Error Handling
While executing a successful payment is of the upmost importance for Saferpay, technical difficulties, or just simply a failed transaction, are unavoidable. This chapter will help you understand, how Saferpay handles these cases and how you are able to gather information about what went wrong.

Http status != 200

A NOK, or an http status-code != 200 (OK), does not necessarily mean, that the connection to Saferpay failed. Saferpay uses other status-codes to indicate the error-type and that something has gone wrong in the first place.
However alongside this code, Saferpay will also return a JSON-message, that contains information abou what exactly happened. You should always take a look at the message-body and not just the returned error-code.
Please take a look at the Saferpay Specification for a list of status codes and parameters, in case of an error.

Failed payments and processor-errors

Lets take a look at how you would gather the error-response, that is returned from the processor, in case of a failed payment attempt, or other difficulties.
In the back, Saferpay communicates with a wide array of processors, in order to process payments. In case of an error, or just a simple failed payment, Saferpay does pass the processor-response through to you, so you may know the reason of the failure.
To gather said response, you simply proceed as you would in a success case. So for example in case of the Payment Page, or the Transaction Interface, Saferpay would redirect the payer to the ReturnUrls.Fail (Or Abort in case of an abort) and also call the Notification.FailNotifyUrl and you simply would proceed, as you would with the success-case. So with the Payment Page, you'd simply execute the Payment Page Assert and with the Transaction Interface the Transaction Authorize.
Some direct requests, like with Recurring Payments, or Refunds, also return the error-response right away, as there is no redirect.
Please note, that it also depends on the processor and/or the card holders bank on what information is shared. Saferpay returns as much information as possible to you, but in some cases, the bank simply does not want to share the exact reasons of a failure. In these cases, only the card holder may ask his/her bank for the exact reasons.

Example

An example of a rejected payment could look like this:
HTTP status code: 402 Payment Required
{
"ResponseHeader": {
"SpecVersion": "[current Spec-Version]",
"RequestId": "[your request id]"
},
"Behavior": "ABORT",
"ErrorName": "TRANSACTION_DECLINED",
"ErrorMessage": "Transaction declined by acquirer",
"TransactionId": "OnGYzfbtEMWMSAlMUh9rb8CdzSlA",
"ProcessorName": "MasterCard Saferpay Test",
"ProcessorResult": "05",
"ProcessorMessage": "Authorization declined"
}

Common error messages and their meaning

There are certain error-messages returned by Saferpay, that have a very specific meaning and thus a very specific solution.
Here is a list of common error-messages you may encounter and ways of solving the issue at hand:

AUTHENTICATION_FAILED - "Invalid credentials":

In this case either the CustomerId, JSON API Password, JSON API User, or a combination of all three is not correct! You have to make sure, that all three things belong to the same Saferpay account and are valid/correct.
{
"ResponseHeader": {
"SpecVersion": "[current Spec-Version]",
"RequestId": "[your request id]"
},
"Behavior": "ABORT",
"ErrorName": "AUTHENTICATION_FAILED",
"ErrorMessage": "Unable to authenticate request",
"ErrorDetail": [
"Invalid credentials"
]
}
NO_CONTRACT:
In this case, you are either asking for a payment method, that is not activated on your account, or the requested currency is not set up for you. Please contact your Account Manager at our sales, to solve this issue.
{
"ResponseHeader": {
"SpecVersion": "[current Spec-Version]",
"RequestId": "[your request id]"
},
"Behavior": "ABORT",
"ErrorName": "NO_CONTRACT",
"ErrorMessage": "No contract for the combination of terminal, means of payment/service provider and currency",
"TransactionId": "bAvfOzbpIlI5rAzG74IEA0x3j47b",
"ProcessorResult": "",
"ProcessorMessage": ""
}
TRANSACTION_IN_WRONG_STATE:
This means, that there are steps in the transaction flow you have to execute, before the currently executed one. For example missing a redirect, or initializing and then authorizing the transaction, without providing the necessary means of payment.
{
"ResponseHeader": {
"SpecVersion": "[current Spec-Version]",
"RequestId": "[your request id]"
},
"Behavior": "ABORT",
"ErrorName": "TRANSACTION_IN_WRONG_STATE",
"ErrorMessage": "Invalid action"
}

TRANSACTION_ALREADY_CAPTURED:

This is not so much an error, than it is a warning/information telling you, that the capturing of the transaction has already happened. The transaction did not fail, nor did the capture, it simply just happened, as a capture can only happen once.
Please see this chapter about the capture and its importance.
{
"ResponseHeader": {
"SpecVersion": "[current Spec-Version]",
"RequestId": "[your request id]"
},
"Behavior": "ABORT",
"ErrorName": "TRANSACTION_ALREADY_CAPTURED",
"ErrorMessage": "Transaction already captured"
}
Copy link
On this page
Http status != 200
Failed payments and processor-errors
Common error messages and their meaning