Gift and Stored Value Card API Fields
| Field | Name | Length Type |
Description |
|---|---|---|---|
| 0001 | Transaction Type | 2 numeric |
Required. Refer to the Transaction Matrix. |
| 0007 | Reference Number | 7 numeric |
Unique reference number to transaction. |
| 0011 | User-Defined Field | 80 alphanumeric |
Conditional. Required for SVS virtual cards only. Value = VIRTUAL |
| 0017 | Cash Back | 1-14 cents |
Conditional. Amount of cash back included in the amount Field 0002. Required for SVS virtual cards only. |
| 0018 | Debit PIN Block | 16 alphanumeric |
Conditional. Required for SVS virtual cards only. Value = 1234 |
| 0036 | Transaction Identifier | 1-15 alphanumeric |
Conditional. Contains the unique tracking number assigned by the credit card issuing bank. Third Party Processor Interface- specific. |
| 0043 | System Trace Audit Number | 6 numeric |
Conditional. A host assigned reference number used for tracking purposes. When returned, must be printed on receipt. |
| 0060 | Unique Device ID | 1-8 numeric |
Required. Must be stored and displayed and may be used for settlement. Used to identify the source lane or terminal through which a transaction is processed. |
| 0115 | Transaction Qualifier | 3 numeric |
Required. Identified type of account used. Gift and Stored Value Card = 050. Refer to the Transaction Matrix. |
| 0117 | Stored Value Function | 1 numeric |
Required. Indicates Stored value transaction function: 1 = Activate 2 = Issue 3 = Reload 4 = Return 5 = Redeem 6 = Redeem w/ cash back 7 = Prior Auth |
| 0128 | CPS Original Authorization Amount | 1-14 cents |
Conditional. Valid format: 0.00 – 99999.99 |
| 0130 | CPS Total Authorized Amount | 1-14 cents |
Conditional. Approved Amount. Valid format: 0.00 – 99999.99 |
| 0201 | Tip Amount | 1-14 cents |
Conditional. Amount of Tip Valid format: 0.00 – 9999.99. Third Party Processor Interface-specific. |
| 0632 | Account Balance | 1-14 cents |
Conditional. New Account Balance. Valid format: 0.00 – 99999.99. Third Party Processor Interface- specific. |
| 0645 | Previous Balance | 11 numeric |
Conditional. Previous balance on card. Third Party Processor Interface- specific. |
| 1035 | Total Number of Cards | 2 numeric |
Conditional. Total number of cards being issued at one time. Third Party Processor Interface- specific. |
| 1036 | Sequence Number of Card | 2 numeric |
Conditional. Determines sequence numbers when multiple cards are issued. Third Party Processor Interface- specific. |
Declines of Approved Cards
INACTIVE CARD - Doing any transaction other than Activate or Issue for a card that is not already active.
INSUFF FUNDS - Redeeming more than available balance allows.
CRD ALRDY ISSUED - Activate or Issue requested on a card that has already been issued.
CRD NOT ISSUED - Card Reload transaction used on a card that has not been Issued or Activated.
CARD ALRDY USED - Reversal/Cancel transaction attempted on issue gift card after card has been redeemed.
CARD FROZEN - Trying to lock the amount when a lock already exists.
NO RECORDS FOUND - Previous transaction could not be found.
Approvals
To get an approval, use any card number that is not defined in Demo Card Scenarios. While most requests are approved, logic is performed based on the status and balance of a card which can result in the following declines.
Account Balance and Open-to-Buy (24)
Transaction Type 24 (Account Balance and Open-to-Buy) is used to obtain the current account balance or open-to-buy amount for an association pre-paid gift card or stored value card. Pre-paid gift cards are not supported by all TPPS. If the TPP does not support this transaction type, a TRANSACTION NOT SUPPORTED error is returned from the application.
It is recommended that the POS application support this transaction type.
Refer to the appropriate Third Party Processor Interface guide(s) for additional information on how to determine if this transaction type is supported, and the requirements for the Input Request and Output Response.
Gift and Stored Value Card Transaction Matrix
| Transaction | Tran Type (API 0001) | Debit PIN Block* (API 0018) | Transaction Qualifier (API 0115) | Stored Value Function (API 0117) | Tip Amount (API 0201) |
|---|---|---|---|---|---|
| Authorization Only | 01 | 050 | N/A | ||
| Close Card | 02 | 050 | 3 | ||
| Redemption | 02 | 050 | 5 | ||
| Redemption Virtual | 02 | 1234 | 050 | 5 | |
| Redemption (Cash Back/Cash Out/Unload) | 02 | 050 | 6 | ||
| Tip | 02 | 050 | 5 | $$$$$$.$$ | |
| IVR Authorized Redemption | 07 | 050 | 7 | ||
| Prior Auth/Unlock | 07 | 050 | 7 | ||
| Card Activation | 09 | 050 | 1 | ||
| Issue Card | 09 | 050 | 2 | ||
| Issue Virtual Card | 09 | 050 | 2 | ||
| Reload/Recharge | 09 | 050 | 3 | ||
| Return | 09 | 050 | 4 | ||
| Void Redemption | 11 | 050 | 5 | ||
| Void Redemption (Cash/Cash Back/Unload) | 11 | 050 | 6 | ||
| Void Prior Auth/Unlock/IVR Auth | 11 | 050 | 7 | ||
| Local Batch Close | 13 | N/A | |||
| Local Batch Inquiry | 14 | N/A | |||
| Void Activation/Deactivate | 17 | 050 | 1 | ||
| Void Card Issue | 17 | 050 | 2 | ||
| Void Reload/Recharge | 17 | 050 | 3 | ||
| Void Return | 17 | 050 | 4 | ||
| Balance Inquiry | 24 | 050 | N/A |
note
API Field 0018 is used only in conjunction with Virtual Cards.
Gift card demo mode runs transactions that mimic gift card functionality. For example, any approved card can be redeemed until the amount issued is exhausted. All cards are reset automatically at midnight, Eastern (EST).