Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Make a gift card payment

Make a gift card payment at the point of sale.

After you have activated a gift card, you can make payments with the card.

Making a gift card payment is similar to a credit or debit card payment, except you add a tender option to allow partial payments. The payment response returns the authorised amount, indicating whether the balance on the gift card is enough. If the gift card balance is insufficient, you can let shopper pay the remainder with another card or in cash.

Before you begin

Before you make any gift card transactions, ensure you have:

Make the initial payment

Testing

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

To make a payment using a gift card where partial authorisation is possible:

  1. Determine the card entry method:

    • If you want to scan the card, do that first and use the obtained card details in your request.
    • If you want to swipe the card or use manual key entry (MKE), send the request first. The payment terminal will show a prompt to swipe the card or enter the card details.

  2. 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.
    • PaymentRequest.PaymentData.PaymentInstrumentData. This is where you indicate that a gift card is used.

      Parameter Required Description
      PaymentInstrumentType StoredValue
      StoredValueAccountID The gift card details:
      • StoredValueAccountType: GiftCard
      • StoredValueProvider: The gift card issuer, such as givex, svs, valuelink, genericgiftcard, or any Intersolve-supported card type.
      • IdentificationType: PAN
      • `EntryMode, StoredValueID and ExpiryDate: These parameters depend on the card entry method you are using. See the following table.
      Card entry Parameters
      Scan
      • EntryMode: Scanned
      • StoredValueID: Gift card number.
      • ExpiryDate: Expiry date of the gift card.
      Swipe
      • EntryMode: MagStripe
      • StoredValueID: Include this parameter but don't provide a value.
      MKE
      • EntryMode: Keyed
      • StoredValueID: Include this parameter but don't provide a value.

    The following example shows how you would make a EUR 25.99 payment with a scanned gift card.

    Gift card 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
                    }
                },
                "PaymentData":{
                    "PaymentInstrumentData":{
                        "PaymentInstrumentType":"StoredValue",
                        "StoredValueAccountID":{
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"9826150911219687",
                            "ExpiryDate":"1122"
                        }
                    }
                }
            }
        }
    }

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

  3. 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 gift card payment was successful, but only EUR 10.00 of the original EUR 25.99 was authorised.

    Response for a partial gift card payment
    {
        "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": {
                        "StoredValueAccountID":{
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"9826150911219687",
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "ExpiryDate":"1122"
                        },
                        "PaymentInstrumentType": "StoredValue"
                    }
                },
                "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, see the Terminal API fundamentals.

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

(Optional) Make a follow-up payment

If the initial partial payment with the gift card 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.

Alternative flow

Instead of using the partial payments flow described above, you can:

  1. Check the balance on the gift card.

  2. Make a payment request with:

  3. Optionally make a regular payment request if the gift card payment doesn't cover the whole purchase.

Next steps