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

Process in-person payments

Process in-person payments on behalf of your users.

In a platform setup, you can onboard your users with point-of-sale integrations to accept in-person payments. With every payment and capture, you can split the funds between any number of balance accounts in your platform, including your liable balance account. For example, when a customer pays, you can split the funds into two parts: one part is the platform fee that goes to your liable account, and the other part is the sale amount that goes to your user's balance account.

You must send the split information for every transaction at the time of payment or at capture. If the payments are not split, the full amount is booked to your liable account.

Before you begin

Before you start processing point-of-sale payments for your user, make sure that you have:

Split at payment

To split funds at the time of payment:

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

    In the MessageHeader, include:

    Parameter Required Description
    ProtocolVersion -white_check_mark- Set to 3.0
    MessageClass -white_check_mark- Set to Service
    MessageCategory -white_check_mark- Set to Payment
    MessageType -white_check_mark- Set to 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].

    In the PaymentRequest, include:

    Parameter Required Description
    SaleData.SaleTransactionID -white_check_mark- An object with:
    • TransactionID: your reference to identify a payment. We recommend using a unique value per payment. In your Customer Area and Adyen reports, this will show as the merchant reference for the transaction.
    • TimeStamp: date and time of the request in UTC format.
    SaleData.SaleToAcquirerData -white_check_mark- Provides the split payment data as concatenated key-value pairs separated by an ampersand (&) character, or in Base64-encoded format. See the tables below for details.
    PaymentTransaction.AmountsReq -white_check_mark- An object with:
    • Currency: the transaction currency.
    • RequestedAmount: the transaction amount.
      Specify the amount with a decimal point. Do not use minor units. For example, for an amount of 10 EUR specify 10.00 (not 1000).
      .

    Provide the split payment data in PaymentRequest.SaleData.SaleToAcquirerData:

    Key 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 and to the sum of the split amounts. split.totalAmount=62000
    split.currencyCode Currency of the amount to be split. split.currencyCode=EUR
    split.nrOfItems Number of times you will split the payment. Must match the number of split items in the request. split.nrOfItems=2

    In the same PaymentRequest.SaleData.SaleToAcquirerData object, specify each split as a split.item{item#} starting at 1: split.item1, split.item2, and so on. In each split item, include:

    Key Description Example
    split.item{item#}.amount Amount of the split, in minor units. split.item1.amount=60000 and split.item2.amount=2000
    split.item{item#}.type Split type.
    • BalanceAccount : sends the amount to the account specified.
    • PaymentFee: books the transaction fees to the specified balance account.
    • Commission : sends the amount to your liable account.
    		 split.item1.type=BalanceAccount and split.item2.type=Commission
    split.item{item#}.account Account that will receive 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#}.type is Commission.  split.item1.account=BA00000000000000000000001
    split.item{item#}.reference The reference for that specific transaction split, which is returned in our reporting. Required if the split.item{item#}.type is BalanceAccount.  

    Example

    The example below shows how to split a 620.00 EUR payment into 600.00 EUR to be paid to your user's balance account and 20.00 EUR commission to be paid to your liable account.

    a. Define the pairs of split payment data. In our example:

    split.api=1
    split.nrOfItems=2
    split.totalAmount=62000
    split.currencyCode=EUR
    split.item1.amount=60000
    split.item1.type=BalanceAccount
    split.item1.account=BA00000000000000000000001
    split.item1.reference=RefSplit1
    split.item1.description=TestPayment
    split.item2.amount=2000
    split.item2.type=Commission
    split.item2.reference=TestCommission

    b. Concatenate the pairs using ampersands (&) to a string.

    split.api=1&split.nrOfItems=2&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=RefSplit1&split.item1.description=TestPayment&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=TestCommission

    c. Pass the string in SaleToAcquirerData.

    Payment request with split data 
    {
  "SaleToPOIRequest": {
      "MessageHeader": {
          "ProtocolVersion": "3.0",
          "MessageClass": "Service",
          "MessageCategory": "Payment",
          "MessageType": "Request",
          "SaleID": "POSSystemID12345",
          "ServiceID": "0207111104",
          "POIID": "V400m-324688179"
      },
      "PaymentRequest": {
          "SaleData": {
              "SaleTransactionID": {
                  "TransactionID": "27908",
                  "TimeStamp": "2022-10-28T10:11:04+00:00"
              },
              "SaleToAcquirerData": "split.api=1&split.nrOfItems=2&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=RefSplit1&split.item1.description=TestPayment&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=TestCommission"
          },
          "PaymentTransaction": {
              "AmountsReq": {
                  "Currency": "EUR",
                  "RequestedAmount": 620.00
              }
          }
      }
  }
}

    The payment request is routed to the terminal, for the customer to present their card and verify the payment. The payment is then sent to the Adyen payments platform for processing.

  2. Check the payment result.

    If your integration uses asynchronous cloud communications, you must set up event notifications. We then send the Terminal API responses to your event notifications endpoint.

    If the payment is successful:

    • Approved is shown on the terminal display.
    • You receive a payment response containing:
      • POIData.POITransactionID.TransactionID: Transaction identifier for the payment in the format tenderReference.pspReference. For example, oLkO0012498220087000.981517998282382C.
      • PaymentResponse.Response.Result: Success
      • PaymentResponse.Response.AdditionalResponse: Information resulting from the processing of your payment request. Its format corresponds to the format of the SaleToAcquirerData in the payment request: a Base64-encoded JSON object or form-encoded key-value pairs.
      • PaymentReceipt: Object containing data you can use to generate a receipt.

    You can also view the details of a payment in your Customer Area under Transactions > Payments, and the splits in your Balance Platform Customer Area.

Split at capture

The final split amounts may not be clear at the moment the payment request is made, for example, in the case of tipping (gratuity) and partial payments. If this applies to your user's point-of-sale payments, you need to enable manual capture and follow up with a /payments/paymentPspReference/captures API call containing the split details.

To enable manual capture, you can either:

  • Enable manual capture at the account level. In this case, you must follow up each authorised Terminal API payment with a /payments/paymentPspReference/captures API call.

    Enabling manual capture at the account level applies to all your point-of-sale users.

  • Enable manual capture at the transaction level. In this case, you add a manual capture flag to the payment request and then make a /payments/paymentPspReference/captures API call for that specific authorization.

To split a payment at capture:

  1. From the transactionID field in the payment response , get the pspReference of the authorisation you want to capture.
  2. Make a POST request to the /payments/paymentPspReference/captures endpoint, where paymentPspReference is the pspReference of the authorisation you want to capture.
    In your request, include:
    Parameter Required Description
    amount.value -white_check_mark- The amount in minor units (without a decimal point) being captured. This must be the same amount as the original authorised amount.
    amount.currency -white_check_mark- This must match the currency of the payment you are capturing.
    merchantAccount -white_check_mark- The name of your merchant account that is used to process the payment.
    reference Your unique identifier for the capture operation.
    splits -white_check_mark- An array of split items, each including:
    • amount.value: the amount of the split, in minor units.
    • type: the type of split type.
      • BalanceAccount: sends the amount to the account specified.
      • Commission: sends the amount to your liable account.
      • PaymentFee: send the tranaction fees to the specified balance account.
    • account: the balance account that will receive 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 a balance account when split.type is Commission.
    • reference: an optional reference which is returned in our reporting. You can use this to refer to that specific transaction split.
    The example below shows how to capture a 620.00 EUR authorisation with pspReference 981517998282382C, and split it into 600.00 EUR to be paid into the user's balance account with balanceAccountId BA00000000000000000000001 and 20.00 EUR commission to be paid to your liable account. 
    curl https://checkout-test.adyen.com/v69/payments/981517998282382C/captures \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "amount": {
          "value": 62000,
          "currency": "EUR"
      },
      "reference": "YOUR_REFERENCE_NUMBER",
      "splits":[
        {
          "amount":{
            "value":60000
          },
          "type":"BalanceAccount",
          "account":"BA00000000000000000000001",
          "reference":"YOUR_REFERENCE_TO_SPLIT_#1"
        },
        {
          "amount":{
            "value":2000
          },
          "type":"Commission",
          "reference":"YOUR_REFERENCE_TO_SPLIT_#2"
        }
      ]
}'
  3. In the capture response, note the following:
    • paymentPspReference: the PSP reference of the authorisation.
    • pspReference: the PSP reference associated with this capture request. This is different from the PSP reference of the authorisation.
    • status: received. Your capture request will be processed asynchronously. You will receive the result in a webhook.
  4. Wait for the CAPTURE webhook to learn the outcome of the request.

See also