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.
Processing
outcomes.processing is the result of the authorisation with the card scheme and the card issuer.
| Field | Description |
|---|---|
status | The result of the authorisation, see below. Always present. |
response_code | The response code of the card network, such as 00 for approved or 05 for do not honor. |
response_code_description | A readable description of response_code. |
merchant_advice_code | Advice of the card scheme on whether and when to retry a declined payment. |
error_description | What went wrong. Only for error without a response of the card network. |
| 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 Paytrim. | 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 Paytrim 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.