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:
-
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 Terminal API request, specifying:
-
The standard
SaleToPOIRequest.MessageHeader
object, withMessageClass
set to Service andMessageCategory
set to StoredValue.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 funds you are loading to the gift card. StoredValueData.Currency
The currency you are loading to the gift card. StoredValueAccountID
The gift card details: StoredValueAccountType
: GiftCardStoredValueProvider
: the gift card issuer: givex, svs, valuelink, or any Intersolve-supported card type.IdentificationType
: PANEntryMode
,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
: MagStripeStoredValueID
: include this parameter but do not provide a value.
MKE EntryMode
: KeyedStoredValueID
: 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.
-
-
In the
StoredValueResponse
, check the following:StoredValueResult.StoredValueTransactionType
: Load andResponse.Result
: Success indicate that funds were loaded.- In the
StoredValueResult
object,ItemAmount
andCurrency
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.