Load funds to a gift card

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:

• Built an integration that can make a payment.
• Completed the onboarding process with your gift card provider.
• Added the payment method to your Adyen account.

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
         MKE	EntryMode: Keyed StoredValueID: xxxxxxxxxxxxxxxxxxx.

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

   https://docs.adyen.com/point-of-sale/make-a-payment/gift-cards-terminal-api/load-a-balance#load-a-balance_0

   • JSON
   • Java

   JSON Java

   {
       "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 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, refer to 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