Are you looking for test card numbers?

Would you like to contact support?

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

Split a refund

Split a refund between the balance accounts in your platform.

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 reference values as the original split.

To provide split information in your refund request:

Step 1: Gather the data

  1. Gather the data that you will pass inside SaleToAcquirerData of the refund request:

    • Specify the following:

      Field Description Example
      split.api Version of the Split API: 1. split.api=1
      split.totalAmount Amount to be split, in minor units. Must be equal to the transaction amount which is the sum of the split amounts. split.totalAmount=62000
      split.currencyCode Currency of the amount you intend to split. split.currencyCode=EUR
      split.nrOfItems Number of times you split the payment. Must match the number 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:

      Field 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 at the time of payment. split.item1.amount=62000
      split.item2.amount=0
      split.item[ITEM_NUMBER].type Split type.
      • BalanceAccount: books the sale amount against the specified balance account.
      • Commission: books the commission against your liable account.
      		 split.item1.type=BalanceAccount
      split.item2.type=Commission
      split.item[ITEM_NUMBER].account Account that will receive (or be charged) the split. This is the balanceAccountID of one of your user's balance accounts or your own liable account. You don't 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 that 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 that specific transaction split, which is returned in our reporting. split.item1.description=description_split_1
      split.item2.description=description_commission
      The data for the split refund 
      currency=USD
split.api=1
split.nrOfItems=2
split.totalAmount=62000
split.currencyCode=EUR
split.item1.amount=62000
split.item1.type=BalanceAccount
split.item1.account=BA00000000000000000000001
split.item1.reference=reference_split_1
split.item1.description=description_split_1
split.item2.amount=0
split.item2.type=Commission
split.item2.reference=reference_commission
split.item2.description=description_commission

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.

  1. Concatenate the key-pairs from Step 1 into a string by separating them with ampersands (&).

    currency=USD&split.api=1&split.nrOfItems=2&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=62000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=reference_split_1&split.item1.description=description_split_1&split.item2.amount=0&split.item2.type=Commission&split.item2.reference=reference_commission&split.item2.description=description_commission

  2. Pass this string in the SaleToAcquirerData object 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 POS Support Team

Step 3: Make a refund request

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

  • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:

    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 10 USD 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.

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 account.
Refund request with split data 
{
    "SaleToPOIRequest":{
        "MessageHeader":{
            "ProtocolVersion": "3.0",
            "MessageClass": "Service",
            "Message Category": "Reversal",
            "MessageType": "Request",
            "SaleID": "YOUR_POS_SYSTEM_ID",
            "ServiceID": "YOUR_UNIQUE_REFERENCE",
            "POIID": "YOUR_TERMINAL_ID"
        },
        "ReversalRequest":{
            "OriginalPOITransaction":{
                "POITransactionID":{
                    "TransactionID": "ORIGINAL_TRANSACTION_REFERENCE",
                    "TimeStamp": "DATE_TIME_ORGINAL_TRANSACTION"
                }
            },
            "ReversalReason": "MerchantCancel",
            "ReversedAmount": "TOTAL_REFUND_AMOUNT",
            "SaleData":{
                "SaleToAcquirerData": "currency=EUR&split.api=1&split.nrOfItems=2&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=62000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=reference_split_1&split.item1.description=description_split_1&split.item2.amount=0&split.item2.type=Commission&split.item2.reference=reference_commission&split.item2.description=description_commission",
                "SaleTransactionID":{
                    "TimeStamp": "DATE_TIME_REFUND_REQUEST",
                    "TransactionID": "YOUR_REFUND_REFERENCE"
                }
            }
        }
    }
}

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

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

    • pspReference: the PSP reference for this refund request.

      Response when we received your full reversal request 
      {
"SaleToPOIResponse": {
"MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "V400m-324688179",
    "ProtocolVersion": "3.0",
    "SaleID": "POSSystemID12345",
    "ServiceID": "207111107"
},
"ReversalResponse": {
    "POIData": {
        "POITransactionID": {
            "TimeStamp": "2022-02-03T15:04:15.004Z",
            "TransactionID": "TF995R5G6L2GWR82"
        }
    },
    "PaymentReceipt": [...],
    "Response": {
        "AdditionalResponse": "tid=47069832&transactionType=GOODS_SERVICES&posadditionalamounts.originalAmountValue=1025&giftcardIndicator=false&posAmountGratuityValue=0&pspReference=TF995R5G6L2GWR82&store=YOUR_STOREL&iso8601TxDate=2022-02-03T15%3a04%3a13.0000000%2b0000&posOriginalAmountValue=1025&txtime=16%3a04%3a13&paymentMethod=mc&txdate=03-02-2022&merchantReference=2022-02-03%2016%3a04%3a13&posadditionalamounts.originalAmountCurrency=EUR&transactionReferenceNumber=TF995R5G6L2GWR82&posAuthAmountCurrency=EUR&posAmountCashbackValue=0&posEntryMode=CLESS_CHIP&posAuthAmountValue=1025",
        "Result": "Success",
        "ReversedAmount": 620
    }
}
}
}

      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. Refunds are always processed asynchronously.