Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Load balance to a gift card

Add funds to a gift card at the point of sale.

You can load funds to an activated gift card by making a load balance request. When the request is processed, you receive a result indicating whether the balance was successfully loaded to the gift card.

Before you begin

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

Step 1: Load balance request

To load a balance to a gift card:

  • 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: StoredValue
      • 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.

    • StoredValueRequest: The request body for the load request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the request, in UTC format.
      • StoredValueData.StoredValueTransactionType: Load
      • StoredValueData.StoredValueAccountID: The gift card details:

        • StoredValueAccountType: GiftCard
        • StoredValueProvider: The gift card issuer: givex, svs, or valuelink
        • ExpiryDate: The expiry date of the gift card.
        • EntryMode: MagStripe or Scanned
        • IdentificationType: PAN or BarCode
        • StoredValueID: The gift card number.

      • StoredValueData.ItemAmount: The value of the balance you are loading to the gift card.
      • StoredValueData.Currency: The currency you are loading to the gift card.

    The example below shows how you would load 15.00 GBP to a 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":"StoredValue",
                "MessageType":"Request",
                "ServiceID":"9265",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            },
            "StoredValueRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"44739",
                        "TimeStamp":"2019-03-26T09:31:34+00:00"
                    }
                },
                "StoredValueData":[
                    {
                        "StoredValueTransactionType":"Load",
                        "StoredValueAccountID":{
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "ExpiryDate":"1122",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "IdentificationType":"PAN",
                            "StoredValueID":"6006491260550218066"
                        },
                        "ItemAmount":15.00,
                        "Currency":"GBP"
                    }
                ]
            }
        }
    }
    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.STORED_VALUE );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    StoredValueRequest storedValueRequest = new StoredValueRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    storedValueRequest.setSaleData(saleData);
    
    StoredValueData storedValueData = new StoredValueData();
    storedValueData.setStoredValueTransactionType( StoredValueTransactionType.LOAD );
    StoredValueAccountID storedValueAccountID = new StoredValueAccountID();
    storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD );
    storedValueAccountID.setStoredValueProvider("svs");
    storedValueAccountID.setExpiryDate("1122");
    storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.setStoredValueID("6006491260550218066");
    storedValueData.setStoredValueAccountID(storedValueAccountID);
    storedValueData.setItemAmount( BigDecimal.valueOf(10) );
    storedValueData.setCurrency("GBP");
    storedValueRequest.setStoredValueData(storedValueData);
    saleToPOIRequest.setStoredValueRequest(storedValueRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

The request to load a balance to the gift card is sent to the Adyen payments platform for processing.

Step 2: Receive load balance result

Once processed, your integration receives a result indicating whether the balance was loaded to the gift card.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 funds were successfully loaded to the gift card:

  • You receive a response that contains a StoredValueResponse object. This includes:

    • POIData.POITransactionID.TransactionID: Transaction identifier for the funds being loaded to the gift card.
    • PaymentReceipt: Object containing data you can use to generate a receipt.
    • PaymentResponse.Response.Result: Success

    The example below indicates that 15.00 GBP was successfully loaded to the gift card.

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

    {
        "SaleToPOIResponse":{
            "StoredValueResponse":{
                "POIData":{
                    "POITransactionID":{
                        "TimeStamp":"2019-03-26T09:31:29.000Z",
                        "TransactionID":"oLkO001522056689002.9815220566972551"
                    }
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2019-03-26T09:31:34.000Z",
                        "TransactionID":"44739"
                    }
                },
                "PaymentReceipt":[...],
                "StoredValueResult":[
                    {
                        "StoredValueTransactionType":"Load",
                        "ItemAmount":15.00,
                        "Currency":"GBP"
                    }
                ],
                "Response":{
                    "Result":"Success"
                }
            },
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "SaleID":"POSSystemID12345",
                "MessageClass":"Service",
                "MessageCategory":"StoredValue",
                "ServiceID":"9265",
                "POIID":"V400m-324688179",
                "MessageType":"Response"
            }
        }
    }

Next steps