跳转到主要内容

​
概述

礼品卡是一种数字化支付工具，支持商户：
  • 创建带有品牌元素和自定义封面的礼品卡
  • 按指定金额和币种发卡
  • 跟踪卡片状态及兑换情况
  • 查询剩余余额
有关请求头、签名规则及回调验签，请参见 认证与安全。

​
API 参考

​
创建礼品卡

接口: POST /v1/pay/gift/create 使用指定参数创建新的礼品卡。成功后会返回礼品卡号、密钥和初始状态。

​
请求参数

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

​
响应字段

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

​
请求示例

{
  "title": "Holiday Gift Card",
  "templateId": "template_001",
  "currency": "USD",
  "amount": "100"
}

​
响应示例

{
  "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)。 有关其他产品的回调处理方式，请参见 通知与回调。

​
错误处理

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

​
接入指南

​
最小可运行链路

获取模板列表 -> 创建礼品卡 -> 安全保存 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

​
相关文档