Adyen-for-platform icon

Refund with split instructions

Split a refund between the balance accounts in your platform.

You can always be in control of funds movements in your platform if you provide split instructions for in your refund requests, and you can support different refund scenarios, such as partial and multiple partial refunds.

Requirements

Take into account the following requirements, limitations, and preparations to capture payments.

Requirement Description
API credentials You must have credentials for the following API:
Webhooks Ensure that your server can receive and accept standard webhooks.
Subscribe to any of the following webhooks:
Limitations When you refund a payment, you must take into account:
  • Some payment methods do not support partial refunds. You can check which ones support partial and multiple partial refunds in the overview of payment methods.
  • Refunds can only be deducted from the balance accounts to which the payment was credited.
  • Use the same reference values as in the original split.

Gather the data

Gather the following data that you need pass in the SaleToAcquirerData field of your refund request:

Data element Description Example
split.api Version of the Split API: 1. split.api=1
split.totalAmount The full transaction mount, in minor units.
Must be equal to the sum of the split amounts.		 split.totalAmount=62000
split.currencyCode Currency of the transaction. split.currencyCode=EUR
split.nrOfItems The number of splits you want to create.
Must match the sum of split items in the request.		 split.nrOfItems=2
currency Currency of the split amount.
Must match the value provided in split.currencyCode.		 currency=EUR

Every split of the full amount is called a split item, and needs to be specified with a different number, starting at 1.
For every split item, like split.item1, split.item2, and so on, include the following:

Split item data Description Example
split.item[ITEM_NUMBER].amount Amount of each split item, in minor units. You do not need to specify the amount for the fees, since this is not known when you send the request. split.item1.amount=61000
split.item2.amount=1000
split.item[ITEM_NUMBER].type Defines the part of the refund you want to book to the specified split.item[ITEM_NUMBER].account.
Possible values:
  • BalanceAccount: Deduct the funds from the specified balance account.
  • Commission: Deduct the commission from your liable balance account.
 split.item1.type=BalanceAccount
split.item2.type=Commission
split.item[ITEM_NUMBER].account The balance account from which we deduct the split amount. This is the balanceAccountID of one of your user's balance accounts or your own liable account. You do not need to specify this field when the split.item[ITEM_NUMBER].type is Commission. split.item1.account=BA00000000000000000000001
split.item[ITEM_NUMBER].reference The reference for the specific transaction split, which is returned in our reporting. Required if the split.item[ITEM_NUMBER].type is BalanceAccount. split.item1.reference=reference_split_1
split.item2.reference=reference_commission
split.item[ITEM_NUMBER].description The description for the specific transaction split, which is returned in our reporting. split.item1.description=description_split_1
split.item2.description=description_commission

Prepare the data

There are two ways to pass the refund data in the SaleToAcquirerData field of your request:

  • Option 1: as form-encoded key-value pairs (using & as a separator).
  • Option 2: as a JSON object converted to a Base64-encoded string.

The format you choose in your request is the format that will be returned in the AdditionaResponse field of the response. To always receive the AdditionalResponse in the same format, contact our Support Team.

Make a refund request

Make a POST request to a Terminal API endpoint, specifying:

  • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

    Parameter Required Description
    ProtocolVersion -white_check_mark- 3.0
    MessageClass -white_check_mark- Service
    MessageCategory -white_check_mark- Reversal
    MessageType -white_check_mark- Request
    ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
    SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
    POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

  • ReversalRequest: The request body. This includes:

    Parameter Required Description
    OriginalPOITransaction.POITransactionID -white_check_mark- An object with:
    • TransactionID: Transaction identifier of the original payment in the format tenderReference.pspReference. For example, BV0q001643892070000.VK9DRSLLRCQ2WN82
    • TimeStamp: date and time of the original payment request in UTC format.
    ReversalReason -white_check_mark- Set to MerchantCancel.
    ReversedAmount -white_check_mark- The refunded amount.
    Specify the amount with a decimal point. Do not use minor units. For example, for an amount of USD 10 specify 10.00 (not 1000).

    SaleData.SaleToAcquirerData -white_check_mark- Provides the split refund data as concatenated key-value pairs separated by an ampersand (&) character, or in Base64-encoded format. See the tables below for details
    SaleData.SaleTransactionID -white_check_mark- An object with:
    • TransactionID: your reference to identify the refund. We recommend using a unique value per refund.
    • TimeStamp: date and time of the request in UTC format.

Refund request

Below is an example Terminal API request to split a refund of EUR 620.00 between the balance accounts on your platform, using key-value pairs.
In this example, we are deducting different amounts from the balance accounts than what was defined in the original payment request.

  • EUR 610.00 is debited from BA00000000000000000000001.
  • EUR 10.00 is debited from your liable balance account.

The refund request is routed to the terminal, where the customer can present their card. The payment terminal shows a waiting screen until you receive a response.

Refund response

When you receive the ReversalResponse, check if we received your request. Note the following:

  • Response.Result: Success. This means we received your request. The refund itself will be processed asynchronously.
  • POIData.POITransactionID.TransactionID: the PSP reference for this refund request.
  • PaymentReceipt: the generated receipt data. This includes REFUND REQUESTED.

  • Response.AdditionalResponse with:

    • posOriginalAmountValue: the amount (in minor units) of the original payment.
    • posAuthAmountValue: the refund amount (in minor units) that we will try to get authorized.

    • pspReference: the PSP reference for this refund request.

Troubleshooting

If your request failed, the ReversalResponse contains:

  • Response.Result: Failure

  • AdditionalResponse: this includes a message explaining why the request failed. For example:

    • Original pspReference required for this operation: messages like this tell you how to fix the request so you can try again.
    • Transaction is already voided: this message tells you that we already received a full reversal request for the original transaction.

Get notified about refund status

Wait for the CANCEL_OR_REFUND webhook to learn the outcome of the refund request. Refunds are always processed asynchronously.

When you initiate a refund, we also send you Transfer webhooks and Transaction webhooks to notify you of the balance and transfer status changes in your platform.

The following tabs show the webhooks you receive when:

  • The payment amount is deducted from your user's balance account
  • The commission amount is deducted from your liable balance account
  • The transaction fees are deducted from the specified balance account