Alternate Payments Errors
JSON error responses from the Alternate Payments API include information in the body of the response similar to the following:
Error
{
"liveMode": "true",
"error": {
"code": "1200",
"message": "API call rate exceeded",
"details": [
"The user has sent too many requests in a given amount of time."
]
}
}
Decline
{
"merchantRefNum": "jon-test 10",
"amount": 100,
"currencyCode": "EUR",
"profile": {
"firstName": "jon",
"lastName": "ng",
"email": "jon.ng@sf.test",
"ip": "100.0.0.1"
},
"paysafecard": {
"consumerId": "consumer123",
"countryRestriction": "DE"
},
"shopperUrl": "http://www.amazon.com",
"descriptor": "Jon test",
"liveMode": false,
"txnTime": "2016-03-30T08:34:27Z",
"status": "DECLINED",
"gatewayResponse": {
"code": "800.100.150",
"description": "Waiting for confirmation of non-instant payment. Denied for now.",
"paymentType": "DB"
},
"redirect": {
"url": "https://paysafe-psp-alternatepayments-redirect-simulator.dev.mtl.oneplatform.io/redirect/paysafecard/auths/077a4104066940088dcdafadc7bb961b?shopperUrl=http://www.amazon.com",
"method": "GET",
"postParameters": []
},
"links": {
"rel": "self",
"href": "https://paysafe-psp-alternatepayments-core.dev.mtl.oneplatform.io/v1/accounts/987001111/auths/61d88be2-bd0e-48d6-8435-302cc164d8a8"
},
"id": "61d88be2-bd0e-48d6-8435-302cc164d8a8",
"error": {
"code": "ALTERNATE-PAYMENTS-INT-4",
"message": "Transaction declined by the Gateway Error",
"details": ["Transaction was declined by the gateway."]
}
}
To ease integration and support for developers integrating to our APIs, the error messages that are returned should be verbose enough to correct the problem. The error structure contains a code as well as a human readable message. Additionally, the application error code will be returned in the header as x-application-error-code so it can be easily used by an application without parsing the body.
The error object consists of the following elements:
| Element | Type | Description |
|---|---|---|
| error.code | String | This is the error code. |
| error.message | String | This is a description of the error. |
| error.details | Array of String | if applicable This is a collection of detailed descriptions. |
| error.fieldErrors | Array of fieldError | if applicable This is a list of fields that have problems. |
| error.links | Array of link | if applicable Links to the error documentation. |
| id | String | if applicable This is the is the unique identifier for the related resource. |
| merchantRefNum | String | if applicable This is the identifier provided by the merchant for a transaction. |
| riskReasonCode | String | if applicable This is the associated risk reason. |
| links | Array of link | if applicable The link to the related resource. |
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. |
Alternate Payments Errors
| HTTP Status | Error Code | Message | Details |
|---|---|---|---|
| 402 | ALTERNATE-PAYMENTS-GATEWAY-1 | Transaction canceled at the gateway | The transaction was canceled at the gateway. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-4 | Transaction declined by the gateway | The transaction declined by the gateway. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-5 | Cannot refund an incomplete transaction | The transaction cannot be refunded as the payment status is not finalized. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-6 | Over refund | The total refund amount cannot exceed the original payment amount. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-7 | Payment expired | The payment has expired. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-9 | Risk gateway error | A risk issue was reported by the gateway. |
| 502 | ALTERNATE-PAYMENTS-GATEWAY-10 | Payment type temporarily unavailable due to maintenance | The gateway is temporarily unavailable due to system maintenance activities. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-11 | Over voidauth | The void authorization cannot exceed the amount remaining to settle for the corresponding payment. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-12 | Payment already settled | The payment is already partially/fully settled. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-13 | Transaction not refundable yet | The transaction is not refundable yet. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-14 | Partial settlements not possible | Partial settlements are not possible with the selected payment method. |
ALL decline errors should be mapped in the payment service provider–specific micro-service and mapped to a HTTP 402 error. Any other HTTP 4XX or 5XX code will be considered an ERROR and not a DECLINE reason.