No momento, esta página não está disponível em português

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: Terminal API
Webhooks	Ensure that your server can receive and accept standard webhooks. Subscribe to any of the following webhooks: Transfer webhooks Transaction 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.

1. 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

2. 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 AdditionalResponse field of the response. To always receive the AdditionalResponse in the same format, contact our Support Team.

3. 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`		3.0
`MessageClass`		Service
`MessageCategory`		Reversal
`MessageType`		Request
`ServiceID`		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`		Your unique ID for the POS system component to send this request from.
`POIID`		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`		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`		Set to MerchantCancel.
`ReversedAmount`		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`		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`		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.

The following Terminal API request, we 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 75.00 is debited from BA00000000000000000000001.
EUR 5.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.

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.Response contains:

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.

4. 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.

Track fund movements

To track the status of the fund transfers initiated by a refund:

Listen to the following webhooks:
- Transfer webhooks: Adyen sends a balancePlatform.transfer.created webhook to inform your server that funds will be credited to balance accounts, and balancePlatform.transfer.updated webhooks after every status change.
- Transaction webhooks: Adyen sends a balancePlatform.transaction.created webhook to inform your server that funds have been credited to a balance account.
Acknowledge the webhooks. We send these webhooks for every split item in the payment.
In the balancePlatform.transfer.updated webhook payload, note that the event array includes all previous transfer events, and the sequenceNumber defines the number of webhooks sent for the transfer, including the current one.

Examples

Your server receives webhooks for each split of the refund amount. The following examples are based on a refund request with split instructions use case.