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, online ordering portal or marketing platform 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 |
| CREATE | create | createResponse |
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 |
Create
Create allows partners to generate gift cards or promotions, e.g. a $20 gift card for a good review. Shopkeepers grant permission to partners to generate these certificates on their behalf and can set limits on denomination and frequency. Following is the request and response when creating a certificate:
{“create”: {“createValue”:15, “recipient”:”alex@giftrocker.com”,”offering”:”c3por2d2″orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”createResponse”:{“reference”:”728243859827″,”currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | createValue | Optional depending on offering. If traditional gift cards, createValue is currency. If a fixed price promotion, not required. If an event ticket, could be ticket count |
| request | recipient | Required – email or US phone number |
| request | offering | Required – an offering is equivalent to a campaign. Different offerings can have different limits and effective periods and can be gift cards, promotions or event tickets |
| 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 | reference | 8 to 64 alpha numeric certificate reference |
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 Message | Description |
|---|---|
| ERROR_INVALID_TRANSACTION_TYPE | Not GET_BALANCE, REDEEM, ACTIVATE, ADD_BALANCE, REVERSE or CREATE |
| ERROR_CARD_ALREADY_ACTIVATED | Attempting to activate a card that is already active |
| ERROR_CARD_NOT_ACTIVATED | GET_BALANCE on a card that is not activated |
| ERROR_CARD_INVALID | Card not found for this merchant |
| ERROR_INVALID_INPUT_PROPERTIES | One or more attributes are invalid |
| ERROR_TRANSACTION_DOES_NOT_EXIST | Attempt to reverse failed because the original transaction was not received. Ok to resubmit the original transaction |
| ERROR_TRANSACTION_CANNOT_BE_REVERSED | Either reverse is not supported on this transaction type or the underlying certificate changed in a way where this reverse would not make sense |
| ERROR_INVALID_MERCHANT | Merchant ID in header is not found |
| ERROR_SUSPENDED_MERCHANT | Merchant api requests included too many failed balance lookups suggesting robotic cracking activity |
| ERROR_INVALID_RECIPIENT | Email invalid or phone not 10 digits |
| ERROR_INVALID_OFFERING1 | Offering does not exist |
| ERROR_INVALID_OFFERING2 | Merchant is not authorized to use this offering. You may have a different merchant’s offering |
| ERROR_INVALID_OFFERING3 | Cannot create certificate from offering |
| ERROR_INVALID_AMOUNT | Amount is not numeric or not within the offering’s lower and upper limit |
| ERROR_BANNED_RECIPIENT | Email or phone associated to a bad apple, e.g. disputed transaction |
| ERROR_CREATE_DUPLICATE | Offering has a limit of one per email/phone |
| ERROR_CREATE_LIMIT_REACHED | Offering creates have exceeded limit set by merchant. Limits can be hourly, daily or lifetime |
| ERROR_NOT_YET_AVAILABLE | Offering’s sell begin date is in the future |
| ERROR_NO_LONGER_AVAILABLE | Offering’s sell end date is in the past |
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.