APi Reference
  • Cards/Wallet API Integration
Powered by GitBook
On this page
  • Scope
  • Check Balance
  • Method
  • Request Headers
  • Request Body
  • Request Body Example
  • Responses
  • Successful Response Example
  • Redeem
  • Method
  • Request Headers
  • Request Body
  • Request Body Example
  • Response
  • Successful Response Example
  • Top Up
  • Method
  • Request Headers
  • Request Body
  • Request Body Example
  • Response
  • Successful Response Example

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

Responses

Code
Example
Description

403

Invalid Bearer token

400

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

200

Gift card found

404

Gift card not found

400

Found gift card is not active

400

Found gift card has expired

400

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

Successful Response Example

Example
Schema


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

Response

Code
Example
Description

403

Invalid Bearer token

400

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

Successful redemption transaction created

404

Gift card not found

400

Found gift card is not active

400

Found gift card has expired

400

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

400

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

400

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

Successful Response Example

Example
Schema


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

Response

Code
Example
Description

403

Invalid Bearer token

400

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

Successful top up transaction created

404

Gift card not found

400

Found gift card is not active

400

Found gift card has expired

400

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

400

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

Successful Response Example

Example
Schema

Last updated 9 months ago

}
    “cardNumber”:“123456789”
}
GiftCardCheckRequest { 
  cardNumber: string; 
}
{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
{
"statusCode": 400,
"message": "Bad Request"
}
{
"cardNumber": "123456789",
"balance": 8.5
}
{
"message": "Gift card not found"
}
{
"message": "Gift card inactive"
}
{
"message": "Gift card expired"
}
{
"message": "Insufficient permissions
for gift card type"
}
{ 
  "cardNumber": "123456789", 
  "balance": 8.5
}
GiftCardCheckResponse {
   cardNumber: string;
   balance: number;
}
}
   “cardNumber” : “123456789”,
   “amount” : 5.00
}
GiftCardRedemptionRequest {
    cardNumber: string;
    amount: number;
}
{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
{
"statusCode": 400,
"message": "Bad Request"
}
{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}
{
"message": "Gift card not found"
}
{
"message": "Gift card inactive"
}
{
"message": "Gift card expired"
}
{
"message": "Insufficient permissions
for gift card type"
}
{
    "message": "Insufficient balance"
}
{
"message": "Gift card redemption
failed"
}
{
"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;
}
}
   “cardNumber” : “123456789”,
   “amount” : 5.00
}
GiftCardTopupRequest {
    cardNumber: string;
    amount: number;
}
{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
{
"statusCode": 400,
"message": "Bad Request"
}
{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}
{
"message": "Gift card not found"
}
{
"message": "Gift card inactive"
}
{
"message": "Gift card expired"
}
{
"message": "Insufficient permissions
for gift card type"
}
{
    "message": "Gift card top up failed"
}
{
"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;
}