Adyen-for-platform icon

Refund with original split ratio

Split a refund between the balance accounts in your platform, according to the original payment's split ratio.

If you want to split the refund amount between the balance accounts in your platform the exact same way as you defined in the original payment request, you do not include the split instructions in your refund request.

Requirements

Take into account the following requirements, limitations, and preparations for processing refunds.

Requirement Description
API credentials You must have credentials for the Terminal API.
Webhooks Ensure that your server can receive and accept standard webhooks.
Subscribe to any of the following webhooks:
Limitations The full refund amount is debited from your liable balance account by default if:
  • The payment authorization did not have split instructions.
  • The refund is partial.

Get the original payment details

Get the TransactionID and the TimeStamp of the original payment. You received these values in the payment response, in the POITransactionID object.

Make a refund request

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

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

Refund request

Here is an example Terminal API request to split a refund of EUR 620.00 according to the original payment split:

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.

Webhook

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

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