Overview
GiftRocker offers a secure JSON REST API to partners needing to create, redeem or check balances of GiftRocker gift cards on behalf of shared merchants. Contact Alex at GiftRocker.com if you are a POS maker or online ordering portal and would like to integrate.
Transaction Types
Transaction types are designated in the API header and in the message body through JSON request and response object names.
| Header Transaction Type | Request Object | Response Object |
|---|---|---|
| GET_BALANCE | getBalance | getBalanceResponse |
| REDEEM | redeem | redeemResponse |
| ADD_VALUE | addValue | addValueResponse |
| ACTIVATE | activate | activateResponse |
| REVERSE | reverse | reverseResponse |
Transaction Header
The transaction header is an array identifying the partner, merchant, transaction type and unique transaction id. The partner and merchant identifiers are used for authentication.
| Array Element Name | Element Value | Description |
|---|---|---|
| Content-Type | application/json | Defines the media type for the service as JavaScript Object Notation (JSON) |
| TransactionType | e.g. GET_BALANCE | See transaction type table for the complete set of values |
| MerchantID | 64 byte GUID | Unique identifier for the merchant in GiftRocker |
| PartnerID | 64 byte GUID | Unique identifier for the partner calling the GiftRocker service |
| TransactionID | 64 byte | Unique identifier for each transaction |
Get Balance
Get Balance will return a gift card’s current value. It can be called prior to a a gift card’s redemption allowing an order to be totaled with a valid gift card prior to placing. Following is the getBalance object from a request, response envelope and getBalanceResponse object:
{“getBalance”: {“giftCardReference”:”ad034bed”}}
{“transactionStatus”:”ACCEPT”,”getBalanceResponse”:{“currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance |
Activate
Activate initializes and sets a value for a gift card reference that is known within GiftRocker and associated with the merchant. Activate works with uninitialized cards and cards that have been fully redeemed. Following is the activate object from a request, response envelope and activateResponse object:
{“activate”: {“initialBalance”:15, “giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”activateResponse”:{“currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance |
Redeem
Redeem subtracts value from a gift card known within GiftRocker and associated with the merchant or associated with the merchant’s enterprise. If a redemption request is larger than the value of the gift card, the redemption value will be limited. Following is the redeem object from a request, response envelope and redeemResponse object:
{“redeem”: {“redeemedValue”:0.25, “giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”redeemResponse”:{“currentBalance”:”14.75″,”redeemedValue”:”0.25″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters |
| request | redeemedValue | currency with two decimal places representing redeem request |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance |
| response | redeemedValue | currency with two decimal places representing the actual value redeemed |
Add Value
Add value adds value to a gift card known within GiftRocker and associated with the merchant or associated with the merchant’s enterprise. Following is the add value object from a request, response envelope and addValueResponse object:
{“addValue”: {“additionalValue”:0.5, “giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”addValueResponse”:{“currentBalance”:”15.00″,”additionalValue”:”0.50″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters |
| request | additionalValue | currency with two decimal places |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance |
| response | additionalValue | currency with two decimal places representing the actual value added |
Reverse
Reverse allows partners to back a transaction out of GiftRocker. Reverse restores the Gift Card to the state and values from before the original transaction. Reverse can be used to ensure system integrity when a response isn’t received from GiftRocker. For example, if a redeem request is originated and no response is received, the originating partner will not know whether the service failed on the request or on the response. Before originating a new request, a reverse should be used referencing the unique identifier of the original transaction. Following is the reverse object from a request, response envelope and reverseResponse object:
{“reverse”: {“previousTransaction”:”106f41f3-6895-447d-a766-d308d546b286″,”giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”reverseResponse”:{“currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | previousTransaction | up to 64 characters, TransactionID from the original request |
| request | giftCardReference | 8-64 characters |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance |
Error Messages
Successful requests will return an HTTP 200 status. Unsuccessful requests will return an HTTP 400 status and one of the following transaction status constants:
ERROR_INVALID_TRANSACTION_TYPE
ERROR_CARD_ALREADY_ACTIVATED
ERROR_CARD_NOT_ACTIVATED
ERROR_CARD_INVALID
ERROR_INVALID_INPUT_PROPERTIES
ERROR_TRANSACTION_DOES_NOT_EXIST
ERROR_TRANSACTION_CANNOT_BE_REVERSED
ERROR_INVALID_MERCHANT
ERROR_SUSPENDED_MERCHANT
Security
To guard against robots programmed to guess gift card references, GiftRocker requires Google’s CAPTCHA on gift card interfaces. As an additional measure, if GiftRocker detects more than 20 invalid gift card references within an hour for a merchant, that merchant’s account will be suspended for the hour and GiftRocker support will be notified.