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, but you will need to provide some additional details relating to the gift card. You can collect this information by swiping or scanning the gift card, or manually keying it on your cash register or terminal. When this payment request has been processed, you receive the result of the gift 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:

Step 1: Make payment request

To initiate a gift card payment:

  • 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
        • ExpiryDate: The gift card expiry date.
        • EntryMode: MagStripe or Scanned
        • StoredValueProvider: The gift card issuer: givex, svs, or valuelink
        • IdentificationType: PAN or BarCode
        • StoredValueID: The gift card number.

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

    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",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueProvider":"svs",
                            "IdentificationType":"PAN",
                            "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.getEntryMode().add( EntryModeType.SCANNED );
    storedValueAccountID.setStoredValueProvider("goldsmiths");
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.setStoredValueID("9826150911219687");
    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.

Step 2: Receive payment result

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