# changelog

    # v1.0.0

    2023-01-10
地址支付接入文档初版

    # 1. 功能介绍

    地址支付目标是支持用户在没有Gate账户前提下，可以用任意钱包资产与Gate商户进行交易

    Gate商家可以通过指定币种，查询支持的链与地址，将地址展示给用户

    用户通过三方钱包，向指定地址转账

    转账完成之后，等待链上打包确认，Gate根据链上确认进度，更新订单状态，异步向商家支付账户转账

    地址支付单状态变化与到账，给商户注册回调地址发送相应通知

    # 2. 地址支付

    # 2.1 流程图

    备注:

    1. 用户进入商户客户端下单界面，商户后端查询拟下单币种支持的链列表，返回链列表
    2. 用户选择要转账的目标链，点击去支付
    3. 在商户后台和Gate支付后台生成预支付订单，Gate后台生成预订单时，根据订单所选链，绑定一个可用链钱包地址
    4. 返回订单详情到商户后台，商户后台将订单对应链钱包地址展示给用户
    5. 用户通过三方钱包向订单地址发起转账
    6. Gate链服务后台监测到用户支付，综合订单支付信息和订单过期时间，更新订单状态
    7. 发送订单状态转换消息到商户后台（注：不论订单完成还是过期，此时并未向商户支付账户转账）
    8. Gate支付后台持续检测已结束订单在链上支付状态，待链上支付记录全部确认完毕后，向商户支付账户转入对应金额
    9. 向商户后台发送到账通知

    # 2.2 地址支付时序图

    # 2.2.1 非闪兑地址支付时序图

    # 2.2.2 闪兑地址支付时序图

    备注:

    • 闪兑支付相较于非闪兑支付，多一个查询支持兑换到订单币种的币种的步骤
    • 可选币种除可闪兑到订单币种的币种之外，包括订单币种本身，若选择订单币种，则支付币种与订单币种一致，判定为非闪兑支付单

    # 3. 支付到账

    # 3.1 异步支付

    # 3.1.1 定义

    在支付单结束时(支付成功或失败)，商户不会立即收到用户支付资金，存在一定延迟

    # 3.1.2 闪兑支付单

    以支付成功结束： 将用户支付币种兑换为订单对应币种和金额，充值到商户支付账户中

    以支付失败结束： 用户支付金额，保留在Gate账户，不进行闪兑和充值到商户支付账户

    # 3.2 延迟支付

    # 3.2.1 定义

    检测到链上交易记录广播的时刻在订单结束后或有效期之后的支付记录，称为延迟支付

    # 3.2.2 非闪兑支付单

    将用户支付资金充值到商户支付账户

    # 3.2.3 闪兑支付单

    将用户支付资金保留在Gate，不充值到商户支付账户

    # 3.3 即时支付

    # 3.2.1 定义

    链上一检测成功后就给商户入账，称为即时支付

    # 3.2.2 非闪兑支付单

    在订单有效期内，每支付一笔资金待链上确认成功就给商户入账资金

    # 4. 消息通知

    # 4.1 向商户发送消息的情形

    • 订单由创建状态转为支付完成状态
    • 订单由创建状态转为过期状态
    • 用户在有效期内支付足够金额，但截止订单过期时间，链上未确认完毕，进入PROCESS状态
    • 订单结束（过期或完成）前，每次检测到成功的支付记录后，Gate支付后台都会向用户支付账户转入对应的金额。有效期内累计某一笔付款总金额达到订单金额后会将订单状态改为完成
    • 订单结束后，订单地址检测到新的到账，确认完毕后转入商户支付账户
    • 订单结束后，闪兑订单地址检测到新的到账

    # 4.2 地址支付消息枚举值

    BizType

    值 解释
    PAY_ADDRESS 订单状态变更通知
    TRANSFER_ADDRESS 订单资金流转通知
    RECEIVED_CONVERT_DELAY_ADDRESS 闪兑地址支付单检测到新的延迟到账记录，通知商户但不充值到商户支付账户

    # 4.3 消息结构

    # 4.3.1 订单状态变更通知

    非闪兑地址支付单状态变更通知:

    字段名 类型 说明
    bizType string 描述通知类别， 见表BizType
    bizId string 订单id
    bizStatus string 参考BizStatus
    client_id string 创建订单的商户client_id
    data content 消息内容

    BizStatus

    值 解释
    PAY_SUCCESS 订单支付成功
    PAY_ERROR 订单支付遇到错误
    PAY_CLOSE 订单过期，订单关闭
    PAY_EXPIRED_IN_PROCESS 地址支付的一种特殊状态，用户在订单过期时间内支付金额>=订单金额，但链上有尚未确认完毕支付单需要继续等待确认支付结果，则订单进入一个名为PROCESS的中间状态
    PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION 地址支付闪兑支付汇率波动导致支付失败

    content

    字段名 类型 说明
    merchantTradeNo string 商户交易号
    productType string 创建订单时候的goodsType
    productName string 创建订单时候的GoodsName
    tradeType string 创建订单时候的terminalType
    goodsName string 创建订单时候的GoodsName
    terminalType string 创建订单时候的terminalType
    currency string 订单币种
    orderAmount string 订单金额
    payerId int64 支付用户的UID
    createTime int64 订单创建时间
    transactionId string 交易流水号
    waitAmountOnChain string 链上有效期内确认中金额
    doneAmountOnChain string 链上有效期内确认完毕金额
    channelId string 客户名称
    chain string 网络
    address string 收款地址

    非闪兑地址支付单状态变更通知，举例:

    {
    "bizType": "PAY_ADDRESS", 
    "bizId": "1666751129271968", 
    "bizStatus": "PAY_CLOSE", 
    "client_id": "836e1131-fb3d-4648-8b04-bd29c46596ba",  
    "data": "{\"merchantTradeNo\":\"1000220221026006\",\"productType\":\"\",\"productName\":\"测试订单20221026006\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"测试订单20221026006\",\"terminalType\":\"MINIAPP\",\"currency\":\"WMHH\",\"totalFee\":\"0.21\",\"orderAmount\":\"0.21\",\"payerId\":10002,\"createTime\":1666751129271,\"transactionId\":\"1666751408050667\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.1\",\"chain\": \"ETH\",\"address\":\"0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F\", \"channelId\":\"AA\"}" 
}

    消息内容:

    {
    "merchantTradeNo": "1000220221026006", 
    "productType": "", 
    "productName": "测试订单20221026006", 
    "tradeType": "MINIAPP",
    "goodsName": "测试订单20221026006",
    "terminalType": "MINIAPP", 
    "currency": "WMHH", 
    "totalFee": "0.21", 
    "orderAmount": "0.21", 
    "payerId": 10002, 
    "createTime": 1666751129271, 
    "transactionId": "1666751408050667", 
    "waitAmountOnChain": "0", 
    "doneAmountOnChain": "0.1",
    "channelId": "123456",
    "chain": "ETH",
    "address": "0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F"
}

    闪兑地址支付单状态变更通知:

    字段名 类型 说明
    bizType string 描述通知类别， 见表BizType
    bizId string 订单id
    bizStatus string 订单状态，PENDING处理中，PROCESS订单有效期内支付足够金额但链上未确认完毕，PAID订单支付成功，EXPIRED订单已过期
    client_id string 创建订单的商户client_id
    data content 消息内容

    content

    字段名 类型 说明
    merchantTradeNo string 商户交易号
    productType string 创建订单时候的goodsType
    productName string 创建订单时候的GoodsName
    tradeType string 创建订单时候的terminalType
    goodsName string 创建订单时候的GoodsName
    terminalType string 创建订单时候的terminalType
    currency string 订单币种
    totalFee string 订单金额
    orderAmount string 订单金额
    payCurrency string 支付币种
    payAmount string 要求支付金额
    rate string 汇率
    payerId int64 支付用户uid
    createTime int64 创建订单时间，UTC毫秒时间戳
    transactionId string 交易流水号
    waitAmountOnChain string 链上有效期内确认中金额
    doneAmountOnChain string 链上有效期内确认完毕金额
    transferAmount string 给商户转账金额，对应订单币种currency，仅在转账通知中有值，订单状态变化通知中为空字符串
    overPay string 用户支付超过订单要求金额部分，仅在订单状态变更为支付成功时有值，其它时候为0
    channelId string 客户名称

    闪兑地址支付单状态变更通知，举例：

    {
   "bizType": "PAY_ADDRESS",
   "bizId": "46301072319320064",
   "bizStatus": "PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION",
   "client_id": "ygMRT5SdrGpiISVV",
   "data": "{\"merchantTradeNo\":\"938402023010600017\",\"productType\":\"\",\"productName\":\"USDT_PAY_WMHH_TEST\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"USDT_PAY_WMHH_TEST\",\"terminalType\":\"MINIAPP\",\"currency\":\"USDT\",\"totalFee\":\"2.1\",\"orderAmount\":\"2.1\",\"payCurrency\":\"WMHH\",\"payAmount\":\"0.2142\",\"rate\":\"0.1\",\"payerId\":10002,\"createTime\":1673000635873,\"transactionId\":\"\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.2142\",\"transferAmount\":\"\",\"overPay\":\"0\"}"
}

    消息内容:

    {
   "merchantTradeNo": "938402023010600017",
   "productType": "",
   "productName": "USDT_PAY_WMHH_TEST",
   "tradeType": "MINIAPP",
   "goodsName": "USDT_PAY_WMHH_TEST",
   "terminalType": "MINIAPP",
   "currency": "USDT",
   "totalFee": "2.1",
   "orderAmount": "2.1",
   "payCurrency": "WMHH",
   "payAmount": "0.2142",
   "rate": "0.1",
   "payerId": 10002,
   "createTime": 1673000635873,
   "transactionId": "",
   "waitAmountOnChain": "0",
   "doneAmountOnChain": "0.2142",
   "transferAmount": "",
   "overPay": "0",
   "channelId": "123456"
}

    # 4.3.2 订单资金流转通知

    订单资金流转通知:

    字段名 类型 说明
    bizType string 描述通知类别， 见表BizType
    bizId string 订单id
    bizStatus string 参考BizStatus
    client_id string 创建订单的商户client_id
    data content 消息内容

    BizStatus

    值 解释
    TRANSFERRED_ADDRESS_IN_TERM 非闪兑地址支付单检测到成功支付记录后，即时将对应金额充值到商户支付账户中。（有效期内到账转账）
    TRANSFERRED_ADDRESS_DELAY 非闪兑地址支付单检测到延迟支付记录，将延迟支付记录对应金额充值到商户支付账户中。（超过有效期到账转账）
    CONVERT_ADDRESS_PAY_DELAY 闪兑地址支付单延迟到账，通知商户但不充值到商户支付账户
    TRANSFERRED_ADDRESS_BLOCK 资金Gate成功接收,但资金有风险,不会入账

    content

    字段名 类型 说明
    merchantTradeNo string 商户交易号
    productType string 创建订单时候的goodsType
    productName string 创建订单时候的GoodsName
    tradeType string 创建订单时候的terminalType
    goodsName string 创建订单时候的GoodsName
    terminalType string 创建订单时候的terminalType
    currency string 订单币种
    orderAmount string 订单金额
    payerId int64 支付用户uid
    createTime int64 创建订单时间，UTC毫秒时间戳
    transactionId string 交易流水号
    transferAmount string 给商户转账金额。特别的，在闪兑支付单的延迟支付场景，仍会发送收到的金额，但不会进行闪兑，也不会支付给商户，资金保留在Gate链上
    channelId string 客户名称
    chain string 网络
    address string 收款地址

    订单资金流转通知，举例：

    {
    "bizType": "TRANSFER_ADDRESS",
    "bizId": "1666751407010007",
    "bizStatus": "TRANSFERRED_ADDRESS_IN_TERM",
    "client_id": "",
    "data": "{\"merchantTradeNo\":\"1000220221026006\",\"productType\":\"\",\"productName\":\"测试订单20221026006\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"测试订单20221026006\",\"terminalType\":\"MINIAPP\",\"currency\":\"WMHH\",\"orderAmount\":\"0.21\",\"payerId\":10002,\"createTime\":1666751129271,\"transactionId\":\"1666751408050667\",\"transferAmount\":\"0.21\",\"chain\": \"ETH\",\"address\":\"0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F\"}"
}

    消息内容：

    {
   "merchantTradeNo": "1000220221026006", 
   "productType": "",
   "productName": "测试订单20221026006", 
   "tradeType": "MINIAPP", 
   "goodsName": "测试订单20221026006",
   "terminalType": "MINIAPP", 
   "currency": "WMHH",
   "orderAmount": "0.21", 
   "payerId": 10002, 
   "createTime": 1666751129271,
   "transactionId": "1666751408050667",
   "transferAmount": "0.21",
   "channelId": "123456",
   "chain": "ETH",
   "address": "0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F"
}

    # 5. 常见问题

    # Q:为什么用户往链上转了一笔资金之后，订单详情查询不到转账记录？

    A：由于区块链是一个分布式系统，用户向链上发起转账之后需要经历打包，广播等步骤，因此Gate支付后台感知到用户转账动作存在一定延迟。

    # Q:为什么订单显示支付完成，但商户支付账户没有收到入账？

    A：由于地址支付业务中，同一个订单，用户可能发起多笔转账，当订单过期或完成时，链上可能还存在部分记录未确认完毕，Gate支付后台会在订单对应链上支付记录全部确认完毕（成功或失败）后，才向用户支付账户转入等于收到的金额的资金。

    # Q:为什么用户在订单有效期内支付足够金额，订单被判定为过期？

    A：用户向链上转账之后，Gate链系统感知到这一笔转账的时间是链上打包完成的时间，链上打包完成时间是不可控的，Gate支付后台判断用户操作时间是用的链上打包完成时间。

    # Q：如何通过消息通知判断订单收到多少资金？

    A：可根据实际场景来具体分析：

    1、有效期内未足额支付：

    • 资金到账通知：bizStatus = TRANSFERRED_ADDRESS_IN_TERM，到账金额为 transferAmount。（需要累加订单号下所有支付单）

    2、有效期内足额支付：

    • 订单状态变更通知：PAY_SUCCESS：支付成功，到账金额为 doneAmountOnChain。
    • 资金到账通知：bizStatus = TRANSFERRED_ADDRESS_IN_TERM，到账金额为 transferAmount。（需要累加订单号下所有支付单）

    3、有效期内超额支付：同有效期内足额支付。

    4、未支付后过期:

    • 订单状态变更通知：PAY_CLOSE，到账金额为 doneAmountOnChain。

    5、过期后进行支付:

    • 订单状态变更通知：PAY_CLOSE：到账金额为 doneAmountOnChain。

    • 资金到账通知：bizStatus = TRANSFERRED_ADDRESS_DELAY，到账金额为 transferAmount。（需要累加订单号下所有支付单）

      也就是说除了用户有效期内未足额支付的情况，只需要关注订单状态变更通知里bizStatus和doneAmountOnChain两个字段来确认订单到账的资金。

    # 6. 地址支付API列表

    # 6.1 查询支持链列表

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：GET
    • 路径Path: /v1/pay/address/chains
    • 验证⽅式：商户签名验证

    接口说明:

    根据提供的币种，查询支持接受此币种的所有可用链

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    currency string 是 拟下单的币种

    响应参数:

    字段名 类型 说明
    currency string 拟支付的币种
    chains []*ChainNameItem 拟支付币种可选Gate链列表

    ChainNameItem

    字段名 类型 说明
    chain string Gate链
    currency string 拟支付的币种
    full_curr_type string 含网络信息的币种符号，下单重要参数
    symbol string 链上交易符号
    explorer_url string 浏览链接，explorer + token_address

    查询支持链列表，请求示例

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/chains?currency=BTC' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1673311329984' \
--header 'X-GatePay-Nonce: 7248468283' \
--header 'X-GatePay-Signature: a4581433e3f9ef4cf3e9f91bd5fb5943ca25488815e412146b4c2bed96d285cc69b4599950e2e4f894b3a205f2e17e28e252bfa635e0a7a80a1fcbb8a7b94b0d' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--data-raw ''

    查询支持链列表，请求响应

    {
   "status": "SUCCESS",
   "code": "000000",
   "errorMessage": "",
   "data": {
      "currency": "BTC",
      "chains": [
         {
            "chain": "BTC",
            "currency": "BTC",
            "full_curr_type": "BTC",
            "symbol": "BTC",
            "explorer_url": ""
         },
         {
            "chain": "HT",
            "currency": "BTC",
            "full_curr_type": "BTC_HT",
            "symbol": "BTC_HT",
            "explorer_url": ""
         },
         {
            "chain": "BSC",
            "currency": "BTC",
            "full_curr_type": "BTC_BSC",
            "symbol": "BTC_BSC",
            "explorer_url": ""
         }
      ]
   }
}

    # 6.2 查询支持币种列表

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：GET
    • 路径Path: /v1/pay/address/currencies
    • 验证⽅式：商户签名验证

    接口说明:

    查询Gate地址支付支持的所有币种列表

    参数说明:

    请求参数:

    无需请求参数

    响应参数:

    字段名 类型 说明
    currencies []string 可选支付币种列表

    查询地址支付可选支付币种列表，请求示例

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/currencies' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1673323157257' \
--header 'X-GatePay-Nonce: 8965308574' \
--header 'X-GatePay-Signature: 21386c0603a7bb7d2b70f47e908fa863c4b7e6ce63c565ef85a44f3053f6a3c04177423c9889b550d015f9c4e4a225c92c3c0da6f063ae0992dff150bb18fb1e' \
--data-raw ''

    查询地址支付可选支付币种列表，请求响应

    {
   "code": "000000",
   "data": {
      "currencies": [
         "USD",
         "USDT",
         "BTC",
         "ETH",
         "EOS",
         "LTC",
         "BCH",
         "XRP",
         "ZEC",
         "ADA",
         "GT",
         "BNB",
         "DOGE",
         "DOT",
         "SHIB",
         "UNI",
         "FIL",
         "STEPG",
         "SUPE",
         "LION",
         "FROG",
         "WMHH"
      ]
   },
   "errorMessage": "",
   "status": "SUCCESS"
}

    # 6.3 根据订单币种查询支持闪兑的币种

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：GET
    • 路径Path: /v1/pay/address/supportedconvertcurrencies
    • 验证⽅式：商户签名验证

    接口说明:

    创建闪兑地址支付单之前，根据订单币种查询支持闪兑的币种，用户从支持闪兑的币种列表中选择实际支付币种创建闪兑支付订单

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    currency string 是 订单币种

    响应参数:

    字段名 类型 说明
    currencies []string 支持闪兑到订单币种的币种列表

    根据订单币种查询支持闪兑的币种，请求示例

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/supportedconvertcurrencies?currency=BTC' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--data-raw ''

    根据订单币种查询支持闪兑的币种，请求响应

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "currencies": [
            "BTC",
            "USD",
            "USDT",
            "ETH",
            "XRP",
            "ZEC",
            "GT",
            "BNB",
            "DOT",
            "SHIB",
            "LION"
        ]
    }
}

    # 6.4 下单

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：POST
    • 路径Path: /v1/pay/address/create
    • 验证⽅式：商户签名验证

    接口说明:

    创建订单，订单币种和支付币种一致创建直付地址支付单，订单币种和支付币种不一致创建闪兑地址支付单

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    merchantTradeNo string 是 商户系统中的交易号
    currency string 是 订单币种
    orderAmount string 是 订单金额
    payCurrency string 否 用户选择的支付币种，非闪兑单不需要传
    env EnvRequest 是 交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
    goods GoodsRequest 是 商品
    orderExpireTime int64 是 商户指定订单过期时间戳，毫秒为单位
    returnUrl string 否 支付完成回调地址
    cancelUrl string 否 取消支付回调地址
    merchantUserId int64 是 支付者在商户平台注册时的唯一ID
    chain string 是 所选链名字
    fullCurrType string 是 包含链名字的币种字段，对应到具体链的具体币种
    channelId string 否 客户名称

    EnvRequest

    字段名 类型 是否必须 说明
    terminalType string 是 创建订单的终端类型

    GoodsRequest

    字段名 类型 是否必须 说明
    goodsName string 否 商品名称
    goodsDetail string 否 商品详情

    响应参数:

    字段名 类型 说明
    prepayId string 创建的支付单order id
    terminalType string 创建订单的终端类型
    expireTime string 过期毫秒时间戳
    chain Chain 地址支付支付单绑定的链和地址

    Chain

    字段名 类型 说明
    chain_type string 链名称
    address string 订单绑定的链收款地址

    # 6.4.1 非闪兑下单

    非闪兑下单，请求示例

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673323831902' \
--header 'X-GatePay-Nonce: 6225572445' \
--header 'X-GatePay-Signature: 8be2d2efcd59354067cfcde2a38ce5921a0ccf39855331971d0855f79fc7e5218782319e0615559a38c9a95b9e9cd6d6de4b3f4e04a8f81458542c369cef5f10' \
--data-raw '{
"merchantTradeNo": "93840202212210025",
"currency": "BTC",
"orderAmount": "2.1",
"env": {
"terminalType": "MINIAPP"
},
"goods": {
"goodsName": "USDT_PAY_BTC_TEST",
"goodsDetail": "yc"
},
"orderExpireTime": 1673410179000,
"returnUrl": "www.test1.com",
"cancelUrl": "www.test2.com",
"merchantUserId": 1336974,
"chain": "BSC",
"fullCurrType": "BTC_BSC",
"channelId":"123456"
}'

    非闪兑下单，请求响应

    {
   "status": "SUCCESS",
   "code": "000000",
   "errorMessage": "",
   "data": {
      "prepayId": "47656656276819968",
      "terminalType": "MINIAPP",
      "expireTime": 1673410179000,
      "chain": {
         "chain_type": "BSC",
         "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD"
      }
   }
}

    # 6.4.2 闪兑下单

    注意：考虑汇率波动，闪兑单过期时间最长不超过10分钟

    闪兑下单，请求示例

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673328735311' \
--header 'X-GatePay-Nonce: 6685832510' \
--header 'X-GatePay-Signature: cbaa0ea384fd5381c418987007136bb70ea88d962927a69f644cd0c2dc54daa605eb44b67eeb2c92eff989fa02d04f0559543bed125a403474c3b09896bfd050' \
--data-raw '{
"merchantTradeNo": "93840202212210017",
"currency": "BTC",
"orderAmount": "2.1",
"payCurrency": "USDT",
"env": {
"terminalType": "MINIAPP"
},
"goods": {
"goodsName": "USDT_PAY_BTC_TEST",
"goodsDetail": "yc"
},
"orderExpireTime": 1673415121000,
"returnUrl": "www.test1.com",
"cancelUrl": "www.test2.com",
"merchantUserId": 1336974,
"chain": "BSC",
"fullCurrType": "BTC_BSC",
"channelId":"123456"
}'

    闪兑下单，请求响应

    {
   "status": "SUCCESS",
   "code": "000000",
   "errorMessage": "",
   "data": {
      "prepayId": "47677222950014976",
      "terminalType": "MINIAPP",
      "expireTime": 1673329335572,
      "chain": {
         "chain_type": "BSC",
         "address": "0x68C1EC61df04B4e8CCcc94687071bEeA0cac738b"
      }
   }
}

    # 6.5 查询支付单详情

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：GET
    • 路径Path: /v1/pay/address/query
    • 验证⽅式：商户签名验证

    接口说明:

    查新地址支付单详情，指定的参数必须对应到地址支付单，否则会返回错误

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    prepayId string 是 地址支付预支付单id
    merchantTradeNo string 是 商户系统交易号

    响应参数:

    字段名 类型 说明
    prepayId string 支付单单号
    merchantId int64 用于申请商户账号的Gate UID
    merchantTradeNo string 商户系统交易号
    transactionId string 交易流水号
    goodsName string 商品名，商户创建订单时提供
    currency string 订单币种
    orderAmount string 订单金额
    payCurrency string 用户实际支付币种，非闪兑单中与订单币种一致
    payAmount string 用户应该支付的金额
    rate string 订单币种到用户支付币种的汇率，例如，1BTC换20000USDT
    status string 订单状态，PENDING处理中，PROCESS订单有效期内支付足够金额但链上未确认完毕，PAID订单支付成功，EXPIRED订单已过期
    createTime int64 订单的创建时间
    expireTime int64 订单的过期时间
    transactTime int64 订单在Gate内部交易发生时间
    order_name string 订单名称
    transaction_info ChainTransactionInfo 订单在链上交易情况总览
    channelId string 客户名称
    chain string 网络
    address string 收款地址

    ChainTransactionInfo

    字段名 类型 说明
    done_amount string 订单有效期内的支付记录在链上确认完毕金额
    confirming_list []*ConfirmItem 订单有效期内的支付记录在链上确认中的支付列表

    ConfirmItem

    字段名 类型 说明
    amount string 支付记录金额
    confirm int 确认数

    查询支付单，请求示例

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/query?prepayId=1661239048576446&merchantTradeNo=43959345943769874395' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--data-raw ''

    查询支付单，请求响应

    {
   "prepayId": "1661239048576446",
   "merchantId": 10002,
   "merchantTradeNo": "43959345943769874395",
   "transactionId": "347827943294834379",
   "goodsName": "abc",
   "currency": "BTC",
   "orderAmount": "9.88",
   "payCurrency": "USDT",
   "payAmount": "197600",
   "rate": "20000",
   "status": "PENDING",
   "createTime": 1663657128148,
   "expireTime": 1664089128000,
   "transactTime": 1663829928000,
   "order_name": "orderName",
   "transaction_info": {
      "done_amount": "8.88",
      "confirming_list": [
         {
            "amount": "0.35",
            "confirm": 3
         },
         {
            "amount": "0.65",
            "confirm": 4
         }
      ]
   },
  "channelId":"123456",
  "chain":"ETN",
  "address":"0x67C30f439D7734f393c2F4a587B198b8F4086Ccb"
}

    # 6.6 退款

    注意：只支持退款到Gate用户的支付账户，需提供接收退款用户的Gate Uid

    # 6.6.1 非闪兑支付单退款

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：POST
    • 路径Path: /v1/pay/address/refund
    • 验证⽅式：商户签名验证

    接口说明: 对直付地址支付单发起退款，只支持直付地址支付单，若提供的参数对应到闪兑支付单，会返回错误

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    refundRequestId string 是 商户请求退款编号
    prepayId string 是 对应支付单订单id
    refundAmount string 是 退款金额
    refundReason string 否 退款原因
    receiverId string 是 地址支付退款接收人在gate系统的user_id

    响应参数:

    字段名 类型 说明
    refundRequestId string 商户退款请求id
    prepayId string 拟退款的订单id
    orderAmount string 订单金额
    refundAmount string 退款金额

    非闪兑支付单退款，请求示例

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/refund' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--data-raw '{
    "refundRequestId": "483902480932841787",
    "prepayId": "1665553233227833",
    "refundAmount": "20",
    "refundReason": "test refund function",
    "receiverId": 598816
}'

    非闪兑支付单退款，请求响应

    {
    "refundRequestId": "483902480932841787", 
    "prepayId": "1665553233227833", 
    "orderAmount": "14.9", 
    "refundAmount": "4.9" 
}

    # 6.6.2 闪兑支付单退款

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：POST
    • 路径Path: /v1/pay/address/refundconvert
    • 验证⽅式：商户签名验证

    接口说明:

    对闪兑地址支付单发起退款，只支持闪兑地址支付单，若提供的参数对应到直付支付单，会返回错误

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    refundRequestId string 是 商户请求退款编号
    prepayId string 是 对应支付单订单id
    refundOrderCurrency string 是 退款订单币种
    refundOrderAmount string 否 退款订单币种对应退款金额
    refundPayCurrency string 是 退款订单支付币种
    refundPayAmount string 是 退款订单支付币种对应退款金额
    refundReason string 是 退款原因
    receiverId string 是 地址支付退款接收人在gate系统的user_id

    响应参数:

    字段名 类型 说明
    refundRequestId string 商户退款请求id
    prepayId string 拟退款的订单id
    orderCurrency string 订单币种
    orderAmount string 订单金额
    refundOrderAmount string 对应订单币种的退款金额
    payCurrency string 用户支付币种
    payAmount string 订单中用户应该支付的金额
    refundPayAmount string 对应订单用户支付币种的退款金额

    闪兑支付单退款，请求示例

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/refundconvert' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--data-raw '{
    "refundRequestId": "483902480932841787",
    "prepayId": "1665553233227833",
    "refundOrderCurrency": "BTC",
    "refundOrderAmount": "1.1",
    "refundPayCurrency": "USDT",
    "refundPayAmount": "1000.1",
    "refundReason": "refund test",
    "receiverId": 123456
}'

    闪兑支付单退款，请求响应

    {
   "status": "SUCCESS",
   "code": "00000",
   "errorMessage": "",
   "data": {
      "refundRequestId": "483902480932841787",
      "prepayId": "1665553233227833", 
      "orderCurrency": "BTC", 
      "orderAmount": "2.2", 
      "refundOrderAmount": "1.1", 
      "payCurrency": "USDT", 
      "payAmount": "44000", 
      "refundPayAmount": "1000.1" 
   }
}

    # 6.7 查询链上交易详情

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：GET
    • 路径Path: /v1/pay/address/transactiondetail
    • 验证⽅式：商户签名验证`

    接口说明： 查询地址直付单在链上的交易详情，包含有效期内直付记录和有效期外的支付记录两部分

    参数说明:

    请求参数:

    字段名 类型 是否必须 说明
    prepayId string 是 地址支付预支付单id

    响应参数:

    字段名 类型 说明
    prepayId string 支付单id
    merchantId int64 用于申请商户账号的Gate UID
    merchantTradeNo string 商户系统交易号
    transactionId string 交易流水号
    goodsName string 商品名称
    currency string 订单币种
    orderAmount string 订单金额
    payCurrency string 用户实际支付币种
    payAmount string 订单对应用户实际支付币种的金额
    status string 订单状态
    utcCreateTime string 订单创建时间的utc表达，例如2023-01-07 14:04:02
    utcExpireTime string 订单过期时间的utc表达，例如2023-01-07 14:04:02
    utcUpdateTime string 订单状态更新时间的utc表达，例如2023-01-07 14:04:02
    transactTime int64 订单在后台完成交易的UTC毫秒时间戳
    order_name string 订单名称
    transactionDetail *TransactionDetail 链上交易详情
    channelId string 客户名称

    TransactionDetail

    字段名 类型 说明
    inTerm *TxDetail 有效期内的支付记录详情
    outOfTerm *TxDetail 有效期外的支付记录详情

    TxDetail

    字段名 类型 说明
    done *TxDetailStateItem 链上确认完毕的交易详情
    wait *TxDetailStateItem 链上确认中的交易详情

    TxDetailStateItem

    字段名 类型 说明
    amount string 链上确认完毕总金额
    txList []*TxItem 支付记录列表

    TxItem

    字段名 类型 说明
    chain string 链名称
    address string 地址
    fullCurrType string 含网络信息的链名称
    amount string 支付金额
    txId string 链上交易id
    utcCreateTime string 链上检测到支付记录时间的utc表达，例如2023-01-07 14:04:02
    utcUpdateTime string 链上确认进度更新支付记录状态的时间的utc表达，例如2023-01-07 14:04:02

    查询链上交易详情请求示例

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/transactiondetail?prepayId=40100646616043520' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1671522977660' \
--header 'X-GatePay-Nonce: 9170105160' \
--header 'X-GatePay-Signature: b76949cf84c8ee9b11af0526adaf8aca72e8f777b35777452b00b920624b7ec4e9ef7d62b80109f61cdb7caaa78d00af02cd270f1c01d84f81aa1ee28659afb1' \
--data-raw ''

    查询链上交易详情请求响应

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "40100646616043520", 
        "merchantId": 10002, 
        "merchantTradeNo": "9384029384092499", 
        "transactionId": "1671522905110477", 
        "goodsName": "",
        "currency": "BTC",
        "orderAmount": "212.999", 
        "payCurrency": "BTC", 
        "payAmount": "212.999", 
        "status": "EXPIRED", 
        "utcCreateTime": "2022-12-20 07:45:39", 
        "utcExpireTime": "2022-12-20 07:55:00", 
        "transactTime": 1671522905110,
        "order_name": "MiniApp-Payment-1#9384029384092499", 
        "channelId": "123456", 
        "transactionDetail": { 
            "inTerm": { 
                "done": { 
                    "amount": "100", 
                    "txList": [ 
                        {
                            "chain": "BTC", 
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", 
                            "fullCurrType": "BTC", 
                            "amount": "100", 
                            "txId": "dosajdajdiojawojdoiwajdojaefhs", 
                            "utcUpdateTime": "2022-12-19 11:50:00" 
                        }
                    ]
                },
                "wait": { 
                    "amount": "99",
                    "txList": [
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "99",
                            "txId": "dosajdajdiojawojdoiwajdojaikjs",
                            "utcUpdateTime": "2022-12-19 11:50:00"
                        }
                    ]
                }
            },
            "outOfTerm": { 
                "done": {
                    "amount": "98",
                    "txList": [
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "98",
                            "txId": "dosajdajdoakawojdoiwajdojaikjs",
                            "utcUpdateTime": "2022-12-19 11:56:00"
                        }
                    ]
                },
                "wait": { 
                    "amount": "193",
                    "txList": [
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "97",
                            "txId": "dosajdajdiojawolakiwajdojaikjs",
                            "utcUpdateTime": "2022-12-19 11:56:00"
                        },
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "96",
                            "txId": "dosajdajdiojawolakiwajdppaikjs",
                            "utcUpdateTime": "2022-12-19 11:56:00"
                        }
                    ]
                }
            }
        }
    }
}

    # 7. 错误码

    错误码 描述 解决方案
    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地址支付没有可用地址 创建订单无可用地址
    500202 使用普通支付单退款接口对地址支付单进行退款 使用地址支付单退款接口
    500203 查询链上地址支付详情，但指定的不是地址支付订单 检查订单id，提供正确的地址支付订单id
    500204 地址支付单退款，提供的接收退款的Gate用户id不存在或已封禁 提供正确的Gate用户uid
    500205 闪兑地址支付单退款，退款币种与订单币种和用户支付币种不匹配 检查申请退款参数，与订单币种保持一致
    500206 申请退款金额超过可退款金额上限 检查参数，修正金额
    500207 使用地址支付单退款接口对非地址支付单进行退款 检查参数，提供地址支付订单id
    500208 使用闪兑地址支付单退款接口对非闪兑地址支付单进行退款 检查参数，提供正确的闪兑地址支付订单id
    Last Updated: 6/3/2025, 1:43:31 AM