Terminal-2 icon

Partial payments

Allow shoppers to pay the remainder with a different payment method.

To reduce the number of transactions that are declined due to insufficient funds, you can add partial payments to your Terminal API integration. With this, you ask the issuer to authorize the available amount when the card's balance is not enough for the full amount. You can then let the shopper pay the remainder with another card or in cash.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement Description
Integration type Make sure that you have built a Terminal API integration.
Limitations Be aware that there is no guarantee that all issuers support partial authorizations.
Setup steps Consider configuring a capture delay.

Risk with partial payments

When the issuer supports partial authorizations and the transaction succeeds, the terminal shows Approved plus a warning that mentions how much was paid, out of the requested amount.

Because the transaction is approved, the warning may be overlooked, and the shopper may leave without having paid the full amount. Therefore, it is very important to ensure that your POS app alerts your staff to the fact that there is an amount remaining to be paid.

Consider configuring a capture delay. If the customer has second thoughts about the transaction, this gives you time to cancel the authorization before the amount is captured. This is easier than issuing a refund.

How it works

To use partial payments, you need to:

  1. Add the tender option AllowPartialAuthorisation to your payment request.
    When the requested amount is higher than the amount available in the account, this tender option asks the issuer to return an authorization for the available amount instead of declining the transaction.

  2. Keep track of how much remains to be paid, and alert your staff.
    The payment response returns the authorized amount. If this is less than the requested amount, you can make another payment request to let the shopper pay the remainder with another card or in cash.

  3. In your reconciliation process, connect multiple partial payments to the same transaction.

Make the initial payment

To start a payment where partial authorization is possible:

  1. Make a PaymentRequest with:

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

    • PaymentRequest.SaleData. This includes:

      Parameter Required Description
      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.
      SaleReferenceID Unique reference, such as your order number plus a sequence number, that lets you identify partial payments that belong together. In your Customer Area, this will appear as the Merchant Order for the transaction.

      For example, if the order number is Order12345, you specify Order12345-1 in the first partial payment request and Order12345-2 in the second partial payment request.
      SaleToAcquirerData -white_check_mark- The AllowPartialAuthorisation tender option.

      See the instructions below.

    In SaleData.SaleToAcquirerData, specify the tender option in one of the following formats:

    • Option 1: a JSON object converted to a Base64 encoded string.
      Encode {"tenderOption": "AllowPartialAuthorisation"} to Base64, and pass the resulting string:
      "SaleToAcquirerData": "eyJ0ZW5kZXJPcHRpb24iOiAiQWxsb3dQYXJ0aWFsQXV0aG9yaXNhdGlvbiJ9"

    • Option 2: a key-value pair:
      "SaleToAcquirerData": "tenderOption=AllowPartialAuthorisation"

    The format that you use here will also be the format of the AdditionalResponse that you receive. If there are more tender options (for example, ReceiptHandler ) or other data elements that you need to pass in the SaleToAcquirerData field, refer to Add information to a payment.

    • PaymentRequest.PaymentTransaction. This includes:
    Parameter Required Description
    AmountsReq -white_check_mark- An object with:
    • Currency: The transaction currency.
    • RequestedAmount: The purchase amount, with decimals.

    The following example shows how to make a EUR 25.99 payment.

    See the PaymentRequest API reference.

  2. In the payment response, note the following:

    • Response.Result: If the payment was successful, Success indicates a full payment, or Partial indicates a partial payment.
    • PaymentResult.AmountsResp.AuthorizedAmount: The amount that was authorized. This may be less than the requested amount.
    • AdditionalResponse: Contains posOriginalAmountValue with the requested amount, and posAuthAmountValue with the authorized amount.
    • SaleData.SaleReferenceID: Your order number. If you are going to make another partial payment, the SaleReferenceID of that other payment must be based on this one.

    The example below shows that the payment was successful but that only EUR 10.00 of the original EUR 25.99 was authorized.

    See the PaymentResponse API reference.

  3. If the Response.Result is Partial, make a follow-up partial payment or let the shopper pay the remainder in cash.

(Optional) Make a follow-up payment

If the initial partial payment didn't cover the full amount, you can follow up with another partial payment for the remainder:

  1. Calculate the remaining amount after the initial partial payment: subtract the AuthorizedAmount in the response from the RequestedAmount in the request.
    Alternatively, you can calculate the remaining amount using posAuthAmountValue and posOriginalAmountValue from the AdditionalResponse.

  2. Make a PaymentRequest with:

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

    • PaymentRequest.SaleData. This includes:

      Parameter Required Description
      SaleReferenceID Unique reference, such as your order number plus a sequence number, that lets you identify partial payments that belong together.

      For example, if you specified Order12345-1 in the first partial payment request with the gift card, you'd specify Order12345-2 in this second partial payment request.
      SaleToAcquirerData -white_check_mark- The AllowPartialAuthorisation tender option.

      For the format, see the initial partial payment.

    • PaymentRequest.PaymentTransaction. This includes:

      Parameter Required Description
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: The transaction currency.
      • RequestedAmount: The calculated remaining amount.

    This example shows a payment request for the remaining EUR 15.99.

  3. When you receive the response, check if the Response.Result is now Success. That means the amount due is paid in full.

Test partial payments

You can test the partial payments flow using an amount ending in 139:

  1. Make a PaymentRequest with:

    • PaymentRequest.SaleData including:

      Parameter Required Description
      SaleReferenceID Unique reference that lets you identify partial payments that belong together.
      SaleToAcquirerData The AllowPartialAuthorisation tender option.

    • PaymentRequest.PaymentTransaction including :

      Parameter Required Description
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: an amount ending in 139. For example, 41.39.

  2. Check that the terminal shows Approved and a warning about how much out of the requested amount was paid.
    For example: !  $ 40.39 out of $ 41.39

  3. Check that the response contains the following:

    • PaymentResult.AmountsResp.AuthorizedAmount: a value of 1 less than the requested amount. For example, 40.39 if the requested amount was 41.39.

    • Response.Result: Partial.

  4. Make a second partial payment request for the remaining amount, with a SaleReferenceID that allows you to identify the two partial payments as belonging together.

  5. In your Customer Area and/or reports, find the two partial payments by their Merchant Order. The Merchant Order corresponds to the SaleReferenceID from the payment requests.

See also