Card Errors
Every transaction journey starts with the creation of a payment handle (if one is not already available), which is then followed by a call to process the actual transaction. This page provides more information about potential errors that may arise during the creation of a payment handle, as well as the errors that could occur when processing the transaction itself.
Payment Handle Errors
JSON error responses returned from the Payments API during the creation of a payment handle include information in the body of the response similar to the following:
{
"error": {
"code": "5068",
"message": "Field error(s)",
"details": [
"Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected."
],
"fieldErrors": [
{
"field": "billingAddress.street",
"error": "size must be between 0 and 50"
}
]
}
}
| Error Code | Description | Additional Information |
|---|---|---|
| 5100 | 3DS Enrollment status check failed | threedEnrollment status is N |
| 5101 | 3DS Enrollment status check failed | threedEnrollment status is U |
| 5102 | Failed as response from wallet is WALLET_FAILED | Response from wallet is WALLET_FAILED (For Embedded Finance Flow. Not for standard card flow) |
| 5103 | 3DS service failed | Response status from 3dSecureApi is FAILED |
| 5104 | 3DS Enrollment status check failed | threedEnrollment from 3dSecureApi is N |
| 5105 | 3DS Enrollment status check failed | threedEnrollment from 3dSecureApi is U |
| 5106 | Risk rule failed | threedsResult from 3dSecureApi is N |
| 5107 | Risk rule failed | threedsResult from 3dSecureApi is R |
| 5108 | Risk rule failed | threedsResult from 3dSecureApi is U |
| 5109 | deviceFingerprintingId is null | deviceFingerprintingId is null |
| 5110 | deviceFingerprintingId is null | deviceFingerprintingId is null |
| 5111 | Risk rule failed | signatureStatus is Y and threedResult is N in authentication response |
| 5112 | Risk rule failed | threedResult response is U in authentication response |
| 5113 | Risk rule failed | threedResult response is E in authentication response |
| 5114 | Risk rule failed | signature status is N in authentication response |
| 5115 | Risk rule failed | threedResult is N |
| 5116 | Risk rule failed | threedResult is U |
| 5117 | Risk rule failed | threedResult is R |
| 5118 | state is null | state is missing |
| 5119 | holderName is null | holderName is missing |
| 5120 | Risk rule failed | Third party 3ds service throws error |
| 5121 | Risk rule failed | Threeds api failed |
| 5124 | Payment Hub Risk Rule Failed - threeDResult is N after Challenge/OTP Flow. | threeDResult is N after the challenge/OTP flow |
| 5125 | Payment Hub Risk Rule Failed - threeDResult is U after Challenge/OTP Flow. | threeDResult is U after the challenge/OTP flow |
Please note that if you are using the Paysafe JS SDK or the Paysafe Checkout SDKs, the creation of payment handles is managed internally by these SDKs. You will receive either a payment handle token or an error message directly from the SDK. If the internal payment handle calls fail, refer to Paysafe JS: Tokenize to understand the potential errors you may encounter with these SDKs.
Transaction Errors (payments, verifications, refunds, original credits)
JSON error responses returned from the Payments API during the card payment include information in the body of the response similar to the following examples:
{
"error": {
"code": "5068",
"message": "Field Error(s)",
"details": [
"Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected."
],
"fieldErrors": [
{
"field": "billingDetails.state",
"error": "Invalid state code for US"
}
]
},
"id": "77a7487a-5acf-42b4-9e9a-aa15ff36d7ab"
}
{
"error": {
"code": "3022",
"message": "The card has been declined due to insufficient funds."
},
"id": "e6c7e4bd-4bb5-4001-8616-91e403a97155",
"merchantRefNum": "53a7ab84-2e2f-45d4-8004-b01a4dae6a83",
"settleWithAuth": true
"cvvVerification": "NOT_PROCESSED",
"gatewayResponse": {
"cvvVerification": "NOT_PROCESSED"
}
}
{
"error": {
"code": "3009",
"message": "Your request has been declined by the issuing bank.",
"additionalDetails": [
{
"type": "ADVICE",
"code": "ADVICE-03",
"message": "Revalidate payment information. Please do not retry more than 10 times over 30 days."
}
]
},
"id": "b0d1d3c0-f3b3-4743-9bff-16aec8e56022",
"merchantRefNum": "bcc8fbad-9b9a-4df9-a54c-b98ddcefa282",
"settleWithAuth": true
}
Where possible, we provide additional information on the advice and the ISO response returned by the payment network.
The error object consists of the following elements:
| Element | Type | Description | Required? | |
|---|---|---|---|---|
| code | string | The error code. Also shown in the X-Application-Status-Code response header. | Yes | |
| message | string | The error message describing the error. | Yes | |
| details | string array | Details of any parameter value errors in the body of the request. | Optional | |
| fieldErrors | object array | Details of any parameter value errors in the body of the request. | Optional | |
additionalDetails | object | Additional details about the error as provided by the processor/acquirer | Optional | |
The following information summarizes all possible errors returned by the Payments API, including HTTP Status Codes.
HTTP Status Code Summary
| Code Range | Description |
|---|---|
| 1xx: Informational | Communicates transfer protocol–level information. |
| 2xx: Success | Indicates that the client’s request was accepted. |
| 3xx: Redirection | Indicates that the client must take some additional action in order to complete the request. |
| 4xx: Client Error | Indicates that the client has made an error with the request. |
| 5xx: Server Error | Indicates that an error occurred on the server side. |
Common HTTP Response Status Codes
| Code | Description |
|---|---|
| 200 OK | Everything worked as expected. |
| 201 Created | The request was successful. Paysafe created a new resource and the response body contains the representation. |
| 202 Accepted | This indicates that the client’s request will be handled asynchronously. It tells the client that the request appears valid, but it still may have problems once it is processed. |
| 204 No Content | This is usually returned in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the body of the response message. |
| 304 Not Modified | The client's cached version of the representation is still up to date. |
| 400 Bad Request | This often indicates that a required parameter is missing or that a parameter is invalid. This is a generic client-side error status, used when no other 4xx error code is appropriate. |
| 401 Unauthorized | This indicates that the client tried to operate on a protected resource without providing the proper authorization. They may have provided the wrong credentials or none at all. |
| 402 Payment Required | The parameters were valid but the request failed. |
| 404 Not Found | The requested resource does not exist. |
| 405 Method Not Allowed | The client tried to POST or PUT to a resource that would not accept it. |
| 415 Unsupported Media Type | The request is in a format not supported by the requested resource for the requested method. |
| 429 Too Many Requests | The application is sending too many simultaneous requests. |
| 500 Internal Server Error | An error occurred with an internal server. |
| 502 External Server Error | We received an invalid response from the upstream gateway in attempting to fulfill the request. |
Common Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 500 | 1000 | An internal error occurred. |
| 502 | 1001 | An error occurred with the external processing gateway. |
| 500 | 1002 | An internal error occurred. |
| 500 | 1003 | An internal error occurred. |
| 500 | 1007 | An internal error occurred. |
| 500 | 1008 | An internal error occurred. |
| 429 | 1200 | The API call has been denied as it has exceeded the permissible call rate limit. |
| 401 | 5000 | Your merchant account authentication failed. Either your store ID/password is invalid or the IP address from which you are sending the transaction has not been authorized. |
| 400 | 5001 | The submitted currency code is invalid or your account does not support this currency. |
| 400 | 5003 | You submitted an invalid amount with your request. |
| 400 | 5004 | You submitted an invalid account type with your request. |
| 400 | 5005 | You submitted an invalid operation type with your request. |
| 400 | 5010 | The submitted country code is invalid. |
| 400 | 5016 | The merchant account you provided cannot be found. |
| 400 | 5017 | The merchant account you provided is disabled. |
| 402 | 5021 | Your transaction request has been declined. |
| 400 | 5023 | The request is not parsable. |
| 409 | 5031 | The transaction you have submitted has already been processed. |
| 401 | 5040 | Your merchant account is not configured for the transaction you attempted. |
| 400 | 5042 | The merchant reference number is missing or invalid or it exceeds the maximum permissible length. |
| 400 | 5068 | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. |
| 404 | 5269 | The ID(s) specified in the URL do not correspond to the values in the system. |
| 403 | 5270 | The credentials provided with the request do not have permission to access the requested data. |
| 406 | 5271 | You requested a response in the 'Accept' header that is in an unsupported format. |
| 406 | 5272 | The 'Content-Type' you specified in request header was submitted in an unsupported format. |
| 404 | 5273 | Your client reached our application but we were unable to service your request due to an invalid URL. |
| 401 | 5275 | The authentication credentials provided with the request have expired. |
| 401 | 5276 | The authentication credentials provided with the request provided have been disabled. |
| 401 | 5277 | The authentication credentials provided with the request have been locked due to multiple authentication failures. |
| 401 | 5278 | The authentication credentials provided with the request were not accepted for an unknown reason. |
| 401 | 5279 | The authentication credentials are invalid. |
| 401 | 5280 | The required authentication credentials were not provided. |
| 405 | 5281 | The request uses an action (e.g., GET, POST, or PUT) that is not supported by the resource. |
| 400 | 5501 | The profile does not have an active credit card. |
| 400 | 5500 | Either the payment token is invalid or the corresponding profile or bank account is not active. |
Authorization Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | 1000 | Internal Error |
| 500 | 1000 | Internal Error |
| 502 | 1000 | Internal Error |
| 502 | 1001 | External Gateway Error |
| 500 | 1002 | Database Error |
| 500 | 1002 | Internal error |
| 500 | 1007 | Gateway Error |
| 500 | 1007 | Internal Error. |
| 504 | 1020 | Gateway timeout |
| 400 | 3002 | You submitted an invalid card number or brand or combination of card number and brand with your request. |
| 400 | 3004 | The zip/postal code must be provided for an AVS check request. |
| 400 | 3005 | You submitted an incorrect CVV value with your request. |
| 400 | 3006 | You submitted an expired credit card number with your request. |
| 402 | 3007 | Your request has failed the AVS check. Note that the amount has still been reserved on the customer's card and will be released in 3-5 business days. Please ensure the billing address is accurate before retrying the transaction. |
| 400 | 3008 | You submitted a card type for which the merchant account is not configured. |
| 402 | 3009 | Your request has been declined by the issuing bank. |
| 402 | 3011 | Your request has been declined by the issuing bank because the card used is a restricted card. Contact the cardholder's credit card company for further investigation. |
| 402 | 3012 | Your request has been declined by the issuing bank because the credit card expiry date submitted is invalid. |
| 402 | 3013 | Your request has been declined by the issuing bank due to problems with the credit card account. |
| 402 | 3014 | Your request has been declined - the issuing bank has returned an unknown response. Contact the card holder's credit card company for further investigation. |
| 402 | 3015 | The bank has requested that you process the transaction manually by calling the cardholder's credit card company. |
| 402 | 3016 | The bank has requested that you retrieve the card from the cardholder - it may be a lost or stolen card. |
| 402 | 3017 | You submitted an invalid credit card number with your request. |
| 402 | 3018 | The bank has requested that you retry the transaction. |
| 402 | 3019 | Your request has failed the CVV check. Please note that the amount may still have been reserved on the customer's card, in which case it will be released in 3-5 business days. |
| 402 | 3020 | The bank has requested that you retry the transaction. |
| 402 | 3022 | The card has been declined due to insufficient funds. |
| 402 | 3023 | Your request has been declined by the issuing bank due to its proprietary card activity regulations. |
| 402 | 3024 | Your request has been declined because the issuing bank does not permit the transaction for this card. |
| 400 | 3025 | The external processing gateway has reported invalid data. |
| 402 | 3027 | The external processing gateway has reported a limit has been exceeded. |
| 502 | 3028 | The external processing gateway has reported a system error. |
| 402 | 3029 | The external processing gateway has rejected the transaction. |
| 402 | 3030 | The external processing gateway has reported the transaction is unauthorized. |
| 402 | 3035 | Your request has been declined due to exceeded PIN tries. |
| 402 | 3036 | Your request has been declined due to an invalid issuer. |
| 402 | 3037 | Your request has been declined because it is invalid. |
| 402 | 3039 | Your request has been declined due to an invalid authentication value. |
| 402 | 3040 | Your request has been declined because the request type is not permitted on the card. |
| 402 | 3041 | Your request has been declined due to a timeout. |
| 402 | 3042 | Your request has been declined due to a cryptographic error. |
| 402 | 3054 | The transaction was declined due to suspected fraud. |
| 402 | 3057 | Please tell cardholder to call the issuer. Do not retry transaction. |
| 402 | 3060 | Your request has been declined because Strong Customer Authentication is required. |
| 400 | 3061 | Invalid initial transaction reference |
| 400 | 3073 | Your request has been declined due to closed customer account. |
| 400 | 3703 | The external gateway has reported that you have submitted an invalid amount with your request. |
| 402 | 4001 | The card number or email address associated with this transaction is in our negative database. |
| 402 | 4002 | The transaction was declined by our Risk Management department. |
| 400 | 5003 | You submitted an invalid amount with your request. |
| 400 | 5017 | The merchant account submitted with your request is disabled. |
| 400 | 5023 | Request body not parsable |
| 409 | 5031 | Duplicate merchant reference |
| 409 | 5031 | The transaction you have submitted has already been processed. |
| 400 | 5034 | You submitted an invalid email address with your request. |
| 400 | 5037 | You submitted an invalid zip/postal code with your request. |
| 401 | 5040 | Your merchant account is not configured for the transaction you attempted. |
| 500 | 5050 | An error occurred with your merchant account configuration. |
| 400 | 5068 | Field Error(s) |
| 400 | 5068 | Field error(s) |
| 403 | 5270 | Unauthorized access |
| 415 | 5272 | Unsupported 'Content-Type' |
| 400 | 5500 | Either the payment token is invalid or the corresponding profile or credit card is not active. |
| 500 | 9000 | Your transaction request could not be processed because your merchant account has no available child accounts for load balancing. |
| 400 | PAYMENTHUB-1 | The submitted payment type and currency code combination is not supported for your account |
Void (Authorization Reversal) Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | 3500 | The confirmation number included in this request could not be found. |
| 402 | 3501 | The requested Void (Authorization Reversal) amount exceeds the remaining Authorization amount. |
| 402 | 3502 | You cannot process an Void (Authorization Reversal) transaction against an Authorization that has been settled. |
| 402 | 3503 | The Void (Authorization Reversal) transaction is not supported for the card type used for the Authorization you are attempting to reverse. |
| 402 | 3504 | The external processing gateway for which your merchant account is configured does not support partial Voids (Authorization Reversals). |
| 500 | 3505 | The Void (Authorization Reversal) could not be completed. |
| 402 | 3506 | The Void (Authorization Reversal)amount exceeds the remaining amount of the Authorization. |
| 402 | 3507 | The Authorization does not support a partial Void (Authorization Reversal). |
Settlement Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | 3200 | You have submitted an invalidly formatted Authorization ID for this Settlement. |
| 404 | 3201 | The Authorization ID included in this Settlement request could not be found. |
| 402 | 3202 | You have exceeded the maximum number of Settlements allowed. |
| 402 | 3203 | The Authorization is either fully settled or cancelled. |
| 402 | 3204 | The requested Settlement amount exceeds the remaining Authorization amount. |
| 402 | 3205 | The Authorization you are attempting to settle has expired. |
| 402 | 3206 | The external processing gateway has rejected the transaction. |
| 402 | 3207 | Due to issuer policies, this type of transaction is not allowed |
Refund Errors
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 402 | 3402 | The requested Refund amount exceeds the remaining Settlement amount. |
| 402 | 3403 | You have already processed the maximum number of refunds allowed for this Settlement. |
| 402 | 3404 | The Settlement has already been fully refunded. |
| 402 | 3405 | The Settlement you are attempting to Refund has expired. |
| 402 | 3406 | The Settlement you are attempting to Refund has not been batched yet. There are no settled funds available to Refund. |
| 400 | 3407 | The Settlement referred to by the transaction response ID you provided cannot be found. |
| 400 | 3408 | You have submitted an invalidly formatted response ID for the original Purchase or Settlement. |
| 402 | 3412 | The Refund transaction you attempted was not permitted because your merchant account is in overdraft. |
| 402 | 3413 | The requested Refund amount exceeds the permissible Visa credit ratio. |
| 400 | 3414 | The Refund referred to by the transaction response ID you provided cannot be found. |
| 402 | 3415 | You cannot cancel this transaction as it is no longer in a pending state. |
| 402 | 3416 | The external processing gateway for which your merchant account is configured does not support partial Settlements. |
| 402 | 3417 | There is already another request being processed on the transaction referenced for this request. |
| 402 | 3418 | The external processing gateway for which your merchant account is configured does not support partial Credits. |
| 402 | 3419 | This type of transaction cannot be refunded. |
| 500 | 3420 | An error occurred while processing the purchase return authorization. |
| 402 | 3421 | The purchase return authorization has been declined by the issuing bank. |
| 402 | 3422 | The purchase return authorization has failed. |
| 500 | 3423 | An error occurred while processing the purchase return authorization reversal. |
| 500 | 3424 | Something went wrong with the purchase return authorization, please retry the transaction. |
Merchant Advice Codes
| HTTP Status | Type | Code | Message |
|---|---|---|---|
| 402 | ADVICE | ADVICE-01 | Issuer will never approve. Please do not retry. |
| 402 | ADVICE | ADVICE-02 | Issuer cannot approve at this time. Please do not retry more than 10 times over 30 days. |
| 402 | ADVICE | ADVICE-03 | Revalidate payment information. Please do not retry more than 10 times over 30 days. |
| 402 | ADVICE | ADVICE-04 | Carholder needs to contact issuer. Please do not retry more than 10 times over 30 days. |
| 402 | ADVICE | ADVICE-05 | Token requirements not fulfilled for this token. Obtain a new token. Please do not retry more than 10 times over 30 days. |
| 402 | ADVICE | ADVICE-06 | Undefined response. |
| 402 | ADVICE | ADVICE-07 | Merchant doesn't qualify for Product code. Modify transaction parameters or do not retry. |
| 402 | ADVICE | ADVICE-08 | Please retry after 1 hour. |
| 402 | ADVICE | ADVICE-09 | Please retry after 24 hours. |
| 402 | ADVICE | ADVICE-10 | Please retry after 48 hours. |
| 402 | ADVICE | ADVICE-11 | Please retry after 4 days. |
| 402 | ADVICE | ADVICE-12 | Please retry after 6 days. |
| 402 | ADVICE | ADVICE-13 | Please retry after 8 days. |
| 402 | ADVICE | ADVICE-14 | Please retry after 10 days. |
| 402 | ADVICE | ADVICE-42 | Sanctions Scoring Service: Score Exceeds Applicable Threshold Value |
ISO Response Codes
| Type | Code | Message |
|---|---|---|
| ISO_RESPONSE | 00 | APPROVED |
| ISO_RESPONSE | 01 | Refer to Issuer |
| ISO_RESPONSE | 03 | Invalid Merchant |
| ISO_RESPONSE | 04 | Pick up |
| ISO_RESPONSE | 05 | Do not honour |
| ISO_RESPONSE | 08 | Honour with Identification |
| ISO_RESPONSE | 10 | Partial Approval |
| ISO_RESPONSE | 12 | Invalid Transaction |
| ISO_RESPONSE | 13 | Invalid Amount |
| ISO_RESPONSE | 14 | Invalid PAN |
| ISO_RESPONSE | 15 | Invalid issuer |
| ISO_RESPONSE | 30 | Format Error |
| ISO_RESPONSE | 41 | Lost card |
| ISO_RESPONSE | 43 | Stolen card |
| ISO_RESPONSE | 51 | Non-sufficient funds |
| ISO_RESPONSE | 54 | Expired card |
| ISO_RESPONSE | 55 | Bad PIN |
| ISO_RESPONSE | 57 | Transaction not allowed |
| ISO_RESPONSE | 58 | Transaction not permitted |
| ISO_RESPONSE | 61 | Exceeds withdrawal limit |
| ISO_RESPONSE | 62 | Restricted Card |
| ISO_RESPONSE | 65 | Exceeded frequency limit |
| ISO_RESPONSE | 70 | Contact Card Issuer |
| ISO_RESPONSE | 71 | PIN Not Changed |
| ISO_RESPONSE | 75 | Exceeded PIN tries |
| ISO_RESPONSE | 76 | Invalid To Account |
| ISO_RESPONSE | 77 | Invalid From Account |
| ISO_RESPONSE | 79 | Life cycle Decline |
| ISO_RESPONSE | 82 | Policy Decline |
| ISO_RESPONSE | 83 | Fraud/Security Decline |
| ISO_RESPONSE | 84 | Invalid Authorization Life Cycle |
| ISO_RESPONSE | 85 | No reason to decline a request |
| ISO_RESPONSE | 86 | Cannot verify PIN |
| ISO_RESPONSE | 87 | Purchase Amount Only, No cash back allowed |
| ISO_RESPONSE | 88 | Cryptographic Error |
| ISO_RESPONSE | 89 | PIN unacceptable |
| ISO_RESPONSE | 91 | Request Destination not reachable |
| ISO_RESPONSE | 92 | Response Destination not reachable |
| ISO_RESPONSE | 94 | Already Reversed |
| ISO_RESPONSE | 96 | Internal Error |
Was this page helpful?
On this Page