跳转到主要内容

​
概述

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

​
API 参考

​
创建礼品卡

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

​
请求参数

字段类型必填说明
titlestringYesGift card title or name
templateIdstringYesCover template ID for the gift card design
currencystringYesGift card currency (e.g., USD, EUR)
amountstringYesGift card initial amount

​
响应 字段

字段类型说明
cardNumberstringUnique gift card number for customer identification
keystringGift card key for activation and redemption
statusstringInitial gift card status (see status enumeration below)

​
Example 请求

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

​
Example 响应

{
  "cardNumber": "GC1234567890123456",
  "key": "KEY_abc123def456",
  "status": "CREATED"
}

​
Query 礼品卡 Cover Templates

接口: GET /v1/pay/giftcard/template/list Retrieves available cover templates for gift card customization.

​
响应 字段

字段类型说明
templateIdstringUnique template identifier
templateNamestringDisplay name of the template
coverUrlstringURL to the template cover image
statusstringTemplate availability status

​
Query Balance

接口: GET /v1/pay/balance/query Retrieves the current balance of a gift card.

​
Query 参数

Query by either cardNumber or key (mutually exclusive—provide only one).
参数类型必填说明
cardNumberstringConditionalGift card number
keystringConditionalGift card key

​
Query 礼品卡 Details

接口: GET /v1/pay/giftcard/query Retrieves complete gift card information including status and 交易 history.

​
Query 参数

参数类型必填说明
cardNumberstringConditionalGift card number for lookup
keystringConditionalGift card key for lookup

​
礼品卡 状态 Enumeration

状态说明
CREATEDGift card has been created and is ready for distribution
REDEEMEDGift card balance has been fully redeemed
EXPIREDGift card has reached its expiration date
CANCELLEDGift card has been cancelled and is no longer valid

​
回调 Behavior

Gift cards do not provide 异步 回调s. 状态 changes and balance updates must be retrieved through the query APIs (GET /v1/pay/giftcard/query or GET /v1/pay/balance/query). For information on 回调 handling for other products, see 通知 & 回调.

​
Error 处理方式

错误码说明适用 APIResolution
400001Invalid request parametersAll gift card APIsVerify all required fields are present and correctly formatted
400007Unsupported Content-类型All gift card APIsEnsure Content-Type: application/json is set in 请求头
For additional error codes and best practices, refer to 错误码s & 最佳实践.

​
Integration Guide

​
Basic Flow

  1. Retrieve available templates using GET /v1/pay/giftcard/template/list
  2. Create a gift card using POST /v1/pay/giftcard/create with your chosen template
  3. Store the card details (cardNumber and key) securely
  4. Distribute the gift card to your customer
  5. Query status periodically using GET /v1/pay/giftcard/query or GET /v1/pay/balance/query

​
最佳实践

  • Store both cardNumber and key in your system for redundant lookups
  • Query status before displaying balance to customers
  • Implement expiration date handling in your 应用
  • Use template IDs that align with your brand guidelines