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 5502 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.

Did you find this page useful?