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

requestIDExternal

Type: string (40)

Sample: "12345"

Description: ID of the STATUS request. Must be unique.

Mandantory: M

timestamp

Type: timestamp

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

Description: Timestamp of the operation. 

Mandantory: M

trainingFlag

Type: boolean

Sample: "True" or "False"

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

Mandantory: M

operationType

Type: string (40)

Sample: "STATUS"

Description: Type of the requested gift card operation.

Mandantory: M

cardID

Type: string (40)

Sample: "12345"

Description: ID of the gift card relevant to the operation.

Mandantory: M

clientStore

Type: string (40)

Sample: "12345"

Description: Store ID

Mandantory: M

clientCountry

Type: string (40)

Sample: "DE"

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

Mandantory: M

clientID

Type: string (40)

Sample: "12345"

Description: ID of the client posting the request.

Mandantory: 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

requestIDexternal

Type: string (40)

Sample: -

Description: ID of the SELL request. Must be unique.

Mandatory: M

timestamp

Type: timestamp

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

Description: Timestamp of the operation. 

Mandatory: M

trainingFlag

Type: boolean

Sample: "false"

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

Mandatory: M

operationType

Type: string (40)

Sample: "SELL"

Description: Type of the requested gift card operation.

Mandatory: M

cardID

Type: string (40)

Sample: "12399"

Description: ID of the gift card relevant to the operation.

Mandatory: M

cardTypeCode

Type: string (40)

Sample: "01"

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

Mandatory: O

amount

Type: number

Sample: "5.00"

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

Mandatory: M

maxBalance

Type: number

Sample: "500.00"

Description: 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.

Mandatory: O

currencyCode

Type: string (3)

Sample: "EUR"

Description: ISO 4217 code of the currency of the operation.

Mandatory: M

clientStore

Type: string (40)

Sample: "1001"

Description: Store ID of the client posting the request.

Mandatory: M

clientCountry

Type: string (40)

Sample: "DE"

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

Mandatory: M

clientID

Type: string (40)

Sample: "1001"

Description: ID of the client posting the request.

Mandatory: M

clientTrx

Type: string (40)

Sample: "1001201910311001000004"

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

Mandatory: M

issuedByClient

Type: boolean

Sample: "false"

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

Mandatory: M

validFrom

Type: date

Sample: "2021-02-20"

Description: 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.

Mandatory: O

validUntil

Type: date

Sample: "2023-02-20"

Description: 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

Mandatory: O

reloadAllowed

Type: boolean

Sample: "false"

Description: 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.

Mandatory: O

returnAllowed

Type: boolean

Sample: "true"

Description: 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.

Mandatory: O

partRedeemAllowed

Type: boolean

Sample: "true"

Description: 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.

Mandatory: O

reason

Type: string (40)

Sample: -

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

Mandatory: 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

requestIDexternal

Type: string (40)

Sample: -

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

Madatory: M

timestamp

Type: timestamp

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

Description: Timestamp of the operation (on client side). 

Madatory: M

trainingFlag

Type: boolean

Sample: "false"

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

Madatory: M

operationType

Type: string (40)

Sample: "LOAD"

Description: Type of the requested gift card operation.

Madatory: M

cardID

Type: string (40)

Sample: "12399"

Description: ID of the gift card relevant to the operation.

Madatory: M

amount

Type: number

Sample: "5.00"

Description: Amount of the operation.

Madatory: M

currencyCode

Type: string (3)

Sample: "EUR"

Description: ISO 4217 code of the currency of the operation. 

Madatory: M

clientStore

Type: string (40)

Sample: "1001"

Description: ID of the client posting the request.

Madatory: M

clientCountry

Type: string (40)

Sample: "DE"

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

Madatory: M

clientID

Type: string (40)

Sample: "1001"

Description: ID of the client posting the request.

Madatory: M

clientTrx

Type: string (40)

Sample: "1001201910311001000004"

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

Madatory: M

reason

Type: string (40)

Sample: -

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

Madatory: O