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; }