Saferpay generally offers a refund functionality from the start through the Saferpay Backoffice. However, if automated, or more integrated processes are needed, the JSON-API can be used to execute refunds from the merchants webshop, or ERP-system. This part of the guide covers the process of how to execute refunds through the Saferpay JSON-API, which can be performed in two ways.

Refunds via API, are a feature sub-set of the Transaction Interface.

Saferpay does not check the amount you are submitting, against the initial transaction, per default.

If you want to prevent the API from refunding more, than originally authorized, see this chapter. Also note, that this can only be done with referenced refunds.

Not all payment methods to support a refund functionality. Especially online banking payment methods do not provide refund functionality due to how the money is processed. You can find an overview of the supported features, inside the respective Payment Method chapter.


  • a valid login access with a username and password for the Saferpay Backoffice.

  • one active Saferpay ecommerce terminal

  • Saferpay terminal number (TerminalId parameter) and Saferpay customer number (CustomerId parameter).

  • valid acceptance agreement for credit cards or other payment methods

  • Secure Card Data Module (if refunds are performed using Aliases. Method 2)

Method 1: Referenced refunds

Referenced refunds are performed, by using the Refund request. This request accepts the CaptureId, of the transaction you want to refund!. It is usually -please refer to the respective Payment Method chapter- returned, after you have executed a Capture.

Capture response

  "ResponseHeader": {
    "SpecVersion": "1.21",
    "RequestId": "d66252aacafc19161333916ba87601e5"
  "CaptureId": "W6ttz4AQMIM2tAhI2llEA0E5xCzb_c",
  "Status": "CAPTURED",
  "Date": "2021-07-09T11:48:02.462+02:00"

By passing this ID through to Saferpay, the refund will be linked to the original transaction inside the Saferpay Backoffice:

By clicking on the transaction ID you'll be redirected to the original transaction:

Preventing refunds from exceeding the originally captured amount

If necessary, you can prevent Saferpay from exceeding the originally captured amount. This can prevent multiple refunds and other mishaps, that can cause you to refund more money, than originally charged.

In order to do so, you have to set the Refund.RestrictRefundAmountToCapturedAmount to true.

However, please note the following restrictions:

  • This only works for API SpecVersions 1.25+ !

  • This only works, if you reference a CaptureId and not a TransactionId! Old API-Versions did use the TransactionId, which still works in newer versions, but not in conjunction with this feature. If you migrate from an old version, you must move to the CaptureId, as described in the previous section.

    • Only the amount of the capture is checked here and not the amount of the whole transaction. This can prove problematic, when using Partial Captures. Please see the following example:

    Let's say, that you have a transaction over 100,- and use Partial Captures to capture 50.- , 20.- and 30.-. You can refund these individual parts and Saferpay will make sure, that the amount of these parts will not be exceeded, even if multiple refunds are executed. This means, that you have to refund each individual part, with this option enabled, in order to refund the whole transaction, as Saferpay will not allow you to refund 100.- on just one part (as it is possible without this option enabled). Likewise, if you want to refund 75.- , you first must refund the 50.- and then 25.- of the 30.- or the 20.- and the remaining 5.- from the 30.-. Of course, you can ignore this detail, if you execute a normal capture or just one Partial Capture over the whole transaction amount.

Try it out

You can try it out, by first doing a complete (including the Capture!) transaction, by using the PaymentPage, or Transaction Interface. The refund-option will be displayed, after the Capture has been executed!

Click here for a demo

Method 2: Refunds using an alias

A different method is using an alias obtained through Secure Card Data, which can be obtained in multiple ways.

This request is different from the that of the referenced refunds. When using an alias, the Refund Direct request has to be used.


Due to legal requirements, concerning money laundering - mandating a refund to always reference a previous transaction, which is only possible via method #1; referenced refund (hence the name) -, each non-referenced refund must be manually checked by your acquirer and even then, it is not guaranteed, that they will be approved!

While Refund Direct does offer the possibilities to submit the card number (PAN) directly, it is not allowed to do this without a full PCI-DSS certification. More on that topic can be found in the Data Security and PCI DSS chapter.

Due to the fact, that the original transaction ID is not submitted, like with referenced refunds, the refund will not be linked to the original transaction inside the Saferpay Backoffice!

Try it out!

You can try it out, by first doing a complete (including the Capture!) transaction, by using the PaymentPage, Transaction Interface, or the Secure Alias Store. The refund-option will be displayed, after the Capture has been executed!

Click here for a demo


Like normal transactions, refunds need to be captured/booked by executing the Capture request successfully, if the transaction STATUS is AUTHORIZED.

The actual transfer of money will not be executed if the refund hasn't been captured!

Likewise, if a transaction has been captured, you cannot execute a cancel anymore.

Difference, between Cancel and Refund

At first glance, a cancel and a refund may be very similar and while they come into action in similar situations, they do different things and apply in slightly different circumstances. It is important to know these differences, so you apply both of them in the right situation.

A cancel prevents a customer from being charged, a refund is for situations, where the customer already has been charged.

However, you must know, that a cancel can only be issued as long as the money-flow hasn't been initiated, which usually happens with the capture.

Once the capture has been executed successfully, the money has been deducted from the cardholder and the transaction can no longer be cancelled. In this case you need to issue a refund, to transfer the money back to the cardholders bank account.

Please note, that there are exceptions. Some payment methods initiate the money flow with the capture, some with the Daily Closing.

Not all payment methods do support a refund, or even the cancel. An overview can be found in the respective Payment Method chapter.

Please note, that scheme-/provider-fees do also apply to refunds, making them a bit more expensive. It is indeed wise to only capture, if you are 100% sure, that you want to deliver the goods and that the possibility for a cancel is low.

Additional information

Refunds are basically normal transactions where instead of debiting the cardholders account, you are crediting it. That means, that refunds go through the same authorization-steps as a normal (debit) authorization. Please keep in mind that a refund can also be rejected, though this is very rare.

The refund amount value can differ from the originally authorized (debited) amount. This also applies to referenced refunds. The refund will be regarded as a completely new transaction, with its own set of parameters, like the amount value. It is also possible to do multiple refunds on one transaction, even though the originally authorized amount has been exceeded, per default. Please make sure to keep track of this process, or prevent that behavior on Saferpay side.

Similar to normal transactions, it is possible to submit the parameter "OrderId" inside the "Refund" container. This ID will be forwarded by Saferpay and will show up inside the Saferpay Backoffice (as the Reference number) as well as in your reconciliation-files. This will help you, keeping track of your refunds.

Last updated