Search

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.

Once 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. If the balance of the gift card doesn't cover a full payment, you can make partial payments.

Before you begin

Before you make any gift card transactions, make sure that you have:

Make a payment request

To initiate a gift card payment:

  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 keyed 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 POST request to a Terminal API endpoint, specifying:

    • MessageHeader: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageCategory: Payment
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for this transaction attempt. This needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal. This indicates which terminal the transaction will be routed to.
    • PaymentRequest: The request body for the payment request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this payment request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the payment request, in UTC format.
      • SaleData.SaleReferenceID: Optional parameter to provide your order number. You can use this to connect different gift card transactions to the same order. In the Customer Area, it will appear as the Merchant Order for the transaction.
      • PaymentTransaction.AmountsReq.Currency: The currency of the transaction.
      • PaymentTransaction.AmountsReq.RequestedAmount: The transaction amount.
      • PaymentData.PaymentInstrumentData.PaymentInstrumentType: StoredValue
      • PaymentData.PaymentInstrumentData.StoredValueAccountID: The gift card details:

        • StoredValueAccountType: GiftCard
        • StoredValueProvider: The gift card issuer: givex, svs, or valuelink
        • IdentificationType: PAN
        • EntryMode, StoredValueID and ExpiryDate: These parameters depend on the card entry method you are using.

          Card entry Parameters
          Scan
          • EntryMode: Scanned
          • StoredValueID: Gift card number.
          • ExpiryDate: Expiry date of the gift card.
          Swipe
          • EntryMode: MagStripe
          MKE
          • EntryMode: Keyed
          • StoredValueID: xxxxxxxxxxxxxxxxxxx.

    The example below shows how you would initiate a 10.99 GBP payment with a scanned gift card.

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

    {
        "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"
                    }
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"GBP",
                        "RequestedAmount":10.99
                    }
                },
                "PaymentData":{
                    "PaymentInstrumentData":{
                        "PaymentInstrumentType":"StoredValue",
                        "StoredValueAccountID":{
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"9826150911219687",
                            "ExpiryDate":"1122"
                        }
                    }
                }
            }
        }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    PaymentRequest paymentRequest = new PaymentRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("GBP");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(100.99) );
    paymentTransaction.setAmountsReq(amountsReq);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    PaymentData paymentData = new PaymentData();
    PaymentInstrumentData paymentInstrumentData = new PaymentInstrumentData();
    paymentInstrumentData.setPaymentInstrumentType( PaymentInstrumentType.STORED_VALUE );
    StoredValueAccountID storedValueAccountID = new StoredValueAccountID();
    storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD );
    storedValueAccountID.setStoredValueProvider("svs");
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );
    storedValueAccountID.setStoredValueID("6006491260550218066");
    storedValueAccountID.setExpiryDate("1122");
    paymentInstrumentData.setStoredValueAccountID(storedValueAccountID);
    paymentData.setPaymentInstrumentData(paymentInstrumentData);
    paymentRequest.setPaymentData(paymentData);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

The payment request is sent to the Adyen payments platform for processing.

Payment response

Once processed, your integration receives the payment result. This is provided in a synchronous API response, unless your integration uses asynchronous cloud communications.

If your integration uses asynchronous cloud communications, you receive the result in a TENDER_FINAL display notification.

If the gift card payment is successful:

  • Approved is displayed on the terminal screen.
  • You receive a response that contains a PaymentResponse object. This includes:

    The example below indicates that the gift card payment was successful.

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

    {
        "SaleToPOIResponse":{
            "PaymentResponse":{
                "POIData":{
                    "POITransactionID":{
                        "TimeStamp":"2019-03-26T09:22:16.000Z",
                        "TransactionID":"oLkO001522056136000.9815220561432452"
                    }
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2019-03-26T09:22:21.000Z",
                        "TransactionID":"44740"
                    }
                },
                "PaymentReceipt":[...],
                "PaymentResult":{
                    "PaymentAcquirerData":{
                        "AcquirerPOIID":"V400m-324688179",
                        "AcquirerTransactionID":{
                            "TimeStamp":"2019-03-26T09:22:16.000Z",
                            "TransactionID":"9815220561432452"
                        },
                        "MerchantID":"TestMerchantPOS"
                    },
                    "PaymentInstrumentData":{
                        "StoredValueAccountID":{
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"9826150911219687",
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "ExpiryDate":"1122"
                        },
                        "PaymentInstrumentType":"StoredValue"
                    },
                    "AmountsResp":{
                        "AuthorizedAmount":10.99,
                        "Currency":"GBP"
                    },
                    "PaymentType":"Normal"
                },
                "Response":{
                    "Result":"Success",
                    "AdditionalResponse":"..."
                }
            },
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "SaleID":"POSSystemID12345",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "ServiceID":"9267",
                "POIID":"V400m-324688179",
                "MessageType":"Response"
            }
        }
    }

You can view the details of gift card payments in your Customer Area, under Transactions > Payments.

Making partial payments

If the balance on the gift card is less than the amount due, you can allow the shopper to pay in part with the gift card, and in part with another card or in cash. In each partial payment request, you add a tender option to indicate it is a partial payment, and a reference that enables you to connect the partial payments to the same order.

To make partial payments for a single sale:

  1. Check the balance of the gift card.
  2. Make a gift card payment request for the remaining balance of the gift card and a regular payment request for the remainder of the amount due, and in each of those requests additionally specify:

    • SaleData.SaleToAcquirerData: allowPartialAuthorisation=true
    • SaleData.SaleReferenceID: Unique reference, such as your order number plus a sequence number, that lets you identify partial payments that belong together. 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. In your Customer Area, this will appear as the Merchant Order for the payment.

    This example shows those additional parameters in a partial gift card payment request.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
            ...
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"44740",
                        "TimeStamp":"2019-03-26T09:13:41+00:00"
                    },
                    "SaleToAcquirerData":"allowPartialAuthorisation=true",
                    "SaleReferenceID":"YOUR_ORDER_REFERENCE"
                },
                "PaymentTransaction":{
                    ...
                },
                "PaymentData":{
                    "PaymentInstrumentData":{
                        "PaymentInstrumentType":"StoredValue",
                        "StoredValueAccountID":{
                            ...
                        }
                    }
                }
            }
        }
    }

The payment requests are sent to the Adyen payments platform for processing. Once processed, your integration receives the payment result.

Next steps

See also