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

# 礼品卡

> 礼品卡功能支持商户创建、管理和跟踪数字礼品卡，并支持自定义封面与模板。本文档覆盖礼品卡的完整生命周期。

## 概述

礼品卡是一种数字化支付工具，支持商户：

* 创建带有品牌元素和自定义封面的礼品卡
* 按指定金额和币种发卡
* 通过查询接口跟踪卡片状态及兑换情况
* 在需要时查询商户账户各币种可用余额（与单张礼品卡无关）

有关请求头、签名规则及回调验签，请参见 [认证与安全](/global/essentials/version/100/cn/common/authentication)。

## API 参考

### 创建礼品卡

**接口:** `POST /v1/pay/gift/create`

使用指定参数创建新的礼品卡。成功时响应为统一的 `status` / `code` / `data` 结构；`card_num`、`card_key`、数值型 `status` 等卡片字段在 `data` 中返回。

#### 请求参数

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `title` | 字符串 | 是 | 礼品卡标题或名称 |
| `templateId` | 字符串 | 是 | 封面模板 ID |
| `currency` | 字符串 | 是 | 礼品卡币种（例如 `USDT`；以 Gate Pay 支持的币种为准） |
| `amount` | 字符串 | 是 | 礼品卡初始金额 |

#### 响应字段

成功响应包含通用外层字段：`status`、`code`、`errorMessage`、`data`。礼品卡明细在 `data` 中：

