# 1. 功能介绍

Gate Pay提供的礼品卡 API 解决方案旨在促进礼品卡的即时创建和价值检查。

# 2. API 接口

# 2.1 创建礼品卡

数据类型：JSON （content-type：application/json）
请求⽅式：POST
路径Path: /v1/pay/gift/create
验证方式：签名验证
请求体内容:

字段名类型是否必须说明

title string 是礼品卡的标题

templateId string 是礼品卡封面的ID

currency string 是礼品卡的币种

amount string 是礼品卡的金额

字段名	类型	是否必须	说明
title	string	是	礼品卡的标题
templateId	string	是	礼品卡封面的ID
currency	string	是	礼品卡的币种
amount	string	是	礼品卡的金额

响应内容

字段名	类型	是否必须	说明
card_num	string	是	礼品卡卡号
card_key	string	是	礼品卡兑换码
amount	string	是	礼品卡金额
currency	string	是	礼品卡币种
status	string	是	礼品卡状态 0 未知状态 1 礼品卡待支付 2 未兑换 3 已兑换 4 冻结 5 支付失败 6 人工审核 7 审核驳回 8 审核支付失败
card_temp_id	string	是	礼品卡封面ID
creator_name	string	是	礼品卡创建人名字
create_time	string	是	创建时间

CURL 请求

curl --location 'https://openplatform.gateapi.io/v1/pay/gift/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1738934053475' \
--header 'x-GatePay-Nonce: 5417061546' \
--header 'x-GatePay-Signature: b8c4705ff4c1357f2a27925dd180c1e1f4a244148f312a2dee5afbcc6f4b150e9ffceee455c5a298f895d43a64ee829eebdfd262539d45c41f7aee4336fd8c8c' \
--header 'X-GatePay-Certificate-SN: 4186d0c6-6a35-55a9-8dc6-5312769dbff8' \
--data '{
    "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
    }
}

# 2.2 获取礼品卡封面列表

数据类型：JSON （content-type：application/json）
请求⽅式：GET
路径Path: /v1/pay/gift/temp/list
验证方式：签名验证
响应内容

字段名	类型	是否必须	说明
card_temp_id	string	是	封面ID
image_url	string	是	图封面图片URL
cover_type	string	是	封面类型

CURL 请求

curl --location 'https://openplatform.gateapi.io/v1/pay/gift/temp/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1738934053475' \
--header 'x-GatePay-Nonce: 5417061546' \
--header 'x-GatePay-Signature: b8c4705ff4c1357f2a27925dd180c1e1f4a244148f312a2dee5afbcc6f4b150e9ffceee455c5a298f895d43a64ee829eebdfd262539d45c41f7aee4336fd8c8c'

响应


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

# 2.3 查询可用币种余额

数据类型：JSON （content-type：application/json）
请求⽅式：GET
路径Path: /v1/pay/balance
验证方式：签名验证
CURL 请求

curl --location 'https://openplatform.gateapi.io/v1/pay/balance' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1737951293198' \
--header 'x-GatePay-Nonce: 5609469415' \
--header 'x-GatePay-Signature: bda8607f683f39f987f52d644738b551b7d29be5663d7c997cb7d2240e49eb1aba7b031f7bae712f6643992585705afe1ce7b4a16440b98ac13aa004a6be6499'

响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "ADA": "313.99963295",
        "ALGO": "0",
        "APT": "0",
        "ARB": "0",
        "ATOM": "0",
        "AVAX": "0",
        "BCH": "0",
    }
}

# 2.4 查询礼品卡

数据类型：JSON （content-type：application/json）
请求⽅式：POST
路径Path: /v1/pay/gift/query
验证方式：签名验证
请求参数

字段名类型是否必须说明

card_number string 否（二选一）礼品卡卡号

key string 否（二选一）兑换码(当两个参数都传时优先使用key)

字段名	类型	是否必须	说明
card_number	string	否（二选一）	礼品卡卡号
key	string	否（二选一）	兑换码(当两个参数都传时优先使用key)

响应参数

字段名	类型	是否必须	说明
card_num	string	是	礼品卡卡号
amount	string	是	礼品卡金额
currency	string	是	礼品卡币种
status	string	是	礼品卡状态 0 未知状态 1 礼品卡待支付 2 未兑换 3 已兑换 4 冻结 5 支付失败 6 人工审核 7 审核驳回 8 审核支付失败
card_temp_id	string	是	礼品卡封面ID
creator_name	string	是	礼品卡创建人名字
create_time	string	是	创建时间
exchange_uid	int	是	兑换人
key	string	是	兑换码
title	string	是	主题
exchange_time	int	是	兑换时间标准时间戳单位为毫秒

CURL 请求

curl --location 'https://openplatform.gateapi.io/v1/pay/gift/query' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1738934053475' \
--header 'x-GatePay-Nonce: 5417061546' \
--data '{
    "card_number":"5202710871862281",
    "key":""
}'

响应

{
    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "card_num": "6712561472330044",
        "key": "r81T4rg3FKjt2+BYUgIn0CFqwtxp9CUSHGBFYDDJ608=",
        "title": "",
        "creator_name": "GateUser-8118f6f8",
        "amount": "0.99",
        "status": 2,
        "currency": "USDT",
        "create_time": 1737971259259,
        "exchange_uid": 0,
        "exchange_time": 1737971259259
    }
    }
}

# 3. Error Code

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

Last Updated: 5/23/2025, 12:54:07 PM