Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Load funds to a gift card

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

You can add funds to an activated gift card by making a load request.

Before you begin

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

Make a load request

To load a balance to a gift card:

  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: 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, valuelink, or any Intersolve-supported card type.
        • 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
          • StoredValueID: Include this parameter but don't provide a value.
          MKE
          • EntryMode: Keyed
          • StoredValueID: Include this parameter but don't provide a value.
      • 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 scanned gift card.

    For more information on the Terminal API request structure, see 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",
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"6006491260550218066",
                            "ExpiryDate":"1122"
                        },
                        "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.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );
    storedValueAccountID.setStoredValueID("6006491260550218066");
    storedValueAccountID.setExpiryDate("1122");
    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.

Load response

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 response as an event 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.
    • StoredValueResult:

      • StoredValueTransactionType: Load
      • ItemAmount and Currency: Current value and currency associated with the card.

    • 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, see the Terminal API fundamentals.

    {
      "SaleToPOIResponse":{
        "StoredValueResponse":{
          "POIData":{
            "POITransactionID":{
              "TimeStamp":"2019-03-26T09:31:29.000Z",
              "TransactionID":"oLkO001522056689002.9815220566972551"
            }
          },
          ...
          "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

See also