Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale 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, the issuer will authorise the available amount when the card's available balance is not enough for the full amount. You can then let the shopper pay the remainder with another card or in cash.

There is no guarantee that all issuers support partial authorisations.

To use partial payments, you need to:

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

  • Keep track of how much remains to be paid, and alert your staff.
    The payment response returns the authorised 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.

  • Connect multiple partial payments to the same transaction in your reconcilation process.

Risk with partial payments

When the issuer supports partial authorisations 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 the cash register alerts your staff to the fact that there is an amount remaining to be paid.

Make the initial partial payment

To start a payment where partial authorisation is possible:

  1. Make a PaymentRequest with:

    • PaymentRequest.SaleData. This includes:
      Parameter Required Description
      SaleTransactionID -white_check_mark- An object with:
      • TransactionID: Your unique reference for this request. 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 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": "AllowParialAuthorisation"} to Base64, and pass the resulting string:
        "SaleToAcquirerData": "eyJ0ZW5kZXJPcHRpb24iOiAiQWxsb3dQYXJpYWxBdXRob3Jpc2F0aW9uIn0="
      • 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
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: The transaction currency.
      • RequestedAmount: The purchase amount, with decimals.

    The following example shows how you would make a €25.99 payment.

    Payment with partial payment tender option
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "MessageType":"Request",
                "ServiceID":"9267",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"44740",
                        "TimeStamp":"2019-03-26T09:13:41+00:00"
                    },
                    "SaleReferenceID": "Order12345-1",
                    "SaleToAcquirerData": "tenderOption=AllowPartialAuthorisation"
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"EUR",
                        "RequestedAmount":25.99
                    }
                }
            }
        }
    }

    For more information on the Terminal API request structure, refer to the Terminal API fundamentals.

  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 authorised. This may be less than the requested amount.
    • AdditionalResponse: Contains posOriginalAmountValue with the requested amount, and posAuthAmountValue with the authorised 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 €10.00 of the original €25.99 was authorised.

    Response for a partial authorisation
    {
        "SaleToPOIResponse": {
            "MessageHeader": {...},
            "PaymentResponse": {
                "POIData": {
                    "POIReconciliationID": "1000",
                    "POITransactionID": {
                        "TimeStamp": "2021-11-16T11:26:19.000Z",
                        "TransactionID": "CWf3001637061979001.M32P3JBKR65ZGN82"
                    }
                },
                "PaymentReceipt": [...],
                "PaymentResult": {
                    "AmountsResp": {
                        "AuthorizedAmount": 10.00,
                        "Currency": "EUR"
                    },
                    ...,
                    "PaymentAcquirerData": {...},
                        ...
                    },
                    "PaymentInstrumentData": {
                        "CardData": {
                            "CardCountryCode": "826",
                            "EntryMode": [
                                "Contactless"
                            ],
                            "MaskedPan": "541333 **** 9999",
                            "PaymentBrand": "mc",
                            "SensitiveCardData": {
                                "CardSeqNumb": "33",
                                "ExpiryDate": "0228"
                            }
                        },
                        "PaymentInstrumentType": "Card"
                    }
                },
                "Response": {
                    "AdditionalResponse": "...&posOriginalAmountValue=2599...&posAuthAmountValue=1000",
                    "Result": "Partial"
                },
                "SaleData": {
                    "SaleReferenceID": "Order12345-1",
                    "SaleTransactionID": {
                        "TimeStamp": "2021-11-16T11:26:15.253Z",
                        "TransactionID": "644"
                    }
                }
            }
        }
    }

    For more information on the Terminal API response structure, refer to the Terminal API fundamentals.

  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:
    • 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 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 €15.99.
    Follow-up partial payment
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "MessageType":"Request",
                "ServiceID":"9267",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"44740",
                        "TimeStamp":"2019-03-26T09:13:45+00:00"
                    },
                    "SaleReferenceID": "Order12345-2",
                    "SaleToAcquirerData": "tenderOption=AllowPartialAuthorisation"
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"EUR",
                        "RequestedAmount":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.

Testing 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