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

# 礼品卡

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

## 概述

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

* 创建带有品牌元素和自定义封面的礼品卡
* 按指定金额和币种发卡
* 跟踪卡片状态及兑换情况
* 查询剩余余额

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

## API 参考

### 创建礼品卡

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

使用指定参数创建新的礼品卡。成功后会返回礼品卡号、密钥和初始状态。

#### 请求参数

| 字段           | 类型  | 必填 | 说明                  |
| ------------ | --- | -- | ------------------- |
| `title`      | 字符串 | 是  | 礼品卡标题或名称            |
| `templateId` | 字符串 | 是  | 礼品卡设计所用封面模板 ID      |
| `currency`   | 字符串 | 是  | 礼品卡币种 （例如 USD, EUR) |
| `amount`     | 字符串 | 是  | 礼品卡初始金额             |

#### 响应字段

| 字段           | 类型  | 说明                |
| ------------ | --- | ----------------- |
| `cardNumber` | 字符串 | 用于识别客户的唯一礼品卡号     |
| `key`        | 字符串 | 用于激活和兑换的礼品卡密钥     |
| `status`     | 字符串 | 礼品卡初始状态 (见下方状态枚举) |

#### 请求示例

```json theme={null}
{
  "title": "Holiday Gift Card",
  "templateId": "template_001",
  "currency": "USD",
  "amount": "100"
}
```

#### 响应示例

```json theme={null}
{
  "cardNumber": "GC1234567890123456",
  "key": "KEY_abc123def456",
  "status": "CREATED"
}
```

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

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

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

#### 响应字段

| 字段             | 类型  | 说明         |
| -------------- | --- | ---------- |
| `templateId`   | 字符串 | 唯一模板标识     |
| `templateName` | 字符串 | 模板显示名称     |
| `coverUrl`     | 字符串 | 模板封面图片 URL |
| `status`       | 字符串 | 模板可用状态     |

### 查询余额

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

获取礼品卡当前余额.

#### 查询参数

可通过 `cardNumber` 或 `key` 查询 (二者互斥：仅传其中一个).

| 参数           | 类型  | 必填  | 说明    |
| ------------ | --- | --- | ----- |
| `cardNumber` | 字符串 | 有条件 | 礼品卡号  |
| `key`        | 字符串 | 有条件 | 礼品卡密钥 |

### 查询礼品卡详情

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

获取完整礼品卡信息，包括状态和交易历史.

#### 查询参数

| 参数           | 类型  | 必填  | 说明         |
| ------------ | --- | --- | ---------- |
| `cardNumber` | 字符串 | 有条件 | 用于查询的礼品卡号  |
| `key`        | 字符串 | 有条件 | 用于查询的礼品卡密钥 |

## 礼品卡 状态枚举

| 状态          | 说明          |
| ----------- | ----------- |
| `CREATED`   | 礼品卡已创建，可发放  |
| `REDEEMED`  | 礼品卡余额已全部兑换  |
| `EXPIRED`   | 礼品卡已到期      |
| `CANCELLED` | 礼品卡已取消，不再有效 |

## 回调行为

礼品卡不提供异步回调。状态变更和余额更新必须通过查询 API 获取 (`POST /v1/pay/gift/query` 或 `GET /v1/pay/balance`)。

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

## 错误处理

| 错误码      | 说明                | 适用 API    | 处理建议                                       |
| -------- | ----------------- | --------- | ------------------------------------------ |
| `400001` | 请求参数非法            | 所有礼品卡 API | 确认所有必填字段均已提供且格式正确                          |
| `400007` | 不支持的 Content-Type | 所有礼品卡 API | 确保请求头中设置了 `Content-Type: application/json` |

有关更多错误码和最佳实践，请参见 [错误码与最佳实践](/essentials/version/100/cn/common/error)。

## 接入指南

### 最小可运行链路

```text theme={null}
获取模板列表 -> 创建礼品卡 -> 安全保存 cardNumber 与 key -> 发放给用户 -> 查询卡片状态与余额
```

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

### 基础流程

1. 使用以下接口**获取可用模板**： `GET /v1/pay/gift/temp/list`
2. 使用 `POST /v1/pay/gift/create` 并传入选定模板来**创建礼品卡**
3. **保存卡片详情** （cardNumber 和 key）并妥善保护
4. 向客户**发放礼品卡**
5. 使用以下接口定期**查询状态**： `POST /v1/pay/gift/query` 或 `GET /v1/pay/balance`

### 最佳实践

* 在系统中同时保存 `cardNumber` 和 `key`，以便冗余查询
* 向客户展示余额前先查询状态
* 在应用中实现到期日期处理
* 使用符合品牌规范的模板 ID

## 相关文档

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