| 字段 | 类型 | 说明 |
| - | - | - |
| `card_num` | 字符串 | 礼品卡号 |
| `card_key` | 字符串 | 兑换码 |
| `amount` | 字符串 | 礼品卡金额 |
| `currency` | 字符串 | 礼品卡币种 |
| `status` | 整数 | 礼品卡状态（见 [礼品卡状态码](#礼品卡状态码)） |
| `card_temp_id` | 字符串 | 封面（模板）ID |
| `creator` | 整数 | 创建人用户 ID |
| `creator_name` | 字符串 | 创建人展示名 |
| `exchange_uid` | 整数 | 兑换人用户 ID（无则为 0） |
| `owner` | 整数 | 归属用户 ID |
| `give_count` | 整数 | 赠送次数 |
| `last_give_time` | 整数 | 最近赠送时间（时间戳；从未赠送则为 0） |
| `create_time` | 整数 | 创建时间（Unix 毫秒时间戳） |

#### 请求示例

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

#### 响应示例

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

### 查询礼品卡封面模板

**接口:** `GET /v1/pay/gift/temp/list`

获取可用于礼品卡自定义的封面模板列表。

#### 响应字段

成功响应包含通用外层字段；模板列表在 `data` 数组中，每项包含：

| 字段 | 类型 | 说明 |
| - | - | - |
| `card_temp_id` | 字符串 | 封面 ID，创建礼品卡时作为 `templateId` 传入 |
| `image_url` | 字符串 | 封面图片 URL |
| `title_en` | 字符串 | 英文标题 |
| `title_cn` | 字符串 | 中文标题 |
| `cover_type` | 字符串 | 封面类型（例如 `theme`、`festival`、`all`） |

#### 响应示例

```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"
    }
  ]
}
```

### 查询商户账户余额

**接口:** `GET /v1/pay/balance`

查询**当前商户账户**下各可用币种的余额（账户维度），**不是**单张礼品卡的余额。无 Query 参数；鉴权请求头与其他 Pay 接口一致。

#### 响应字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `data` | 对象 | 币种代码到余额字符串的映射（例如 `"USDT": "1000.50"`） |

#### 响应示例

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

### 查询礼品卡详情

**接口:** `POST /v1/pay/gift/query`

按**礼品卡号**或**兑换码**查询礼品卡详情。使用 **JSON 请求体**（不要用 Query 参数）。可传 `card_number` 和/或 `key`；**若两者同时传入，以 `key` 为准**。

#### 请求体

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `card_number` | 字符串 | 二选一 | 礼品卡号 |
| `key` | 字符串 | 二选一 | 兑换码 |

#### 响应字段（`data`）

| 字段 | 类型 | 说明 |
| - | - | - |
| `card_num` | 字符串 | 礼品卡号 |
| `key` | 字符串 | 兑换码 |
| `title` | 字符串 | 标题 |
| `creator_name` | 字符串 | 创建人展示名 |
| `amount` | 字符串 | 礼品卡金额 |
| `status` | 整数 | 状态码（见下文） |
| `currency` | 字符串 | 币种 |
| `card_temp_id` | 字符串 | 封面 ID |
| `create_time` | 整数 | 创建时间（毫秒） |
| `exchange_uid` | 整数 | 兑换人 ID |
| `exchange_time` | 整数 | 兑换时间（毫秒） |

#### 请求示例

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

#### 响应示例

```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"
  }
}
```

## 礼品卡状态码

礼品卡记录上的 `status` 为**整数**，与平台枚举一致（例如 `GiftCardStatusEnum`）：

| 状态码 | 说明 |
| - | - |
| `0` | 未知 |
| `1` | 待支付 |
| `2` | 未兑换 |
| `3` | 已兑现 |
| `4` | 冻结 |
| `5` | 支付失败 |
| `6` | 人工审核 |
| `7` | 审核驳回 |
| `8` | 审核支付失败 |
| `9` | 软删除 |
| `10` | 赠送处理中 |
| `11` | 已作废 |

## 回调行为

礼品卡不提供异步回调。卡片状态与详情请使用 `POST /v1/pay/gift/query` 获取。`GET /v1/pay/balance` 仅用于商户账户多币种余额，**不能**用来查单张礼品卡余额。

有关其他产品的回调处理方式，请参见 [通知与回调](/global/essentials/version/100/cn/common/notification)。

## 错误处理

以下为平台常见错误码及处理建议。查询礼品卡时若卡号或兑换码错误，可能返回 `5003000`。

| 错误码 | 描述 | 解决方案 |
| - | - | - |
| `400007` | 不支持的 media type | 查看接口支持的 media type |
| `400004` | 请求参数中找不到 api\_key | 在请求 Header 中，使用 `X-GatePay-Certificate-ClientId` 携带注册时提供的 api\_key |
| `400003` | 请求时间戳不合法 | 检查 `X-GatePay-Timestamp` 是否早于当前时间或晚于请求时间 10 秒 |
| `400020` | 请求未携带签名用的随机字符串 Nonce | 在请求 Header 中，使用 `X-GatePay-Nonce` 携带生成签名时的随机字符串 |
| `400002` | 签名不合法 | 检查签名算法 |
| `400000` | 请求参数格式错误 | 检查请求数据格式 |
| `400001` | 请求参数错误 | 检查请求参数 |
| `400621` | 订单金额不正确 | 检查订单金额参数 |
| `400201` | 对应商户 `merchantTradeNo` 的支付单已存在 | 检查是否重复创建 |
| `400620` | 创建退款单重复 | 检查是否重复请求 |
| `400604` | 要退款的地址支付单尚未进入终态（过期或完成） | 等待订单结束后再发起退款 |
| `400608` | 退款金额异常：小于等于 0 或超过支付单金额 | 检查退款金额 |
| `400607` | 单笔支付单退款次数超过限制 | 当前一笔支付单仅支持一次退款 |
| `500008` | 找不到商户 | 确认 `X-GatePay-Certificate-ClientId` 携带的是商户注册时下发的 api\_key |
| `500200` | 当前 Gate 地址支付没有可用地址 | 创建订单时无可用地址 |
| `5003000` | 未查询到当前礼品卡 | 检查礼品卡 Key 或礼品卡号 |

更多错误码与最佳实践见 [错误码与最佳实践](/global/essentials/version/100/cn/common/error)。

## 接入指南

### 最小可运行链路

```text theme={null}
拉取模板列表 -> 创建礼品卡 -> 安全保存 card_num 与 card_key -> 发放给用户 -> 查询卡片详情（POST /v1/pay/gift/query）；如需商户账户资金再看 GET /v1/pay/balance
```

对于首次接入，建议先跑通单张礼品卡的创建、发放和查询，再扩展到批量发卡、活动营销或会员权益场景。

### 基础流程

1. 使用 `GET /v1/pay/gift/temp/list` **获取可用模板**
2. 使用 `POST /v1/pay/gift/create` 并传入选定模板 **创建礼品卡**
3. **保存卡片信息**（创建响应中的 `card_num`、`card_key`）并妥善保护
4. 向客户 **发放礼品卡**
5. 使用 `POST /v1/pay/gift/query` **查询详情**（请求体：`card_number` 和/或 `key`）。`GET /v1/pay/balance` **仅用于**商户账户各币种余额

### 最佳实践

* 同时保存 `card_num` 与 `card_key`；查询接口在 JSON 体中接收 `card_number` 或 `key`，两者都传时以 `key` 为准
* 分支逻辑请使用 [礼品卡状态码](#礼品卡状态码) 中的整型状态
* 创建礼品卡时，将模板列表返回的 `card_temp_id` 作为 `templateId` 传入
* `GET /v1/pay/balance` 反映的是商户账户按币种的可用资金，不是单张礼品卡的剩余面值

## 相关文档

* [认证与安全](/global/essentials/version/100/cn/common/authentication)
* [通知与回调](/global/essentials/version/100/cn/common/notification)
* [错误码与最佳实践](/global/essentials/version/100/cn/common/error)
* [账户查询与对账](/global/essentials/version/100/cn/common/balance)
* [支付概述](/global/essentials/version/100/cn/inflow/payment/payment)


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