> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gift Card

> Gift card functionality allows merchants to create, manage, and track digital gift cards with customizable designs and templates. This guide covers the complete gift card lifecycle.

## Overview

Gift cards are digital payment instruments that enable merchants to:

* Create branded gift cards with custom cover designs
* Issue cards with specified amounts and currencies
* Track card status and redemption via the query API
* Query merchant account currency balances (separate from any single card) when needed

For request headers, signature rules, and callback verification, refer to [Authentication & Security](/global/essentials/version/100/en/common/authentication).

## API Reference

### Create Gift Card

**Endpoint:** `POST /v1/pay/gift/create`

Creates a new gift card with specified parameters. On success, the response includes the standard `status` / `code` / `data` wrapper; card fields such as `card_num`, `card_key`, and numeric `status` are inside `data`.

#### Request Parameters

| Field | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | Gift card title or name |
| `templateId` | string | Yes | Cover template ID for the gift card design |
| `currency` | string | Yes | Gift card currency (e.g. `USDT`; use values supported by Gate Pay) |
| `amount` | string | Yes | Gift card initial amount |

#### Response Fields

Successful responses use the common wrapper: `status`, `code`, `errorMessage`, and `data`. The gift card payload is in `data`:

| Field | Type | Description |
| - | - | - |
| `card_num` | string | Unique gift card number |
| `card_key` | string | Redemption code |
| `amount` | string | Gift card amount |
| `currency` | string | Gift card currency |
| `status` | integer | Gift card status (see [Gift card status codes](#gift-card-status-codes)) |
| `card_temp_id` | string | Template (cover) ID |
| `creator` | integer | Creator user ID |
| `creator_name` | string | Creator display name |
| `exchange_uid` | integer | Redeemer user ID (0 if none) |
| `owner` | integer | Owner user ID |
| `give_count` | integer | Number of times the card was gifted |
| `last_give_time` | integer | Last gift time (timestamp; 0 if never) |
| `create_time` | integer | Create time (Unix timestamp in milliseconds) |

#### Example Request

```json theme={null}
{
  "title": "api create gift card1",
  "templateId": "255267012439183360",
  "currency": "USDT",
  "amount": "0.99"
}
```

#### Example Response

```json theme={null}
{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "card_num": "2002356433468640",
    "card_key": "yJgkiqAVCwS0tC8W5D+t9iFqwtxp9CUSHGBFYDDJ608=",
    "amount": "0.99",
    "currency": "USDT",
    "status": 1,
    "card_temp_id": "255267012439183360",
    "creator": 10002,
    "creator_name": "GateUser-8118f6f8",
    "exchange_uid": 0,
    "owner": 10002,
    "give_count": 0,
    "last_give_time": 0,
    "create_time": 1737942105582
  }
}
```

### Query Gift Card Cover Templates

**Endpoint:** `GET /v1/pay/gift/temp/list`

Retrieves available cover templates for gift card customization.

#### Response Fields

Successful responses use the common wrapper; templates are returned in `data` as an array. Each item has:

| Field | Type | Description |
| - | - | - |
| `card_temp_id` | string | Cover (template) ID — use this value as `templateId` when creating a card |
| `image_url` | string | Cover image URL |
| `title_en` | string | English title |
| `title_cn` | string | Chinese title |
| `cover_type` | string | Cover type (e.g. `theme`,`festival`,`all`) |

#### Example Response

```json theme={null}
{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": [
    {
      "card_temp_id": "293389550603997184",
      "image_url": "https://test-gateio-nft.s3.ap-northeast-1.amazonaws.com/image/688c908c72b1cb9b78039de44003b4f8de4009f5.jpg",
      "title_en": "anlitest",
      "title_cn": "anlitest常用",
      "cover_type": "theme"
    }
  ]
}
```

### Query merchant account balances

**Endpoint:** `GET /v1/pay/balance`

Returns balances for **all currencies available on the current merchant account** (account-level balances), not a single gift card. There are no query parameters; authentication headers apply as for other Pay APIs.

#### Response Fields

| Field | Type | Description |
| - | - | - |
| `data` | object | Map of currency code to balance string (e.g. `"USDT": "1000.50"`) |

#### Example Response

```json theme={null}
{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "ADA": "313.99963295",
    "ALGO": "0",
    "USDT": "1000.50"
  }
}
```

### Query Gift Card Details

**Endpoint:** `POST /v1/pay/gift/query`

Retrieves gift card details by **card number** or **redemption code**. Send a JSON body (not query string). Provide `card_number` and/or `key`; if both are sent, **`key` takes priority**.

#### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `card_number` | string | One of two | Gift card number |
| `key` | string | One of two | Redemption code |

#### Response Fields (`data`)

| Field | Type | Description |
| - | - | - |
| `card_num` | string | Gift card number |
| `key` | string | Redemption code |
| `title` | string | Title |
| `creator_name` | string | Creator display name |
| `amount` | string | Gift card amount |
| `status` | integer | Status code (see below) |
| `currency` | string | Currency |
| `card_temp_id` | string | Cover ID |
| `create_time` | integer | Create time (milliseconds) |
| `exchange_uid` | integer | Redeemer ID |
| `exchange_time` | integer | Exchange time (milliseconds) |

#### Example Request

```json theme={null}
{
  "card_number": "5202710871862281"
}
```

#### Example Response

```json theme={null}
{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
      "card_num": "5607423016280059",
      "key": "94Q1UV7RMUEMNINL",
      "title": "anliAPI",
      "creator_name": "xuyi006",
      "amount": "0.0001",
      "status": 3,
      "currency": "USDT",
      "create_time": 1744717081334,
      "exchange_uid": 39992131,
      "exchange_time": 1776838077478,
      "card_temp_id": "346749173549240320"
  }
}
```

## Gift card status codes

The `status` field on gift card records is an **integer**. Values match the platform enumeration (e.g. `GiftCardStatusEnum`):

| Code | Meaning |
| - | - |
| `0` | Unknown |
| `1` | Pending payment |
| `2` | Not redeemed |
| `3` | Redeemed (cashed out) |
| `4` | Frozen |
| `5` | Payment failed |
| `6` | Manual review |
| `7` | Review rejected |
| `8` | Review payment failed |
| `9` | Soft-deleted |
| `10` | Gifting in progress |
| `11` | Voided |

## Callback Behavior

Gift cards do not provide asynchronous callbacks. Card status and details should be retrieved with `POST /v1/pay/gift/query`. Use `GET /v1/pay/balance` when you need the merchant account’s multi-currency balances, not a per-card balance.

For information on callback handling for other products, see [Notification & Callbacks](/global/essentials/version/100/en/common/notification).

## Error Handling

Common platform error codes and how to resolve them are listed below. When querying a gift card, an incorrect key or card number may return `5003000`.

| Error Code | Description | Resolution |
| - | - | - |
| `400007` | Unsupported media type | Check which media types the API accepts |
| `400004` | `api_key` not found in the request | In the request header, pass the `api_key` from registration using `X-GatePay-Certificate-ClientId` |
| `400020` | Missing Nonce random string for signing | In the request header, pass the random string used to build the signature using `X-GatePay-Nonce` |
| `400002` | Invalid signature | Verify the signing algorithm |
| `400000` | Request parameter format error | Check the request payload format |
| `400001` | Request parameter error | Check the request parameters |
| `400621` | Order amount is incorrect | Check the order amount fields |
| `400003` | Timestamp is incorrect | Check whether X-GatePay-Timestamp is earlier than the current time or more than 10 seconds ahead of the request time |
| `400201` | A payment order for this merchant’s `merchantTradeNo` already exists | Check for duplicate creation |
| `400620` | Duplicate refund order | Check for duplicate requests |
| `400604` | The address payment order to refund is not in a terminal state (expired or completed) | Wait until the order reaches a final state before refunding |
| `400608` | Refund amount invalid: ≤ 0 or exceeds the payment order amount | Check the refund amount |
| `400607` | Refund attempts for one payment order exceed the limit | Only one refund is allowed per payment order |
| `500008` | Merchant not found | Confirm `X-GatePay-Certificate-ClientId` carries the `api_key` issued at merchant registration |
| `500200` | No Gate address-payment address is available | No payout address available when creating the order |
| `5003000` | Gift card not found | Check the gift card key or card number |

For more error codes and best practices, see [Error Codes & Best Practices](/global/essentials/version/100/en/common/error).

## Integration Guide

### Minimum runnable path

```text theme={null}
List templates -> Create gift card -> Store card_num and card_key securely -> Distribute to the user -> Query card details (POST /v1/pay/gift/query); use GET /v1/pay/balance for merchant account balances if needed
```

For a first integration, validate the lifecycle of a single gift card first, then expand to batch issuance, campaign fulfillment, or membership-related use cases.

### Basic Flow

1. **Retrieve available templates** using `GET /v1/pay/gift/temp/list`
2. **Create a gift card** using `POST /v1/pay/gift/create` with your chosen template
3. **Store the card details** (`card_num` and `card_key` from the create response) securely
4. **Distribute the gift card** to your customer
5. **Query card details** with `POST /v1/pay/gift/query` (body: `card_number` and/or `key`). Use `GET /v1/pay/balance` only for merchant account currency balances

### Best Practices

* Store both `card_num` and `card_key` for lookups; the query API accepts `card_number` or `key` in the JSON body (if both are sent, `key` wins)
* Use integer `status` codes from [Gift card status codes](#gift-card-status-codes) when branching in your app
* Use `card_temp_id` from the template list as `templateId` when creating a card
* `GET /v1/pay/balance` reflects merchant account funds by currency, not an individual gift card’s remaining value

## Related Documentation

* [Authentication & Security](/global/essentials/version/100/en/common/authentication)
* [Notification & Callbacks](/global/essentials/version/100/en/common/notification)
* [Error Codes & Best Practices](/global/essentials/version/100/en/common/error)
* [Account Queries and Reconciliation](/global/essentials/version/100/en/common/balance)
* [Payments Overview](/global/essentials/version/100/en/inflow/payment/payment)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.