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:
- 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.
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: This follows the standardMessageHeader
structure, explained in Terminal API fundamentals, which includes:ProtocolVersion
: 3.0MessageCategory
: StoredValueMessageType
: RequestSaleID
: 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
: GiftCardStoredValueProvider
: The gift card issuer: givex, svs, valuelink, or any Intersolve-supported card type.IdentificationType
: PAN-
EntryMode
,StoredValueID
andExpiryDate
: These parameters depend on the card entry method you are using.Card entry Parameters Scan EntryMode
: ScannedStoredValueID
: Gift card number.ExpiryDate
: Expiry date of the gift card.
Swipe EntryMode
: MagStripe
MKE EntryMode
: KeyedStoredValueID
: 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.
{ "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 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.-
StoredValueResult
:StoredValueTransactionType
: Load-
ItemAmount
andCurrency
: 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" } } }