LogoLogo
BlogLogin
English
English
  • An Introduction to Saferpay
    • Licensing
      • Legacy licensing
    • Reconciliation
    • Acquirers & Payment Methods
    • Web Shop Plugins and certified partners
      • ePages Beyond
      • ePages NOW
      • Magento 2
      • Odoo
      • PrestaShop
        • PrestaShop User Guide
      • Salesforce Commerce Cloud
      • SAP Commerce Cloud
      • Shopware 6
        • Shopware 6 User Guide - German
        • Shopware 6 User Guide - English
      • WordPress WooCommerce
      • Shopify
    • Supported Languages
    • Common Saferpay terms - Glossary
  • News
    • Changes for transactions without customer presence
    • Changes for the Saferpay Hosted Forms, Fields and Payment Page
  • Quick Links
    • Web Shop Plugins and certified partners
    • Secure PayGate
    • User Administration
    • Payment Page Configuration
    • Risk Management
    • API Authentication
  • Interfaces
    • Payment API (aka JSON API)
    • Management API
    • Backoffice
      • The Home screen
      • Batch Processing
      • Transactions
        • Transaction Details
        • Batch Close
        • Declined transactions
        • Pending authorizations
        • Analytics
        • SEPA Refunds Export
        • Authorization & Payment
        • Credit
      • Risk Management
      • Secure PayGate / Payment Links
      • Secure Card Data
        • Secure Card Data Details
      • Settings
        • JSON API basic/Client Certificate authentication
        • User Administration
        • Payment Page Configuration
      • Online Support
      • User Profile
    • Saferpay OnSite
    • Feedback
  • Integration Guide
    • Integrating Saferpay
    • Ways of integration
      • General Information
        • Data Security and PCI DSS
        • Versioning
        • 3-D Secure
        • PSD2
        • Dynamic Currency Conversion
        • Iframe Integration and CSS
        • Fraud Intelligence
          • Silver
          • Fraud Intelligence Integration
      • Payment Page
        • Payment Page checklist
      • Transaction Interface
        • Recurring Payments
        • Refunds
          • SEPA Refunds
      • Capture and Daily Closing
        • Partial Captures
          • Marketplace
      • Secure Card Data - Tokenization
      • Saferpay Fields
      • Inquire Interfaces
      • Mobile Integration
      • Omni-Channel
      • Mail Phone Order
      • Error Handling
      • API Health Check
      • Saferpay API Specification
    • Payment Methods & Wallets
      • General and special cases
      • Account-to-Account Payments
      • Alipay+
      • Apple Pay
      • American Express
      • Bancontact
      • Billie
      • blik
      • Click to Pay
      • Diners Club International & Discover Card
      • eps
      • giropay
      • Google Pay
      • iDEAL 2.0
      • JCB
      • Klarna Payments
      • Maestro International
      • Mastercard
      • paydirekt
      • PayPal
      • PostFinance Pay
      • Przelewy24
      • Reka
      • SEPA Direct Debit
      • Sofort by Klarna
      • TWINT
      • UnionPay
      • Visa & V PAY
      • WeChat Pay
      • WL Crypto Payments
    • Testing
    • Go-Live
    • Frequently Asked Questions
    • Saferpay Demo
      • Saferpay Demo Environment
      • Saferpay Demo Shop
    • Support
    • Changelog
Powered by GitBook
On this page
  • Http status != 200
  • Failed payments and processor-errors
  • Don't just retry
  • Retry behavior and polling
  • The RequestId and RetryIndicator
  • Common error messages and their meaning

Was this helpful?

  1. Integration Guide
  2. Ways of integration

Error Handling

PreviousMail Phone OrderNextAPI Health Check

Last updated 1 month ago

Was this helpful?

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 , 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 , or the , Saferpay would redirect the payer to the ReturnUrl.Url and also call the Notification.FailNotifyUrl and you simply would proceed, as you would normally. So with the Payment Page, you'd simply execute the and with the Transaction Interface the .

Some direct requests, like with , or , 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": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_DECLINED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "OnGYzfbtEMWMSAlMUh9rb8CdzSlA",
  "ProcessorName": "MasterCard Saferpay Test",
  "ProcessorResult": "05",
  "ProcessorMessage": "Authorization declined"
}

Don't just retry

