Cards/Wallet API Integration

This document is focused on the activities required from a technology perspective to integrate partner systems with the gift card / wallet program systems.

The document would be best suited to be used by the partner IT teams to support integration.

Scope

The scope of this document covers:

  • Checking the balance of a gift card

  • Redeeming

  • Top Up (Sale)

Check Balance

POST /api/interface/gift-card/check

Method

Keyward
Value

EndpointURI

Main API endpoint provided separately

URI

interface/gift-card/check

Call Type

POST

HTTP Address

<endpoint>/api/interface/gift-card/check

Request Headers

Keyward
Value

Verb

POST

Authorisation

HTTP Bearer (access-token)

Content-Type

application/json

Request Body

Property Name
Type
Description
Mandatory

cardNumber

string

The gift card number

Yes

Request Body Example

Example
Schema
}
    “cardNumber”:“123456789”
}
GiftCardCheckRequest { 
  cardNumber: string; 
}

Responses

Code
Example
Description

403

{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}

Invalid Bearer token

400

{
"statusCode": 400,
"message": "Bad Request"
}

cardNumber is missing; cardNumber is not a string; cardNumber is not a numeric string;

200

{
"cardNumber": "123456789",
"balance": 8.5
}

Gift card found

404

{
"message": "Gift card not found"
}

Gift card not found

400

{
"message": "Gift card inactive"
}

Found gift card is not active

400

{
"message": "Gift card expired"
}

Found gift card has expired

400

{
"message": "Insufficient permissions
for gift card type"
}

The access token provided has insufficient permissions to retrieve gift card. Contact UpCo to resolve

Successful Response Example

Example
Schema
{ 
  "cardNumber": "123456789", 
  "balance": 8.5
}

GiftCardCheckResponse {
   cardNumber: string;
   balance: number;
}

Redeem

Redem can only be performed with amount equal or smaller than the card balance

POST /api/interface/gift-card/redeem

Method

Keyward
Value

EndpointURI

Main API endpoint provided separately

URI

interface/gift-card/redeem

Call Type

POST

HTTP Address

<endpoint>/api/interface/gift-card/redeem

Request Headers

Keyward
Value

Verb

POST

Authorisation

HTTP Bearer (access-token)

Content-Type

application/json

Request Body

Property Name
Type
Description
Mandatory

cardNumber

string

The gift card number

Yes

amount

number

The amount to be redeemed

Yes

Request Body Example

Example
Schema
}
   “cardNumber” : “123456789”,
   “amount” : 5.00
}
GiftCardRedemptionRequest {
    cardNumber: string;
    amount: number;
}

Response

Code
Example
Description

403

{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}

Invalid Bearer token

400

{
"statusCode": 400,
"message": "Bad Request"
}

cardNumber is missing;

cardNumber is not a string;

cardNumber is not a numeric string;

amount is missing;

amount is not a number;

amount is not a positive number;

201

{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}

Successful redemption transaction created

404

{
"message": "Gift card not found"
}

Gift card not found

400

{
"message": "Gift card inactive"
}

Found gift card is not active

400

{
"message": "Gift card expired"
}

Found gift card has expired

400

{
"message": "Insufficient permissions
for gift card type"
}

The access token provided has insufficient permissions to retrieve gift card. Contact UpCo to resolve

400

{
    "message": "Insufficient balance"
}

The amount to be redeemed exceeds the balance of the found gift card

400

{
"message": "Gift card redemption
failed"
}

The gift card was found but the redemption transaction could not be completed.

Successful Response Example

Example
Schema
{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}

GiftCardRedemptionResponse {
cardNumber: string;
balance: number;
previousBalance: number;
amountRedeemed: number;
success: boolean;
reference: number;
}

Top Up

POST /api/interface/gift-card/top-up

Method

Keyward
Value

EndpointURI

Main API endpoint provided separately

URI

interface/gift-card/top-up

Call Type

POST

HTTP Address

<endpoint>/api/interface/gift-card/top-up

Request Headers

Keyward
Value

Verb

POST

Authorisation

HTTP Bearer (access-token)

Content-Type

application/json

Request Body

Property Name
Type
Description
Mandatory

cardNumber

string

The gift card number

Yes

amount

number

The amount to be redeemed

Yes

Request Body Example

Example
Schema
}
   “cardNumber” : “123456789”,
   “amount” : 5.00
}
GiftCardTopupRequest {
    cardNumber: string;
    amount: number;
}

Response

Code
Example
Description

403

{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}

Invalid Bearer token

400

{
"statusCode": 400,
"message": "Bad Request"
}

cardNumber is missing;

cardNumber is not a string;

cardNumber is not a numeric string;

amount is missing; amount is not a number;

amount is not a positive number;

201

{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}

Successful top up transaction created

404

{
"message": "Gift card not found"
}

Gift card not found

400

{
"message": "Gift card inactive"
}

Found gift card is not active

400

{
"message": "Gift card expired"
}

Found gift card has expired

400

{
"message": "Insufficient permissions
for gift card type"
}

The access token provided has insufficient permissions to retrieve gift card. Contact UpCo to resolve

400

{
    "message": "Gift card top up failed"
}

The gift card was found but the top up transaction could not be completed.

Successful Response Example

Example
Schema
{
"cardNumber": "123456789",
"balance": 10,
"previousBalance": 8.5,
"topupAmount": 1.5,
"success": true,
"reference": 458829
}

GiftCardTopUpResponse {
cardNumber: string;
balance: number;
previousBalance: number;
amountRedeemed: number;
success: boolean;
reference: number;
}

Last updated