Dev Docs

Gift Card API

The RETAIL7 Gift Card API can be used to perform a variety of actions related to gift cards. These actions include e.g.:

  • Status check

  • Sell

  • Load

  • Redeem

  • Cancel

  • Create without sell

  • Update

  • Lock

  • Unlock

  • Close

Check status

If you want to get information about gift card status (e.g. balance, validity, etc.) you can use the following request:

Body

The valid json looks like that:

{
"requestIDExternal": "GC10",
"timestamp": "2021-02-21T11:30:25.930Z",
"trainingFlag": false,
"operationType": "STATUS",
"cardID": "12399",
"clientStore": "1001",
"clientCountry": "US",
"clientID": "1001"
}

Definition

Field

Type

Sample

Description

Mandatory

requestIDExternal

string (40)

"12345"

ID of the STATUS request. Must be unique.

M

timestamp

timestamp

"2021-02-21T11:30:25.930Z"

Timestamp of the operation. 

M

trainingFlag

boolean

"True" or "False"

Flag which reflects if operating in training mode (true) or not (false).

M

operationType

string (40)

"STATUS"

Type of the requested gift card operation.

M

cardID

string (40)

"12345"

ID of the gift card relevant to the operation.

M

clientStore

string (40)

"12345"

Store ID

M

clientCountry

string (40)

"DE"

ISO 3166-1 alpha-2 code of the country.

M

clientID

string (40)

"12345"

ID of the client posting the request.

M

Sell gift card

Body

The valid json looks like that:

{
"requestIDExternal": "GC10",
"timestamp": "2021-02-21T11:30:25.930Z",
"trainingFlag": false,
"operationType": "SELL",
"cardID": "1234567",
"amount": 5.00,
"currencyCode": "USD",
"clientStore": "1001",
"clientCountry": "US",
"clientID": "1001",
"clientTrx": "1001201910311001000004"
"issuedByClient": false,
"validFrom": "2021-02-20",
"validUntil": "2023-02-20"
}

Definition

Field

Type

Sample

Description

Mandatory

requestIDexternal

string (40)

ID of the SELL request. Must be unique.

M

timestamp

timestamp

"2019-10-31T21:29:51.779Z"

Timestamp of the operation. 

M

trainingFlag

boolean

"false"

Indicator, if operating in training mode (true) or not (false).

M

operationType

string (40)

"SELL"

Type of the requested gift card operation.

M

cardID

string (40)

"12399"

ID of the gift card relevant to the operation.

M

cardTypeCode

string (40)

"01"

Used only when gift card is issued by the client - it defines the type code of the gift card.

O

amount

number

"5.00"

Amount of the operation. In case of SELL operation it defines the initial gift card balance.

M

maxBalance

number

"500.00"

Used only when gift card is issued by the client - it defines the maximum balance. The value can be taken from configuration. If not defined by the request, server default is used.

O

currencyCode

string (3)

"EUR"

ISO 4217 code of the currency of the operation. 

M

clientStore

string (40)

"1001"

Store ID of the client posting the request.

M

clientCountry

string (40)

"DE"

ISO 3166-1 alpha-2 code of the country of the client posting the request.

M

clientID

string (40)

"1001"

ID of the client posting the request.

M

clientTrx

string (40)

"1001201910311001000004"

ID of the transaction containing gift card sale / return / tender line item, created by the client.

M

issuedByClient

boolean

"false"

Indicator, if the gift card was issued by client (true) or not (false).

M

validFrom

date

"2021-02-20"

This defines from when is the gift card valid for redemption. Usually it is the date of sale. If it is not filled in the request, then it is set to current date.

O

validUntil

date

"2023-02-20"

This defines until when is the gift card valid for redemption. If it is not filled in the request, then:

  • for existing gift card it is set according to the validity period defined for that gift cards

  • for gift card issued by POS it is set according to the validity period defined in the server configuration

O

reloadAllowed

boolean

"false"

Used only when gift card is issued by the client - it defines if gift card is re-loadable. The value can be taken from configuration. If not defined by the request, server default is used.

O

returnAllowed

boolean

"true"

Used only when gift card is issued by the client - it defines if gift card can be returned. The value can be taken from configuration. If not defined by the request, server default is used.

O

partRedeemAllowed

boolean

"false"

Used only when gift card is issued by the client - it defines if gift card can be redeemed in part. The value can be taken from configuration. If not defined by the request, server default is used.

O

reason

string (40)


If captured a reason code during the process, it is also passed on in the request.

O

Load gift card

Body

The valid json looks like that:

{
"requestIDExternal": "GC111",
"timestamp": "2021-02-21T11:30:25.930Z",
"trainingFlag": false,
"operationType": "LOAD",
"cardID": "12300",
"amount": 5.00,
"currencyCode": "USD",
"clientStore": "1001",
"clientCountry": "US",
"clientID": "1001",
"clientTrx": "1001201910311001000004"
}

Definition

Field

Type

Sample

Description

Mandatory

requestIDexternal

string (40)


ID of the LOAD request assigned by the client. Must be unique.

M

timestamp

timestamp

"2021-02-21T11:30:25.930Z"

Timestamp of the operation (on client side). 

M

trainingFlag

boolean

"false"

Indicator, if the client is operating in training mode (true) or not (false).

M

operationType

string (40)

"LOAD"

Type of the requested gift card operation.

M

cardID

string (40)

"12399"

ID of the gift card relevant to the operation.

M

amount

number

"5.00"

Amount of the operation.

M

currencyCode

string (3)

"EUR"

ISO 4217 code of the currency of the operation. 

M

clientStore

string (40)

"1001"

Store ID of the client posting the request.

M

clientCountry

string (40)

"DE"

ISO 3166-1 alpha-2 code of the country of the client posting the request.

M

clientID

string (40)

"1001"

ID of the client posting the request.

M

clientTrx

string (40)

"1001201910311001000004"

ID of the transaction containing gift card sale / return / tender line item, created by the client.

M

reason

string (40)


If client captured a reason code during the process, it is also passed on in the request.

O