If a transaction fails, do not just retry the transaction.

Doing an unauthorized retry can lead to additional charges put upon you.

Saferpay does return a recommended Behavior and ErrorName telling you, if you can attempt at a later date:

Behavior
ErrorName
What to do

RETRY

Not important/various

Your request was correct, but could not be processed at this time, but you can reattempt right away.

RETRY_LATER

Not important/various

Your request was correct, but could not be processed at this time.

Reason could be insufficient funds on the card holders bank account, or technical issues on the bank-side.

You can reattempt at a later time. The exact time-frame can vary, depending on the reason. Waiting at least 24h is recommended.

Also note, that you may only attempt 10 times, within 30 days.

OTHER_MEANS

Not important/various

The payment cannot succeed with these means of payment, but may be possible, if others are used.

DO_NOT_RETRY

Not important/various

Your request was not correct. Do not reattempt, it will not work this way. Please also consult the ErrorMessage/ProcessorMessage about the reason.

DO_NOT_RETRY

UPDTAE_CARD_INFORMATION

Your request was not correct. Do not reattempt, it will not work. However the ErrorName indicates, that the card-details may not be up to date and need to be updated (e.g. new expiration-date), in order for the payment to succeed.

More about the meaning

These behaviors and error names specifically apply to the request itself and not necessarily to the payment itself.

As an example:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "3DS_AUTHENTICATION_FAILED",
  "ErrorMessage": "3D-Secure authentication failed",
  "TransactionId": "b5zQ22b6r9zOtAnES2Uxb6KOY14b",
  "OrderId": "4"
}

However, what this does not mean is, that you cannot reattempt the payment itself. Given the above example, a 3D Secure authentication could also fail, if the card holder simply did a mistake. Reattempting the overall payment could lead to a success, if the card holder fixes his/her mistake.

Retry behavior and polling

In some cases, a retry may be the right thing to do, e.g. in case of a timeout and the like. However, please consider the following things:

  1. The processing timeout is 100 seconds. Saferpay communicates with all manner of internal and external systems. Especially external ones can increase the processing-time by a considerable margin. Please wait for 100 seconds, before reattempting a request.

  2. Do not use polling to continiously ask for information! Saferpay prohibits the use of polling. Violating this rule will lead to your account being blocked.

  3. While polling is forbidden, you are allowed to implement a retry mechanic. We'd also recommend, after you have retried the request, to wait for a while, in order to circumvent longer lasting issues. For example, if you haven't gotten a response after 100 seconds, you may retry immediately. If this still fails, you should wait a minute, then retry. If that fails, wait for an hour and so on. This staggered retry mechanic is the best compromise between time and ressource investment.

The RequestId and RetryIndicator

The RequestHeader.RequestId and RequestHeader.RetryIndicator are soely meant for debugging-purposes and indication of retries.

The RequestId is meant to identify this one request. Not the whole payment, only this one request. It has to be generated by the merchant-system. Please make sure, that it is unique for each different request.

If your request fails with a Behavior of RETRY and RETRY_LATER, you may reattempt the request with the same RequestId, but then you should increase the RetryIndicator by one, to indicate, that this is a retry of a previously failed attempt.

The maximum number of retries/value for RetryIndicator is 9.

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 , your application could not authenticate itself against the Saferpay gateway, which could be caused by one, or more of the following things:

  • You are running on the wrong environment, e.g. using a Live account on the test environment and vice versa.

Please make sure, that all of these do match up and are set correctly.

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "AUTHENTICATION_FAILED",
  "ErrorMessage": "Unable to authenticate request",
  "ErrorDetail": [
    "Invalid credentials"
  ]
}

TRANSACTION_ABORTED

This transaction has been aborted by the payer, through clicking the Cancel-button.

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETR",
  "ErrorName": "TRANSACTION_ABORTED",
  "ErrorMessage": "Transaction aborted",
  "TransactionId": "zM9v9SAtlpY5SAYCM0KxbhKzp5Mb",
  "OrderId": "0"
}

3DS_AUTHENTICATION_FAILED

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "3DS_AUTHENTICATION_FAILED",
  "ErrorMessage": "3D-Secure authentication failed",
  "TransactionId": "3fnEh0bnrStzUAWnCWYfAb5C8KCb",
  "PayerMessage": "Card holder information -> Failed",
  "OrderId": "2"
}

