# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.supersweet.ai/crave.cards-apis/cards-wallet-api-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.