Referenced refunds

Customers appreciate the possibility of omnichannel returns, allowing them to return an ecommerce purchase to a physical store, or return their in-store purchase by sending it to your distribution center. With referenced refunds, you can offer omnichannel returns with a minimum of operational burden.

Referenced refunds are not processed synchronously. When you send an API request for a referenced refund, the API response only confirms we received the request. We process the refund asynchronously, and inform you of the result through a webhook.

Refunded amounts are deducted from the in-process funds of the merchant account that processed the original payment. For example, if a sale took place on MerchantAccount_ECOM and the product is returned to MerchantAccount_POS, the funds are taken from the ECOM account.

Requirements

Synchronize your back-end systems

A requirement for omnichannel returns is that you have access to transaction information of all sales channels. For referenced refunds, this transaction information must include the PSP reference.

Ideally you have a central database where you store information from both ecommerce and point-of-sale transactions. If you store the ecommerce and point-of-sale transaction information separately on different systems, these systems must be able read each other's data.

Enable on the company level

To process returns between multiple merchant accounts, in this case omnichannel returns between ecommerce and point-of-sale merchants accounts, you need to contact our Support Team to enable refunds on the company level. You can then use the /payments/{paymentPspReference}/refunds endpoint to submit returns for any merchant account under your company account.

Benefits

Omnichannel referenced refunds offer the following benefits.

• Simpler reconciliation
  On our unified payments platform we assign a unique identifier to each transaction. This identifier is known as the PSP reference. When you issue a referenced refund, you specify the PSP reference of the original payment. In this way, you can match each refund against a payment, regardless of the sales channel. You have the complete audit trail of a payment including any full or partial refunds.

• Better fraud protection
  A referenced refund returns the funds to the payment method that was used for the original payment, not to the card the shopper is presenting in the store or as cash. This helps combat various return fraud types like returning stolen merchandise, receipt fraud, and cross-retailer returns.

• Never more than 100%
  When using referenced refunds, payments cannot be refunded multiple times, or for an amount exceeding 100% of the payment value.

Refund authorization

Refund authorization means that before processing a refund, Adyen checks with the issuer if the shopper's card or account is valid. This happens automatically; you do not have to ask for this in your refund request.

Adyen supports this for:

• American Express
• Discover
• Mastercard
• Visa

As soon as the issuer authorizes the refund, the refund is visible on the shopper's account. This improves customer satisfaction and reduces the number of questions from shoppers about their refund. Also, there are less refund-related chargebacks because issuers usually return the funds to the shopper sooner.

Issuers can decline a refund authorization for reasons like:

• Lost or expired card
• Invalid card number
• Closed account
• Suspected fraud

When a refund authorization is declined, we still try to process the refund.

Pilot to prepare for 2025 changes

Adyen is currently running a pilot where declined refund authorizations are handled differently:

• We do not proceed with the refund. In your Customer Area, the transaction status remains Settled.

• We inform you of the reason for the declined refund authorization in the REFUND, CANCEL_OR_REFUND, and REFUND_WITH_DATA webhooks. The reason parameter in the webhook will a have a value of Authorisation for refund failed with response code followed by the raw response we received.

This improved transparency about the status of a refund enables you to take action sooner, so you can return the funds to the shopper in some other way.

The behavior described above will become the default in 2025. If you want to prepare for that and participate in this pilot, reach out to your Adyen contact or to our Support Team. Note that some card networks charge a refund authorization fee.

Refund options

To issue a full or partial referenced refund, you have these options:

• Terminal API reversal request: your POS app sends a Terminal API ReversalRequest to the payment terminal. The request includes the PSP reference of the original point-of-sale or ecommerce purchase. The terminal generates a receipt, and the funds are returned to the original card or other payment method without the need for the customer to present a card to the payment terminal.

• Server-to-server refund: you make a POST request to the /payments/{paymentPspReference}/refunds endpoint, where paymentPspReference is the PSP reference of the original point-of-sale or ecommerce purchase.

• Refund from your Customer Area: this is a good option if you do not issue refunds often. We describe this in the Account section of our documentation.

Send a Terminal API reversal request

When you make a POS payment, the Terminal API response returns the transaction identifier of the payment in the format tenderReference.pspReference. To make a referenced refund, you specify this transaction identifier in your refund request.

However, the tenderReference is generated by the payment terminal, and is missing for an ecommerce payment. In that case you include only the PSP reference, in the format .pspReference.

You can make a:

• Full refund to return the total value of the purchase to the shopper.
• Partial refund to return part of the purchase to the shopper. For example, when a shopper returns one of the items they purchased. You can also make multiple partial refunds. For example, when a shopper returns several items at different times.