NO_CONTRACT:

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETR",
  "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, OR you are executing steps, that already have been executed. For example missing a redirect, or initializing and then authorizing the transaction, without providing the necessary means of payment.

The previous step (e.g. actions by the payer, after he has been redirected) may also still be in

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "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 already happened, as a capture can only happen once.

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_ALREADY_CAPTURED",
  "ErrorMessage": "Transaction already captured"
}

Missing permissions to perform PayPal transactions

If Paypal has not been set up correctly, you will get the following error response, when trying to execute a PayPal payment:

{
    "ResponseHeader": {
        "SpecVersion": "[CURRENT SPECVERSION]",
        "RequestId": "[YOUR REQUESTID]"
    },
    "Behavior": "DO_NOT_RETRY",
    "ErrorName": "TRANSACTION_DECLINED",
    "ErrorMessage": "Transaction declined by acquirer",
    "TransactionId": "[TransactionId]",
    "ErrorDetail":[
        "Check that PayPal was setup as described in the Saferpay integration guide for the PayPal payment method."
    ],
    "ProcessorName": "PayPal",
    "ProcessorResult": "invalid_request",
    "ProcessorMessage": "No permission to set target_client_id",
    "OrderId": "[YOUR ORDERID]"
}

Soft decline/Additional customer authentication required

{ 
  "ResponseHeader": {
    "SpecVersion": "[current SpecVersion]",
    "RequestId": "[unique request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "PAYER_AUTHENTICATION_REQUIRED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "llOKnfAEW57QSAErGdIYbAtAQ1fb",
  "ProcessorResult": "1A",
  "ProcessorMessage": "Additional customer authentication required"
}
{
  "ResponseHeader": {
    "SpecVersion": "[current SpecVersion]",
    "RequestId": "[unique request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "PAYER_AUTHENTICATION_REQUIRED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "dOrvUAAWn16USAU8d08OA10A03SA",
  "ProcessorResult": "65",
  "ProcessorMessage": "Soft decline, SCA required"
}

General decline

The most common rejection you'll probably encounter during normal business is the "General decline", or code "05".

This code is thrown, when the cardholders bank, or the processor refuse to elaborate on the exact reason of the rejection. The only way to get more information would be either for the cardholder to ask his bank, or, if the first option yielded no result, for you -the merchant- to ask your account manager for more details.

{
  "ResponseHeader": {
    "SpecVersion": "[current SpecVersion]",
    "RequestId": "[unique request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_DECLINED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "prYlfSAMbGSttA6h29WWA33p68GA",
  "ProcessorName": "MasterCard Saferpay Test",
  "ProcessorResult": "05",
  "ProcessorMessage": "Authorization declined",
  "OrderId": "1"
}

This example indicates, that the authentication failed for this transaction. The behavior itself applies to this request, in this case the , or . These requests will always yield this exact result, so a retry does not help.

However, you are allowed to voluntarely execute requests, in order to gain information on a transaction. For example, if you haven't gotten any notification, you may execute the , in order to check, if there has been an activity.

Your is incorrect.

Your is incorrect.

Your is incorrect.

This error is thrown, if the failed. Since 3D Secure is an anti-fraud measure, Saferpay will not attempt a transaction, if the authentication is attempted, but ending up failed, which could be an indicator for a payer with stolen card details and malicious intents.

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. You can check these things inside the Saferpay Backoffice under . If something is not correct, please contact your Account Manager at our sales, to solve this issue.

Please see this chapter about .

With it being a 3rd party payment method, , so Saferpay has the permission to perform actions/transactions on your PayPal account.

This is a special rejection, that is exclusive to the PSD2 area. This error means, that this transaction must be secured with Strong Consumer Authentication (SCA), which is most commonly done via .

The whole PSD2-topic is .

3D Secure authentication
the capture and its importance
3D Secure
explained in more detail over here
Saferpay Specification for a list of status codes and parameters
Payment Page
Transaction Interface
Recurring Payments
Refunds
3D Secure
Settings > Terminals
Transaction Authorize
Payment Page Assert
Transaction Authorize
Payment Page Assert
Payment Page Assert
CustomerId
API-User
API-Password
PayPal needs a special setup