礼品卡 - Gate Pay DOCS

概述

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

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

有关请求头、签名规则及回调验签，请参见认证与安全。

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 毫秒时间戳）

请求示例

{
  "title": "api create gift card1",
  "templateId": "255267012439183360",
  "currency": "USDT",
  "amount": "0.99"
}

响应示例

{
  "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`）

响应示例

{
  "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"`）

响应示例

{
  "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`	整数	兑换时间（毫秒）

请求示例

{
  "card_number": "5202710871862281"
}

响应示例

{
  "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 仅用于商户账户多币种余额，不能用来查单张礼品卡余额。有关其他产品的回调处理方式，请参见通知与回调。

错误处理

以下为平台常见错误码及处理建议。查询礼品卡时若卡号或兑换码错误，可能返回 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 或礼品卡号

更多错误码与最佳实践见错误码与最佳实践。

接入指南

最小可运行链路

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

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

基础流程

使用 GET /v1/pay/gift/temp/list 获取可用模板
使用 POST /v1/pay/gift/create 并传入选定模板 创建礼品卡
保存卡片信息（创建响应中的 card_num、card_key）并妥善保护
向客户 发放礼品卡
使用 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 反映的是商户账户按币种的可用资金，不是单张礼品卡的剩余面值

​概述

​API 参考

​创建礼品卡

​请求参数

​响应字段

​请求示例

​响应示例

​查询礼品卡封面模板

​响应字段

​响应示例

​查询商户账户余额

​响应字段

​响应示例

​查询礼品卡详情

​请求体

​响应字段（data）

​请求示例

​响应示例

​礼品卡状态码

​回调行为

​错误处理

​接入指南

​最小可运行链路

​基础流程

​最佳实践

​相关文档

概述

API 参考

创建礼品卡

请求参数

响应字段

请求示例

响应示例

查询礼品卡封面模板

响应字段

响应示例

查询商户账户余额

响应字段

响应示例

查询礼品卡详情

请求体

响应字段（`data`）

请求示例

响应示例

礼品卡状态码

回调行为

错误处理

接入指南

最小可运行链路

基础流程

最佳实践

相关文档