# 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

<mark style="color:green;">`POST`</mark> `/api/interface/gift-card/check`

### Method

<table><thead><tr><th width="237">Keyward</th><th>Value</th></tr></thead><tbody><tr><td>EndpointURI</td><td>Main API endpoint provided separately</td></tr><tr><td>URI</td><td><code>interface/gift-card/check</code></td></tr><tr><td>Call Type</td><td>POST</td></tr><tr><td>HTTP Address</td><td><code>&#x3C;endpoint>/api/interface/gift-card/check</code></td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="192">Keyward</th><th>Value</th></tr></thead><tbody><tr><td>Verb</td><td>POST</td></tr><tr><td>Authorisation</td><td>HTTP Bearer (access-token)</td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="164">Property Name</th><th>Type</th><th width="230">Description</th><th>Mandatory</th></tr></thead><tbody><tr><td>cardNumber</td><td>string</td><td>The gift card number</td><td>Yes</td></tr></tbody></table>

### **Request Body Example**

<table><thead><tr><th>Example</th><th>Schema</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">}
    “cardNumber”:“123456789”
}
</code></pre></td><td><pre class="language-scheme"><code class="lang-scheme">GiftCardCheckRequest { 
  cardNumber: string; 
}
</code></pre></td></tr></tbody></table>

### Responses

<table><thead><tr><th width="91">Code</th><th width="361">Example</th><th>Description</th></tr></thead><tbody><tr><td>403</td><td><pre class="language-json"><code class="lang-json">{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
</code></pre></td><td>Invalid Bearer token</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"statusCode": 400,
"message": "Bad Request"
}
</code></pre></td><td>cardNumber is missing; cardNumber is not a string; cardNumber is not a numeric string;</td></tr><tr><td>200</td><td><pre class="language-json"><code class="lang-json">{
"cardNumber": "123456789",
"balance": 8.5
}
</code></pre></td><td>Gift card found</td></tr><tr><td>404</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card not found"
}
</code></pre></td><td>Gift card not found</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card inactive"
}
</code></pre></td><td>Found gift card is not active</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card expired"
}
</code></pre></td><td>Found gift card has expired</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Insufficient permissions
for gift card type"
}
</code></pre></td><td>The access token provided has insufficient permissions to retrieve gift card. <br>Contact UpCo to resolve</td></tr></tbody></table>

### Successful Response Example

<table><thead><tr><th>Example</th><th>Schema</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{ 
  "cardNumber": "123456789", 
  "balance": 8.5
}
</code></pre><p></p></td><td><pre class="language-json"><code class="lang-json">GiftCardCheckResponse {
   cardNumber: string;
   balance: number;
}
</code></pre></td></tr></tbody></table>

***

## Redeem

{% hint style="info" %}
Redem can only be performed with amount equal or smaller than the card balance
{% endhint %}

<mark style="color:green;">`POST`</mark> `/api/interface/gift-card/redeem`

### Method

<table><thead><tr><th width="200">Keyward</th><th>Value</th></tr></thead><tbody><tr><td>EndpointURI</td><td>Main API endpoint provided separately</td></tr><tr><td>URI</td><td><code>interface/gift-card/redeem</code></td></tr><tr><td>Call Type</td><td>POST</td></tr><tr><td>HTTP Address</td><td><code>&#x3C;endpoint>/api/interface/gift-card/redeem</code></td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="192">Keyward</th><th>Value</th></tr></thead><tbody><tr><td>Verb</td><td>POST</td></tr><tr><td>Authorisation</td><td>HTTP Bearer (access-token)</td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="164">Property Name</th><th>Type</th><th width="230">Description</th><th>Mandatory</th></tr></thead><tbody><tr><td>cardNumber</td><td>string</td><td>The gift card number</td><td>Yes</td></tr><tr><td>amount</td><td>number</td><td>The amount to be redeemed</td><td>Yes</td></tr></tbody></table>

### **Request Body Example**

<table><thead><tr><th>Example</th><th>Schema</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">}
   “cardNumber” : “123456789”,
   “amount” : 5.00
}
</code></pre></td><td><pre class="language-scheme"><code class="lang-scheme">GiftCardRedemptionRequest {
    cardNumber: string;
    amount: number;
}
</code></pre></td></tr></tbody></table>

### **Response**