Select a tab to see the parameters that you need to specify for a full referenced refund, or a partial referenced refund.

Refunding an ecommerce payment

An ecommerce payment does have a PSP reference, but the tender reference is missing because it is generated by the terminal. To refund an ecommerce payment, you need to know the PSP reference, the date, and the currency of the original payment.

Send a server-to-server refund request

To return funds to your customer:

1. From the AUTHORISATION webhook, get the pspReference of the authorization you want to refund.

2. Make a POST request to the /payments/{paymentPspReference}/refunds endpoint, where paymentPspReference is the pspReference of the authorization you want to refund.
   

   In your request, include:

   Parameter	Required	Description
   merchantAccount		The name of your merchant account that is used to process the payment.
   amount		The amount that you want to refund. The value must be the same or, in case of a partial refund, less than the captured amount. The currency must match the currency used in the authorization.
   reference		Your reference for the refund, for example to tag a partial refund for future reconciliation. The reference parameter is required for GrabPay refunds.

   The following example shows how to refund EUR 25.00 on an authorization that has the pspReference XB7XNCQ8HXSKGK82.

3. When you receive the /payments/{paymentPspReference}/refunds response, note:

   • paymentPspReference: the PSP reference of the authorization you want to refund.
   • pspReference: Adyen's unique reference associated with this refund request.

   {
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "paymentPspReference": "XB7XNCQ8HXSKGK82",
       "pspReference" : "JDD6LKT8MBLZNN84",
       "reference": "YOUR_UNIQUE_REFERENCE",
       "status" : "received"
   }

4. Wait for the REFUND webhook to learn the outcome of the refund request.

Webhooks

Refunds are not processed synchronously. When you send an API request for a referenced refund, the API response only confirms we received the request.

We process the refund asynchronously, and inform you of the result through a webhook.

• For a Terminal API reversal request, we return a CANCEL_OR_REFUND webhook.
• For a server-to-server refund, we return a REFUND webhook

CANCEL_OR_REFUND webhook

Before we send your Terminal API reversal request to be processed, we perform various validations. If these validations succeed, usually the refund itself also succeeds. You receive the outcome of the validations asynchronously, in a CANCEL_OR_REFUND webhook that includes:

• eventCode: CANCEL_OR_REFUND.
• originalReference: the PSP reference of the original payment.
• pspReference: the pspReference from the reversal response.

• success: indicates the outcome of the refund validations. Possible values:

  • true: Adyen's validations were successful and we sent the refund request to the card scheme. This usually means that the refund will be processed successfully. However, in rare cases the refund can be rejected by the card scheme, or reversed. For information about these exceptions, see REFUND_FAILED webhook, and REFUNDED_REVERSED webhook.

  • false: the refund validations failed. The webhook includes a reason field with a short description of the problem. Review the reason, fix the issue if possible, and resubmit the refund request.

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "modification.action": "refund"
            },
            "amount":{
               "currency": "EUR",
               "value": 1025
            },
            "eventCode":"CANCEL_OR_REFUND",
            "eventDate":"2022-02-03T15:14:15.004Z",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "originalReference":"VK9DRSLLRCQ2WN82",
            "paymentMethod":"mc",
            "pspReference":"TF995R5G6L2GWR82",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

For more information about the included fields, see the CANCEL_OR_REFUND webhook reference.

REFUND webhook

Before we send a refund request to be processed, we perform various validations. If these validations succeed, usually the refund itself also succeeds. You receive the outcome of the validations asynchronously, in a webhook that includes:

• eventCode: REFUND.
• pspReference: the pspReference from the response for your refund request.

• success: indicates the outcome of the refund validations. Possible values:

  • true: Adyen's validations were successful and we sent the refund request to the card scheme. This usually means that the refund will be processed successfully. However, in rare cases the refund can be rejected by the card scheme, or reversed. For information about these exceptions, see REFUND_FAILED webhook, and REFUNDED_REVERSED webhook.

  • false: the refund validations failed. The webhook includes a reason field with a short description of the problem. Review the reason, fix the issue if possible, and resubmit the refund request.

For more information about the included fields, see the REFUND webhook reference.

Reasons for failed refund validation

When our validations of a refund fail, you receive a webhook for the refund with success: false and the reason of the failure. The next table shows the most common reasons.

The balance on the payment is the amount that remains from the original payment. For example, if a transaction has a total of EUR 10 and no refund or chargeback is processed, then the balance on the payment is EUR 10. After a refund or chargeback of EUR 3 is processed, the remaining balance on the payment is EUR 7.

See also