Error reasons
Why a payment was declined or failed, and what you or your customer can do about it.
When a payment isn't successful, the API still responds with HTTP status 200 OK or 201 Created, but the transaction status is error. The transaction tells you why in two fields:
outcomes: the structured result of each stage of the payment, such as the status and response code of the authorisation. Base your logic on these.reason: a short text that explains why the payment was refused. Show it in your logs or to your support team.
{
"status": "error",
"transactions": [
{
"status": "error",
"payment_method": "credit-card",
"reason": "Do not honor",
"outcomes": {
"processing": {
"status": "declined",
"response_code": "05",
"response_code_description": "Do not honor"
}
}
}
]
}We recommend outcomes over reason. Its statuses and codes are fixed values, while reason is free text. It also tells a decline apart from a technical error, and tells you when to retry.
Outcomes
outcomes holds an object for each stage the payment went through. A stage that didn't run, or doesn't apply, isn't in it. See Get an order in the API reference for all fields.
Processing
outcomes.processing is the result of the authorisation with the card scheme and the card issuer. Its status is always present:
| Status | Meaning | What to do |
|---|---|---|
accepted | The authorisation was approved. | Nothing. |
declined | The issuer or card scheme declined the payment. | Check response_code and the decline reasons. Don't retry with the same card unless merchant_advice_code allows it. |
soft_declined | The issuer asks for authentication. | Retry the payment with 3D Secure. |
error | A technical error at the card network or Rabobank. | Check error_description. Your customer can try again or use another payment method. |
If the merchant_advice_code field is populated it is advised to follow the advise from the scheme. The most common ones:
| Code | Advice |
|---|---|
01 | New account information is available. Ask your customer for their new card details. |
02 | The payment can't be approved now. Try again later. |
03 | Don't try again. |
21 | The cardholder cancelled the payment agreement. Stop your recurring payments. |
See the documentation of Mastercard for all codes.
Decline reasons
When the issuer or card scheme declines a payment, outcomes.processing.response_code_description is one of the texts below. The transaction reason holds the same text.
The Source column shows who refused the payment:
- Issuer: the card issuer (your customer's bank). Your customer can usually solve it with their bank, or by using another card or payment method.
- Card scheme: the card scheme network, such as Visa or Mastercard, for example because the payment couldn't be routed.
| Source | Reason | Description |
|---|---|---|
| Issuer | Invalid card number | The card issuer can't validate the card number. |
| Issuer | Format error | The card issuer doesn't recognise the transaction details. Your customer should check the details and try again. |
| Issuer | Not supported | The card issuer declined the payment, possibly because of a hold on the card. |
| Issuer | Insufficient funds/over credit limit | The account has insufficient funds or exceeds its credit limit. Your customer can add funds or use another payment method. |
| Issuer | Transaction not permitted to issuer/cardholder | The payment isn't permitted for this issuer or cardholder. Your customer should use another payment method. |
| Issuer | Transaction not permitted to acquirer/terminal | The card issuer doesn't permit this payment on this card or account. Your customer can use another payment method or contact their bank. |
| Issuer | Exceeds withdrawal amount limit | The amount exceeds the card's withdrawal limit. Your customer can try again after solving it with their bank, or use another payment method. |
| Issuer | Restricted card | The card is restricted and can't be used for this payment, for example because of an embargo. |
| Issuer | Exceeds withdrawal count limit / Soft-decline (Mastercard) | Mastercard: authentication is required. If the payment falls under PSD2 and didn't go through 3-D Secure, retry it with 3-D Secure. This is a soft decline. |
| Issuer | Allowable number of PIN tries exceeded | The wrong PIN was entered too many times. Your customer should try again or use another payment method. |
| Issuer | Life cycle | The payment can't be processed because of the card's life cycle. |
| Issuer | Domestic debit transaction not allowed | Domestic debit payments aren't allowed for this payment. |
| Issuer | Fraud/Security (Mastercard) | Mastercard: the card issuer flagged the payment as a possible fraud or security risk. |
| Issuer | Cryptographic failure | The cryptographic process failed. |
| Issuer | Authorization system or issuer system inoperative | The authorisation system or the issuer's system is unavailable. Your customer should try again or use another payment method. |
| Issuer | Additional customer authentication required (Visa) | Visa: authentication is required. If the payment falls under PSD2 and didn't go through 3-D Secure, retry it with 3-D Secure. This is a soft decline. |
| Issuer | Refer to card issuer | Contact the card issuer for further instructions. |
| Issuer | Invalid merchant | The card issuer refused the payment. Your customer should ask their bank for clarification and can try again once it's solved. |
| Issuer | Pick up card (no fraud) | The issuer asks to confiscate the card, without suspicion of fraud. |
| Issuer | Do not honor | A generic refusal with several possible causes. Your customer should ask their bank for clarification. |
| Issuer | Error | The payment couldn't be authorised. Your customer can try again or use another payment method. |
| Issuer | Invalid transaction | The card issuer doesn't allow this type of payment on this card or account, for example a fleet card used for a purchase it isn't meant for. |
| Issuer | Invalid amount | An invalid format or field. This often happens with debit or prepaid cards that can't be used online. |
| Issuer | Invalid account number | The card issuer can't validate the account number. |
| Issuer | Lost card | The card was reported lost. Check your customer's identity and refer them to their bank. |
| Issuer | Stolen card | The card was reported stolen. Check your customer's identity and refer them to their bank. |
| Issuer | Closed account | The account of the card has been closed. |
| Issuer | Not sufficient funds | The account has insufficient funds. Your customer can add funds or use another payment method. |
| Issuer | Expired card | The card has expired. Your customer should correct the expiry date or use another payment method. |
| Issuer | Transaction not permitted to cardholder | The card issuer doesn't permit the payment on this card. Your customer can use another payment method. |
| Issuer | Suspected fraud | The payment is suspected to be fraudulent. |
| Issuer | Exceeds approval amount limit | Your customer exceeded their card limit. They can try again after solving it with their bank. |
| Issuer | Invalid/nonexistent account specified (general) | The card belongs to a new cardholder and hasn't been properly unblocked. |
| Issuer | Restricted card (card invalid in region or country) | The card can't be used in this region or country. |
| Issuer | Security violation | A security violation occurred during the payment. |
| Issuer | Transaction does not fulfill AML requirement | The payment doesn't meet anti-money laundering requirements. |
| Issuer | Exceeds withdrawal frequency limit | Your customer exceeded how often the card can be used. They can use another payment method or try again after solving the limit. |
| Issuer | Blocked, first used or special condition | The card is blocked, new and not activated yet, or temporarily blocked. Your customer can try again after solving it with their bank. |
| Issuer | Negative online CAM, dCVV, iCVV, CVV, etc. results | An online verification method, such as CVV or dCVV, gave a negative result. |
| Issuer | Issuer unavailable | The card issuer is unavailable. Your customer should try again or use another payment method. |
| Issuer | Transaction cannot be completed violation of law | The payment violates a law, so the issuer doesn't allow it. Your customer should use another payment method. |
| Issuer | System malfunction | The issuing bank can't be reached. Your customer should try again or use another payment method. |
| Issuer | Decline for CVV2 failure | The CVV2 check failed. Your customer should try again or use another payment method. |
| Issuer | Account not yet activated | The card or account has been issued, but isn't active yet. |
| Issuer | Allowable number of Pin-entry tries exceeded | The card is locked for PIN entry after too many wrong attempts. This is a security control of the issuer. |
| Issuer | Blocked by cardholder/contact cardholder | The cardholder blocked this card. |
| Issuer | Capture card | The issuer permanently revoked the card and wants it confiscated. This is a hard decline, usually related to fraud. |
| Issuer | Contact card issuer | A generic decline. The cardholder should contact their bank. |
| Issuer | Cryptographic error found in Pin | The encrypted PIN failed the issuer's cryptographic check. Usually a fraud or security decline, or a technical key mismatch. |
| Issuer | CVC contains an invalid amount of characters | The security code doesn't match. |
| Issuer | Invalid response status code | The issuer's reply couldn't be understood. This is a technical error. |
| Issuer | No checking account | The card has no valid checking or current account. This is an issuer or account setup decline. |
| Issuer | No credit account | The card has no active credit facility. This is an issuer or account setup decline. |
| Issuer | No savings account | The payment asked for a savings account that doesn't exist or isn't linked. This is an issuer or account setup decline. |
| Issuer | Pick up card- special condition (fraud account) | The account is confirmed as fraudulent. This is a hard fraud decline. |
| Issuer | Pin incorrect or missing | The PIN was wrong, or missing when it was required. |
| Issuer | Stop all future payments | The cardholder asked their bank to stop all future payments to you. |
| Issuer | Stop this payment | The cardholder asked their bank to block this payment, often because of a cancelled subscription or a dispute. |
| Issuer | Transaction not supported/blocked by issuer | The issuer blocked the payment, or the card product doesn't support it. |
| Issuer | Verification data failed | The security or verification data doesn't match the issuer's records. |
| Card scheme | Policy (Mastercard) | Mastercard: the payment was refused because of a policy violation. |
| Card scheme | Unable to route transaction | The payment can't be routed. This can happen when a test card is used in live mode. Your customer should use another payment method. |
| Card scheme | No such issuer | The card issuer doesn't exist or isn't recognised. |
| Card scheme | Re-enter transaction (Visa) | Visa: the payment can't be processed at the moment. |
| Card scheme | Duplicate transmission detected | The acquirer or issuer received the same authorisation request more than once. |
| Card scheme | Invalid issuer | The card's BIN doesn't belong to a valid issuer. This is a routing or configuration decline. |
| Card scheme | System error | A generic failure at the issuer, acquirer or card network. |
| Card scheme | Unknown | The reason for the decline couldn't be determined. This is a technical or mapping issue. |
Platform errors
When Rabobank or the integration refuses the payment before it reaches the card network, for example because of invalid data in your request, there's no response_code_description. The transaction reason is one of these texts:
| Reason | Description |
|---|---|
| Cancelled | The payment was stopped on the cardholder's instruction. |
| Fail to retrieve card details. Not found | The card data linked to the payment couldn't be found. This is a technical or tokenisation issue. |
| Fail to retrieve card details. Unknown error | The stored card data couldn't be retrieved because of an unexpected internal failure. |
| The request does not adhere to the defined api schema | An integration or validation error. Check your request against the API reference. |
| The server encountered an unexpected condition | A technical issue at a party in the payment chain, such as the gateway, the acquirer or the issuer's 3-D Secure server. |
| Transaction not allowed at terminal | Your account isn't set up for this type of payment. |
| Vault_token was not found | The vault_token in your request doesn't exist. This is an integration or validation error. |
You only get a reason when the status is error. Orders and transactions with status cancelled or expired don't have one.
Response codes
The response code of the card network is in outcomes.processing.response_code, and also in payment_method_details.authorization_iso_response_code. For its meaning, see the documentation of the card scheme.
3-D Secure error reasons
When 3-D Secure authentication fails, the reason is one of these, followed by a transStatusReason code:
| Reason | Meaning |
|---|---|
Fail to start 3ds authentication. | 3-D Secure authentication couldn't be started. |
Fail to authenticate 3ds challenge. | Your customer didn't pass 3-D Secure authentication. |
The transStatusReason code tells you why:
| Code | Description |
|---|---|
01 | Card authentication failed |
02 | Unknown device |
03 | Unsupported device |
04 | Exceeds authentication frequency limit |
05 | Expired card |
06 | Invalid card number |
07 | Invalid transaction |
08 | No card record |
09 | Security failure |
10 | Stolen card |
11 | Suspected fraud |
12 | Transaction not permitted to cardholder |
13 | Cardholder not enrolled in service |
14 | Transaction timed out at the ACS |
15 | Low confidence |
16 | Medium confidence |
17 | High confidence |
18 | Very high confidence |
19 | Exceeds ACS maximum challenges |
20 | Non-payment transaction not supported |
21 | 3RI transaction not supported |
22 | ACS technical issue |
23 | Decoupled authentication required by ACS but not requested by 3DS Requestor |
24 | 3DS Requestor decoupled max expiry time exceeded |
25 | Decoupled authentication was provided insufficient time to authenticate cardholder |
26 | Authentication attempted but not performed by the cardholder |
27–79 | Reserved for future use by EMVCo |
80–99 | Reserved for use by the Directory Server |
See 3D Secure for how authentication works.