Load funds to a gift card

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

Requirements

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: the standard SaleToPOIRequest.MessageHeader object. Specify:

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		StoredValue
     MessageType		Request
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     SaleID		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • StoredValueRequest.SaleData. This includes:

     Parameter	Required	Description
     SaleTransactionID.TransactionID		Your reference to identify this load request. We recommend using a unique value.
     SaleTransactionID.TimeStamp		Date and time of the request, in UTC format.
     SaleToAcquirerData		Optional, for Stored Value Solutions (SVS) gift cards: ssc. This is the secondary security code of the gift card, and allows up to 8 digits. For example, ssc=1111.

   • StoredValueRequest.StoredValueData. This includes:

     Parameter	Required	Description
     StoredValueTransactionType		Load
     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.
     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 do not provide a value.
     MKE	EntryMode: Keyed StoredValueID: include this parameter but do not provide a value.

   The example below shows how to load GBP 15.00 to a scanned gift card.

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 GBP 15.00 was successfully loaded to the gift card.

  See the StoredValueResponse API reference.

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