GiftRocker API Specification

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 TypeRequest ObjectResponse Object
GET_BALANCEgetBalancegetBalanceResponse
REDEEMredeemredeemResponse
ADD_VALUEaddValueaddValueResponse
ACTIVATEactivateactivateResponse
REVERSEreversereverseResponse

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 NameElement ValueDescription
Content-Typeapplication/jsonDefines the media type for the service as JavaScript Object Notation (JSON)
TransactionTypee.g. GET_BALANCESee transaction type table for the complete set of values
MerchantID64 byte GUIDUnique identifier for the merchant in GiftRocker
PartnerID64 byte GUIDUnique identifier for the partner calling the GiftRocker service
TransactionID64 byteUnique 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″}}

ActionLabelDescription
requestgiftCardReference8-64 characters
responsetransactionStatusACCEPT is the desired status. Error messages can be found below.
responsecurrentBalancecurrency 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″}}

ActionLabelDescription
requestgiftCardReference8-64 characters
requestorderIDOptional but recommended up to 64 character order identifier from the requesting partner.
responsetransactionStatusACCEPT is the desired status. Error messages can be found below.
responsecurrentBalancecurrency 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″}}

ActionLabelDescription
requestgiftCardReference8-64 characters
requestredeemedValuecurrency with two decimal places representing redeem request
requestorderIDOptional but recommended up to 64 character order identifier from the requesting partner.
responsetransactionStatusACCEPT is the desired status. Error messages can be found below.
responsecurrentBalancecurrency with two decimal places representing the gift card’s balance
responseredeemedValuecurrency 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″}}

ActionLabelDescription
requestgiftCardReference8-64 characters
requestadditionalValuecurrency with two decimal places
requestorderIDOptional but recommended up to 64 character order identifier from the requesting partner.
responsetransactionStatusACCEPT is the desired status. Error messages can be found below.
responsecurrentBalancecurrency with two decimal places representing the gift card’s balance
responseadditionalValuecurrency 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″}}

ActionLabelDescription
requestpreviousTransactionup to 64 characters, TransactionID from the original request
requestgiftCardReference8-64 characters
requestorderIDOptional but recommended up to 64 character order identifier from the requesting partner.
responsetransactionStatusACCEPT is the desired status. Error messages can be found below.
responsecurrentBalancecurrency 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, if GiftRocker detects more than 10 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.

Comments are closed.