<table><thead><tr><th width="88">Code</th><th width="363">Example</th><th>Description</th></tr></thead><tbody><tr><td>403</td><td><pre class="language-json"><code class="lang-json">{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
</code></pre></td><td>Invalid Bearer token</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"statusCode": 400,
"message": "Bad Request"
}
</code></pre></td><td><p>cardNumber is missing; </p><p>cardNumber is not a string;</p><p>cardNumber is not a numeric string; </p><p>amount is missing;</p><p>amount is not a number;</p><p>amount is not a positive number;</p></td></tr><tr><td>201</td><td><pre class="language-json"><code class="lang-json">{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}
</code></pre></td><td>Successful redemption transaction created</td></tr><tr><td>404</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card not found"
}
</code></pre></td><td>Gift card not found</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card inactive"
}
</code></pre></td><td>Found gift card is not active</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card expired"
}
</code></pre></td><td>Found gift card has expired</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Insufficient permissions
for gift card type"
}
</code></pre></td><td>The access token provided has insufficient permissions to retrieve gift card. <br>Contact UpCo to resolve</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
    "message": "Insufficient balance"
}
</code></pre></td><td>The amount to be redeemed exceeds the balance of the found gift card</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card redemption
failed"
}
</code></pre></td><td>The gift card was found but the redemption transaction could not be completed.</td></tr></tbody></table>

### Successful Response Example

<table><thead><tr><th>Example</th><th>Schema</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}
</code></pre><p></p></td><td><pre class="language-json"><code class="lang-json">GiftCardRedemptionResponse {
cardNumber: string;
balance: number;
previousBalance: number;
amountRedeemed: number;
success: boolean;
reference: number;
}
</code></pre></td></tr></tbody></table>

***

## Top Up

<mark style="color:green;">`POST`</mark> `/api/interface/gift-card/top-up`

### Method

<table><thead><tr><th width="200">Keyward</th><th>Value</th></tr></thead><tbody><tr><td>EndpointURI</td><td>Main API endpoint provided separately</td></tr><tr><td>URI</td><td><code>interface/gift-card/top-up</code></td></tr><tr><td>Call Type</td><td>POST</td></tr><tr><td>HTTP Address</td><td><code>&#x3C;endpoint>/api/interface/gift-card/top-up</code></td></tr></tbody></table>

### Request Headers

<table><thead><tr><th width="192">Keyward</th><th>Value</th></tr></thead><tbody><tr><td>Verb</td><td>POST</td></tr><tr><td>Authorisation</td><td>HTTP Bearer (access-token)</td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="164">Property Name</th><th>Type</th><th width="230">Description</th><th>Mandatory</th></tr></thead><tbody><tr><td>cardNumber</td><td>string</td><td>The gift card number</td><td>Yes</td></tr><tr><td>amount</td><td>number</td><td>The amount to be redeemed</td><td>Yes</td></tr></tbody></table>

### **Request Body Example**

<table><thead><tr><th>Example</th><th>Schema</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">}
   “cardNumber” : “123456789”,
   “amount” : 5.00
}
</code></pre></td><td><pre class="language-scheme"><code class="lang-scheme">GiftCardTopupRequest {
    cardNumber: string;
    amount: number;
}
</code></pre></td></tr></tbody></table>

### **Response**

<table><thead><tr><th width="92">Code</th><th width="363">Example</th><th>Description</th></tr></thead><tbody><tr><td>403</td><td><pre class="language-json"><code class="lang-json">{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
</code></pre></td><td>Invalid Bearer token</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"statusCode": 400,
"message": "Bad Request"
}
</code></pre></td><td><p>cardNumber is missing; </p><p>cardNumber is not a string; </p><p>cardNumber is not a numeric string; </p><p>amount is missing; amount is not a number; </p><p>amount is not a positive number;</p></td></tr><tr><td>201</td><td><pre class="language-json"><code class="lang-json">{
"cardNumber": "123456789",
"balance": 7,
"previousBalance": 8.5,
"amountRedeemed": 1.5,
"success": true,
"reference": 458829
}
</code></pre></td><td>Successful top up transaction created</td></tr><tr><td>404</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card not found"
}
</code></pre></td><td>Gift card not found</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card inactive"
}
</code></pre></td><td>Found gift card is not active</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Gift card expired"
}
</code></pre></td><td>Found gift card has expired</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
"message": "Insufficient permissions
for gift card type"
}
</code></pre></td><td>The access token provided has insufficient permissions to retrieve gift card. <br>Contact UpCo to resolve</td></tr><tr><td>400</td><td><pre class="language-json"><code class="lang-json">{
    "message": "Gift card top up failed"
}
</code></pre></td><td>The gift card was found but the top up transaction could not be completed.</td></tr></tbody></table>

### Successful Response Example

<table><thead><tr><th>Example</th><th>Schema</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{
"cardNumber": "123456789",
"balance": 10,
"previousBalance": 8.5,
"topupAmount": 1.5,
"success": true,
"reference": 458829
}
</code></pre><p></p></td><td><pre class="language-json"><code class="lang-json">GiftCardTopUpResponse {
cardNumber: string;
balance: number;
previousBalance: number;
amountRedeemed: number;
success: boolean;
reference: number;
}
</code></pre></td></tr></tbody></table>