Checkout Statuses and Failure Reasons

Use this page to decide what to do with a checkout from its status and, when it failed, from its failure reasons. The hosted page, the iframe and the Payin SDK all report the same values.

Before you start

You read checkouts with Get Checkout, Search Checkouts or the checkout-status-changed webhook. The Payins Overview explains checkouts and checkout transactions.

Checkout status

Status	Meaning	Final?	What to do
`PENDING`	Created and not paid yet. No charge is in flight.	No	Wait for the buyer, charge it yourself with a saved instrument, or send it to a terminal if the buyer pays in person.
`PROCESSING`	A charge is in flight, including a 3D Secure challenge the buyer has not finished.	No	Wait. Do not create a second checkout for the same order.
`PAID`	The charge succeeded. `chargedAmount` and `succeededTransactionId` are set.	Yes	Fulfil the order.
`FAILED`	The last charge was declined or could not be made. `errorTransaction` says why.	No, while `expiresAt` has not passed	See Charging a failed checkout again.
`EXPIRED`	`expiresAt` passed before the checkout was paid.	Yes	Create a new checkout if the buyer still wants to pay.
`UNKNOWN`	The charge was never confirmed as succeeded or failed. The checkout is locked against further charges.	Yes	Do not charge the buyer again and do not cancel the order. Contact Payment Labs support with the checkout ID.

Two details matter when you read these values:

Expiry. A checkout past its expiresAt can no longer be paid, but its status can stay PENDING or FAILED. Compare expiresAt with the current time instead of relying on the status alone.
Subscription checkouts. Checkouts that Payment Labs creates to bill a subscription do not appear in Search Checkouts and do not send checkout-status-changed. Follow them through the subscription events instead. See Subscriptions.

Checkout transaction status

Every charge attempt creates a checkout transaction (ST-…). To follow the latest attempt, read the checkout's status; succeededTransactionId names the successful transaction, and errorTransaction the last failed one. List Checkout Transactions returns every attempt.

Status	Meaning
`PENDING`	The charge was accepted and is being processed.
`PENDING_3DS`	The issuer asked for 3D Secure and the buyer has not completed it.
`SUCCEEDED`	The money was taken. Only a `SUCCEEDED` transaction can be refunded.
`FAILED`	The charge did not succeed. This also covers charges that were cancelled, returned or never confirmed. Read the checkout's status to tell a decline (`FAILED`) from an unconfirmed charge (`UNKNOWN`).

Failure reasons

When a checkout is FAILED, errorTransaction describes the failed attempt:

{
  "status": "FAILED",
  "errorTransaction": {
    "transactionId": "ST-01JBX8C4D6F8G0H2J4K6M8N0P2",
    "errorReason": "CHARGE_INSTRUMENT_ERROR",
    "extendedErrorReason": "INSUFFICIENT_FUNDS",
    "checkoutInstrumentId": "SI-01JBX8B1C3D5E7F9G1H3J5K7M9",
    "instrumentType": "payment-card-1"
  }
}

The top-level errorReason on the checkout is deprecated. Read errorTransaction.errorReason instead.

`errorReason`

The category of the failure. It is always present on a failed attempt.

Value	Meaning	What to tell the buyer
`MISSING_INSTRUMENT`	No usable payment method reached the charge: none was provided, or the saved one is no longer available.	Choose or enter a payment method.
`INVALID_INSTRUMENT`	The payment details did not pass validation, for example a card number, expiry date or billing address that does not match what the bank holds.	Check the details, including the billing address on file with the bank.
`CHARGE_INSTRUMENT_ERROR`	The bank or card network declined the charge.	Use another payment method, or contact the bank.
`APPLICATION_ERROR`	Payment Labs could not process the charge. Payment Labs is notified automatically.	Try again later.

`extendedErrorReason`

The specific cause, when the bank or card network reports one. It can be absent. New values can be added, so handle values you do not recognise by falling back to errorReason.

Value	Meaning
`INSUFFICIENT_FUNDS`	The account does not have enough funds.
`EXPIRED_CARD`	The card's expiration date has passed.
`INVALID_CVV`	The security code was wrong.
`DO_NOT_HONOR`	The issuer declined without giving a reason.
`TRANSACTION_NOT_PERMITTED`	The card does not allow this kind of transaction.
`RESTRICTED_CARD`	The card is restricted, for example by region or account status.
`DUPLICATE_TRANSACTION`	The same charge was submitted twice.
`INVALID_ACCOUNT_NUMBER`	The card or account number does not exist.
`INVALID_AMOUNT`	The amount is out of range or over the card's limit.
`INVALID_CURRENCY`	The currency is not accepted.
`CALL_ISSUER`	The issuer wants the cardholder to contact them.
`ADDRESS_VERIFICATION_FAILED`	The billing address does not match the issuer's records.
`MERCHANT_RULE_VALIDATION`	A rule configured for your account blocked the charge.
`THREE_D_SECURE_REQUIRED`	The issuer requires 3D Secure and it was not completed.
`THREE_D_SECURE_FAILED`	The 3D Secure authentication was rejected.
`THREE_D_SECURE_EXPIRED`	The buyer did not finish 3D Secure in time.
`NEW_ACCOUNT_INFO_AVAILABLE`	The issuer holds newer card details than the ones used. Ask the buyer to enter the card again.
`PAYMENT_CANCELLED_BY_CARDHOLDER`	The cardholder withdrew permission to bill this card. Do not charge it again.
`RETRY_LATER`	The charge could not be approved now but may succeed later.
`PROCESSOR_UNAVAILABLE`	The payment network could not be reached.
`UNKNOWN_ERROR`	No usable reason was reported.

Charging a failed checkout again

A FAILED checkout can be charged again while its expiresAt has not passed and none of its attempts is still in flight or unconfirmed.

The buyer. After a failure the hosted page, the iframe and the Payin SDK show the result and do not offer another attempt on the same checkout. To let the buyer try again, create a new checkout for the same order and send them the new link or ID.
You, with a saved instrument. Call Charge Checkout on the same checkout. See Saved Cards and Merchant-Initiated Charges.
You, on a terminal. For an in-person payment, send the same checkout to the terminal again with Charge Checkout. See POS Terminals.

A PAID, EXPIRED or UNKNOWN checkout cannot be charged again. Charge Checkout on one of them returns 423 NOT_EDITABLE.

Next steps

Refunds
Credit Card Payin Test Values to produce FAILED and UNKNOWN checkouts in sandbox