Operation failures

An HTTP request can succeed while the created financial object later reaches a failed state. Handle transport and request failures separately from object status.

Four failure surfaces

HTTP error: no successful operation response was returned. Use error.code and the HTTP error catalogue. If retrying a create operation, preserve the original Idempotency-Key and an equivalent operation-specific effective request identity unless the catalogue requires a corrected request. Keep card-data retries inside the approved PCI boundary.
Payment FAILED: the create call may have returned 201. Use the Payment’s failure_code and failure_message. This Payment is final; a customer retry creates a new Payment with a new key.
Refund FAILED: the Refund exists. Use failure.code and failure.message, retrieve the parent Payment, and check the remaining refundable amount and business intent before creating a new Refund.
Payout FAILED: the Payout is terminal. Use its public failure_code and failure_message, retain the Payout ID and request ID, and reconcile the result before deciding on a distinct business Payout.

Payment and Refund failure codes

Payment failure_code and Refund failure.code use the same public vocabulary below. The meaning column applies to both objects; the action column applies only to a failed Payment. Do not apply that Payment action to a Refund. Keep customer-facing text short and neutral. A Refund never requires a shopper browser action: if a Refund carries a 3D Secure-labelled terminal code, treat it only as a failure reason and do not redirect the customer.

`failure_code`	Meaning	Merchant action for a failed Payment
`not_found`	A required payment operation could not be found.	Retain the Payment and request IDs and contact support.
`processor_error`	The processor returned a transient processing failure.	Create a new Payment after a short delay.
`processor_unavailable`	The processor was temporarily unavailable.	Create a new Payment later.
`generic_decline`	The card was declined without a more specific public reason.	Ask for another card.
`do_not_honor`	The issuer declined the transaction.	Ask for another card.
`issuer_declined`	The issuer declined the transaction.	Ask for another card.
`insufficient_funds`	Available funds were insufficient.	Ask the customer to use another card or resolve the balance.
`invalid_number`	The card number was invalid.	Let the customer correct it or use another card.
`invalid_expiry`	The expiry value was invalid.	Let the customer correct it or use another card.
`expired_card`	The card has expired.	Ask for another card.
`invalid_amount`	The amount was invalid for this payment method.	Check the integration before a new attempt.
`invalid_currency`	The currency was invalid for this payment method.	Check the integration before a new attempt.
`not_permitted`	The transaction is not permitted for this card.	Ask for another card.
`cardholder_limit`	A cardholder limit was exceeded.	Ask for another card or let the customer resolve the limit.
`card_velocity_exceeded`	A card activity limit was exceeded.	Ask for another card or try later as a new attempt.
`lost_card`	The card was reported lost.	Show only a generic decline and ask for another card.
`stolen_card`	The card was reported stolen.	Show only a generic decline and ask for another card.
`suspect_fraud`	The issuer or processor suspected fraud.	Show only a generic decline and ask for another card.
`fraud_filter`	Fraud controls declined the Payment.	Show only a generic decline and ask for another card.
`three_d_secure_failed`	3D Secure authentication failed.	If the customer retries, create a new Payment.
`three_d_secure_timeout`	3D Secure authentication timed out.	If the customer retries, create a new Payment.
`three_d_secure_not_supported`	The card cannot complete the required 3D Secure flow.	Ask for another card.
`three_d_secure_error`	3D Secure could not be completed.	If the customer retries, create a new Payment.

An unknown failure_code is still a terminal Payment failure. Show a neutral decline, offer another card, retain the IDs, and do not expose raw processor details.

Refund failures

When a Refund is FAILED, use the nested failure.code and failure.message for developer handling. The Refund object remains part of the parent Payment’s refunds[] history. Never ask for another card or initiate a browser action from the shared failure code. An unknown failure.code is still a terminal Refund failure: retain the Refund, Payment, and request IDs, show neutral text, and reconcile the parent Payment before deciding whether to create another Refund. Before another Refund:

retrieve the parent Payment;
reconcile amount_refunded and amount_refundable;
confirm that the business still intends to return the amount;
create a distinct Refund with a new key only when appropriate.

Payout failures

FAILED records a definitive Payout failure. Read failure_code and failure_message; these fields are omitted in other states. They use the public operation-failure vocabulary, not raw provider codes. Keep customer copy neutral and retain the Payout ID and the Request-Id from the relevant request. For a known or unknown failure code, do not automatically create another Payout. Retrieve the operation, confirm the business intent and destination, and use a new key only for a deliberately new Payout. An uncertain or lost HTTP response is different: preserve the original key and follow Idempotency.

Get started

Build with Flowlix

Handle failures

API reference

Four failure surfaces

Payment and Refund failure codes

Refund failures

Payout failures

​Four failure surfaces

​Payment and Refund failure codes

​Refund failures

​Payout failures

Four failure surfaces

Payment and Refund failure codes

Refund failures

Payout failures