Terminal-2 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. This allows you to increase a card's existing balance or load an initial amount of funds.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement Description
Integration type A Terminal API integration with payment terminals.
Setup steps Before you begin:

Make a load request

To load funds 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 Terminal API request, specifying:

    • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to StoredValue.

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- StoredValue
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- 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 -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- 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 -white_check_mark- Your reference to identify this load request. We recommend using a unique value.
      SaleTransactionID.TimeStamp -white_check_mark- 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 -white_check_mark- Load
      StoredValueData.ItemAmount -white_check_mark- The value of the funds you are loading to the gift card.
      StoredValueData.Currency -white_check_mark- The currency you are loading to the gift card.
      StoredValueAccountID -white_check_mark- 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.

    See the StoredValueRequest API reference.

  3. In the StoredValueResponse, check the following:

    • StoredValueResult.StoredValueTransactionType: Load and Response.Result: Success indicate that funds were loaded.
    • In the StoredValueResult object, ItemAmount and Currency indicate the total value and the currency associated with the gift card.
    • POIData.POITransactionID.TransactionID: This is the Transaction identifier for the funds being loaded to the gift card.

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

    {
      "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"
        }
      }
    }

    See the StoredValueResponse API reference.

See also