When refunding a split payment, you can either deduct the same amount from the same balance accounts as used in the original payment request, or provide new split data in the
ReversalRequest. Refunds can only be deducted from the balance accounts to which the payment was credited.
For example, a payment of EUR 620.00 is split between two balance accounts:
- EUR 600.00 is booked to your user's balance account (BA00000000000000000000001).
- EUR 20.00 is booked to your liable balance account as your platform's commission.
To refund this payment, send a Terminal API
ReversalRequest. If you do not provide the split data in the
SaleData.SaleToAcquirerData object of your request, the split data from the original payment will be used for the refund.
We recommend that you always provide split data for refunds. That way, you are always in control and can support different refund scenarios, such as partial and multiple partial refunds.
When sending split data in a refund request, you must:
- Only use balance accounts that were part of the original split.
- Use the same
referencevalues as the original split.
To provide split information in your refund request:
Step 1: Gather the data
Gather the following data that you need pass inside
SaleToAcquirerData of the refund request:
||Version of the Split API: 1.||split.api=1|
||The full transaction mount, in minor units.
Must be equal to the sum of the split amounts.
||Currency of the transaction.||split.currencyCode=EUR|
||The number of splits you want to create.
Must match the sum of split items in the request.
||Currency of the split amount.
Must match the value provided in
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.item2, and so on, include the following:
||Amount of each split item, in minor units. You do not need to specify the amount for the fees, since this is not known at the time of payment.||split.item1.amount=62000
||Account that will receive (or be charged) the split. This is the
||The reference for that specific transaction split, which is returned in our reporting. Required if the
||The description for that specific transaction split, which is returned in our reporting.||split.item1.description=description_split_1
Step 2: Prepare the data
There are two ways to pass data elements 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.
Concatenate the key-pairs from Step 1 into a string by separating them with ampersands (&).
Pass this string in the
SaleToAcquirerDataobject of your request.
The format you choose in your request is the format that will be returned in the
AdditionalResponse. To always receive the
AdditionalResponse in the same format, contact our Support Team
Step 3: Make a refund request
Make a POST request to a Terminal API endpoint, specifying:
MessageHeader: the standard
SaleToPOIRequest.MessageHeaderobject. This includes:
Parameter Required Description
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.
Your unique ID for the POS system component to send this request from.
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
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.
Set to MerchantCancel.
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).
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
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.
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 620.00 is debited from BA00000000000000000000001.
- EUR 0.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.
Step 4: Check the result
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.
posOriginalAmountValue: the amount (in minor units) of the original payment.
posAuthAmountValue: the refund amount (in minor units) that we will try to get authorised.
pspReference: the PSP reference for this refund request.
If your request failed, the
AdditionalResponse: this includes a
messageexplaining 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.
Wait for the CANCEL_OR_REFUND webhook to learn the outcome. Refunds are always processed asynchronously.