Getting Started with EVO Gift API

Authorization

Authorization is easy, just pass your authenticator in the body of the request. The authenticator is 22 characters long.

"authenticator": "22CharacterMerchantKey"

Content Types

Communicate with us in your favorite content type!

We support the following for Content-Type:

application/json

HTTP Responses

200 OK Accepted Transaction
400 BAD REQUEST Invalid Transaction
401 UNAUTHORIZED Failed Authentication
403 FORBIDDEN Failed Authorization
500 ERROR Unexpected Error

see Response payload for more detail

TranCodes

TranCode	Description
Issue	Activate and load funds on an account
Create	Generate a new account number
Load	Increase the currency balance on an account
Redeem	Decrease the currency balance on an account
Loyalty	Adjust the points balance on an account
Set	Set an attribute of an account (identifier, locked status, currency/points balances)
Balance	Retrieve the currency and/or points balance for the specified account
Void	Undo the effect of a previous transaction by reference number
Detail	Replay the response from a previous tranastion by reference number

Request

(R = Required, C = Conditional, O = Optional)

Payload Element	Issue	Create	Load	Redeem	Loyalty	Set	Balance	Void	Detail
authenticator	R	R	R	R	R	R	R	R	R
trancode	R	R	R	R	R	R	R	R	R
track2¹	C		C	C	C	C	C
account¹	C		C	C	C	C	C
cvv	O		O	O	O	O	O
override_cvv	O		O	O	O	O	O
amount	O		R	R
points²	O		O	O	R
invoice	O	O	O	O	O
override_duplicate	O		O	O	O
partial_auth				O
promo	O	O	O
identifier³		O				C
locked³		O				C
balance³		O				C
points_balance³		O				C
reference								R	R
trace_data	O	O	O	O	O	O	O	O	O

¹ If conditional, only one of these elements is required.
² Sign affects direction of adjustment.
³ If conditional, at least one of these elements is required.

Response

(A = Always, C = Conditional)^*

Payload Element	Issue	Create	Load	Redeem	Loyalty	Set	Balance	Void	Detail
response_code¹	A	A	A	A	A	A	A	A	A
status¹	A	A	A	A	A	A	A	A	A
message¹	A	A	A	A	A	A	A	A	A
trancode	A	A	A	A	A	A	A	A	A
reference	A	C	A	A	A	C		A	A
account	A	A	A	A	A	A	A	A	A
cvv		A
amount	C		A	A				A	A
balance	A	A	A	A	A	C	A	A	A
points	C		C	C	A	C		C	C
points_balance	C	C	C	C	C	C	C	C
invoice	C	C	C	C	C				C
locked		C				C
amount_adjusted						C
promo	C	C	C						C
voided									C
human_readable		A
track1		A
track2		A
balance_url		A
voided_id								A
trace_data	C	C	C	C	C	C	C	C	C

^* This table shows behavior of Approved transactions.
¹ Always returned regardless of status. Use response_code for programmatic behavior.

Data Types

Payload Element	Type	Minimum	Maximum
account	string		30
amount	decimal	0.01	214748.36
amount_adjusted	decimal	-214748.36	214748.36
balance	decimal	-214748.36	214748.36
balance_url	string		50
cvv	string		3
human_readable	string		30
identifier	string		30
invoice	string		16
locked	boolean
authenticator	string		22
message	string		50
override_cvv	boolean
override_duplicate	boolean
partial_auth	boolean
points	integer	-32768	32767
points_balance	integer	0	32767
promo	boolean
reference	integer	0	2⁶³
response_code	integer	1000	9999
status	string		50
track1	string		50
track2	string		50
trancode	string		50
voided	boolean
voided_id	integer	0	2⁶³
trace_data	string		100

Response Codes

Response Codes are 4-digit numbers. The leftmost number, or thousands place, indicates the status.

Thousands	Status
1	Approved
2	Partial
3	Duplicate
4	Declined
5	Invalid
9	Error

Call GET /v1/transactions/response_codes for response code details

JSON Example Redeem Request

                
POST https://[base_url]/v1/transactions

Content-Type: application/json

{
"authenticator": "HM8draWRMkWMc+H8bK3tnQ",
"trancode": "Redeem",
"amount": 5.12,
"track2": ";5614760000000000003=3912000123?",
"trace_data": "123456789012345"
}

            

JSON Example Redeem Response

                200 OK

{
 "response_code": 1000,
 "status": "Approved",
 "message": "Approved",
 "trancode": "Redeem",
 "reference": 39,
 "account": "5614760000000000003",
 "amount": 5.12,
 "balance": 186.25,
 "trace_data": "123456789012345"
}

            

XML Example Redeem Request

                
POST https://[base_url]/v1/transactions

Content-Type: application/xml

<Request>
<authenticator>HM8draWRMkWMc+H8bK3tnQ</authenticator>
<trancode>Redeem</trancode>
<amount>5.12</amount>
<track2>;5614760000000000003=3912000123?</track2>
<trace_data>123456789012345</trace_data>
</Request>

            

XML Example Redeem Response

                200 OK

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <response_code>1000</response_code>
  <status>Approved</status>
  <message>Approved</message>
  <trancode>Redeem</trancode>
  <reference>39</reference>
  <account>5614760000000000003</account>
  <amount>5.12</amount>
  <balance>186.25</balance>
  <trace_data>123456789012345</trace_data>
</Response>

            