# changelog

    # v1.0.0

    2024-09-25
    静态收款地址支付方式接入文档初版
    

    # 1. 功能介绍

    静态地址收款方式目标是支持用户在没有Gate账户前提下,可以使用任意钱包资产与Gate商户进行交易

    区别于现有"地址支付",静态收款地址不会为每一笔账单分配一个不同的地址,而是商户事先申请一定数

    量的静态地址,用户向静态地址转账,Gate生成支付账单,结算至商户Gate支付账户,并向商户推送用

    户支付信息

    # 2. 静态收款码支付

    # 2.1 安全验证

    安全验证参考接口签名

    # 2.2 时序图

    # 3. 消息通知

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

    • 当商户绑定的收款地址有收入,且收款网络和接收币种在商户营收范围内

    # 3.2 静态地址收款消息枚举值

    bizType

    解释
    PAY_FIXED_ADDRESS 表示这是一个静态地址收款的通知类型

    bizStatus

    解释
    PAY_SUCCESS 支付成功,且到账
    PAY_BLOCK Gate成功接收,但资金有风险,不会入账

    # 3.3 静态地址收款消息字段

    字段名 类型 说明
    bizType string 消息提示类型
    bizId string 订单号
    data string dataType的json编码

    dataType

    字段名 类型 说明
    channelId string 客户名称,只支持字母、数字、下划线和破折号,长度不超过50字节
    currency string 账单币种
    orderAmount string 账单金额
    createTime int 账单创建时间
    transactionId string 交易流水号
    transactionTime string 账单成交时间
    chain string 网络
    address string 收款地址
    amount string 到账金额

    消息结构示例

    {
        "bizType": "PAY_FIXED_ADDRESS",
        "bizId": "kt40t9i3t34kt0k09t543932111146",
        "bizStatus": "PAY_SUCCESS",
        "data": "{\"channelId\":\"smart_shop\",\"currency\":\"USDT\",\"amount\":\"5\",\"orderAmount\":\"5\",\"createTime\":1727160132504,\"transactionId\":\"273462465781567488\",\"transactionTime\":1727160132504,\"chain\":\"ETH\",\"address\":\"0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F\"}"
    }
    

    商户在收到异步回调消息后,需按如下结构响应,returnCodeSUCCESS,否则Gate会认为没有提示成功,响应示例如下

    {
        "returnCode": "SUCCESS",
        "returnMessage": ""
    }
    

    # 4. 静态收款地址API列表

    # 4.1 查询支持的网络和币种

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

    接口说明:

    查询GatePay支持用于静态地址收款的网络和币种

    请求参数:

    响应参数:

    字段名 类型 说明
    Chains []*FixedChainItem 支持的网络、币种列表

    FixedChainItem

    字段名 类型 说明
    chain string 网络
    showChainNameEn string 网络英文名称
    currencies string 该网络下支持的币种

    请求示例

    curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/chains' \
    --header 'Content-Type: application/json' \
    --header 'X-GatePay-Timestamp: 1727244774062' \
    --header 'X-GatePay-Nonce: 6528576972' \
    --header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
    --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'
    

    响应示例

    {
        "status": "SUCCESS",
        "code": "000000",
        "errorMessage": "",
        "data": {
            "Chains": [
                {
                    "chain": "ETH",
                    "showChainNameEn": "ETH/ERC20",
                    "currencies": [
                        "USDT",
                        "DAI",
                        "ETH",
                        "MATIC",
                        "USDC"
                    ]
                },
                {
                    "chain": "TRX",
                    "showChainNameEn": "Tron/TRC20",
                    "currencies": [
                        "USDT"
                    ]
                }
            ]
        }
    }
    

    # 4.2 创建静态收款地址

    • 数据类型:JSON (content-type:application/json)
    • 请求⽅式:POST
    • 路径Path: /v1/pay/fixedaddress/save
    • 验证⽅式:商户签名验证

    接口说明:

    按照指定币种和网络,生成静态收款地址

    注意: 若channelId + chain已经存在静态收款地址,则会将请求中的currenciescallbackUrl更新到已绑定信息中

    请求参数:

    字段名 类型 是否必须 说明
    channelId string 客户名称,只支持字母、数字、下划线和破折号,长度不超过50字节
    chain string 网络名称
    currencies string 要在该静态地址上营收的币种,多币种逗号分隔,例如USDT,BTC
    callbackUrl string 该渠道到账回调地址,长度不超过128字节

    响应参数:

    字段名 类型 说明
    channelId string 客户名称
    chain string 网络名称
    address string 收款地址
    currencies []string 该网络上的收款币种列表
    callbackUrl string 该渠道下的收款消息回调地址

    请求示例

    curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/save' \
    --header 'Content-Type: application/json' \
    --header 'X-GatePay-Timestamp: 1727602580817' \
    --header 'X-GatePay-Nonce: 9167310285' \
    --header 'X-GatePay-Signature: a23f55ded2e938fd7b6cd436837b21ec8fd413f3dbd496cffae3bedac3a41c7bf684ca46a25484f8b1607d90313ff46aff2d5b75765ef1d97f51bc63f8e0c139' \
    --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
    --data '{
        "channelId": "smart_shop",
        "chain": "ETH",
        "currencies": "DAI,USDT",
        "callbackUrl": "https://www.abc.com/callback"
    }'
    

    响应示例

    {
      "status": "SUCCESS",
      "code": "000000",
      "errorMessage": "",
      "data": {
        "channelId": "smart_shop",
        "chain": "ETH",
        "address": "0x2EBa11a702F1d53c6e2F08278819e26E6e4a63ae",
        "currencies": [
          "DAI",
          "USDT"
        ],
        "callbackUrl": "https://www.abc.com/callback"
      }
    }
    

    # 4.3 查询静态收款地址列表

    • 数据类型:JSON (content-type:application/json)
    • 请求⽅式:GET
    • 路径Path: /v1/pay/fixedaddress/list
    • 验证⽅式:商户签名验证

    接口说明:

    请求参数:

    字段名 类型 是否必须 说明
    page int 从0开始的非负整数,表示页号
    count int 正整数,每页显示条数,最大100

    响应参数:

    字段名 类型 说明
    total int 总数量
    list []*FixedAddressItem 静态收款地址列表

    FixedAddressItem

    字段名 类型 说明
    channelId string 客户名称
    chain string 网络
    address string 收款地址
    currencies []string 该地址上绑定的收款币种
    callbackUrl string 到账回调地址
    createTime int 创建时间
    updateTime int 首次更新时间

    请求示例

    curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/list?page=0&count=10' \
    --header 'Content-Type: application/json' \
    --header 'X-GatePay-Timestamp: 1727244774062' \
    --header 'X-GatePay-Nonce: 6528576972' \
    --header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
    --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'
    

    响应示例

    {
      "status": "SUCCESS",
      "code": "000000",
      "errorMessage": "",
      "data": {
        "total": 2,
        "list": [
          {
            "channelId": "smart_shop1",
            "chain": "ETH",
            "address": "0xE2b3fA811f04FD5Ac6559007795D6Fc74365126B",
            "currencies": [
              "USDC"
            ],
            "callbackUrl": "https://www.abc.com/callback",
            "createTime": 1727603135221,
            "updateTime": 1727603135221
          },
          {
            "channelId": "smart_shop",
            "chain": "ETH",
            "address": "0x3FdC81C3f549343a3E0706A382035B7B461C0840",
            "currencies": [
              "DAI",
              "USDT"
            ],
            "callbackUrl": "https://www.abc.com/callback",
            "createTime": 1727603076963,
            "updateTime": 1727603076963
          }
        ]
      }
    }
    

    # 4.4 查看静态收款地址详情

    • 数据类型:JSON (content-type:application/json)
    • 请求⽅式:GET
    • 路径Path: /v1/pay/fixedaddress/detail
    • 验证⽅式:商户签名验证

    接口说明:

    请求参数:

    字段名 类型 是否必须 说明
    channelId string 客户名称
    chain string 网络

    响应参数:

    字段名 类型 说明
    channelId string 商户绑定静态地址收款时指定的渠道名称
    chain string 网络
    address string 收款地址
    currencies []string 该地址上绑定的收款币种
    callbackUrl string 到账回调地址
    createTime int 创建时间
    updateTime int 首次更新时间

    请求示例

    curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/detail?channelId=smart_shop&chain=ETH' \
    --header 'Content-Type: application/json' \
    --header 'X-GatePay-Timestamp: 1727603139811' \
    --header 'X-GatePay-Nonce: 2839411632' \
    --header 'X-GatePay-Signature: ca46d4a5b7a516faf6d8d770eeba814004733b9660c35f472b36f4cfa045df2df905b0cdcf3a8212a4c39085ed3843fa721b3dd10cbb931dd32fbf4363d36a52' \
    --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'
    

    响应示例

    {
      "status": "SUCCESS",
      "code": "000000",
      "errorMessage": "",
      "data": {
        "channelId": "smart_shop",
        "chain": "ETH",
        "address": "0x5178ff5B10c17282834028E0A79cb18586D44B7C",
        "currencies": [
          "DAI",
          "USDT"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "createTime": 1727602420837,
        "updateTime": 1727602430742
      }
    }
    

    # 4.5 删除静态收款地址

    • 数据类型:JSON (content-type:application/json)
    • 请求⽅式:DELETE
    • 路径Path: /v1/pay/fixedaddress/delete
    • 验证⽅式:商户签名验证

    接口说明:

    请求参数:

    字段名 类型 是否必须 说明
    channelId string 客户名称
    chain string 网络

    响应参数:

    字段名 类型 说明
    result string ok表示成功,其它表示失败

    请求示例

    curl --location --request DELETE 'https://openplatform.gateapi.io/v1/pay/fixedaddress/delete?channelId=smart_shop&chain=ETH' \
    --header 'Content-Type: application/json' \
    --header 'X-GatePay-Timestamp: 1727603139811' \
    --header 'X-GatePay-Nonce: 2839411632' \
    --header 'X-GatePay-Signature: ca46d4a5b7a516faf6d8d770eeba814004733b9660c35f472b36f4cfa045df2df905b0cdcf3a8212a4c39085ed3843fa721b3dd10cbb931dd32fbf4363d36a52' \
    --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'
    

    响应示例

    {
      "status": "SUCCESS",
      "code": "000000",
      "errorMessage": "",
      "data": {
        "result": "ok"
      }
    }
    

    # 4.6 查询静态收款码账单列表

    • 数据类型:JSON (content-type:application/json)
    • 请求⽅式:GET
    • 路径Path: /v1/pay/fixedaddress/order/query
    • 验证⽅式:商户签名验证

    接口说明:

    请求参数:

    字段名 类型 是否必须 说明
    channelId string 客户名称
    chain string 网络
    startTime int 订单创建时间开始,单位毫秒
    endTime int 订单创建时间结束,单位毫秒
    page int 从0开始的非负整数,表示页号
    count int 正整数,每页显示条数,最大5000
    address string 收款方Web3地址
    fromAddress string 付款方Web3地址
    txHash string 交易hash

    响应参数:

    字段名 类型 说明
    total int 总数量
    list []*PaymentDetails 静态收款账单列表

    PaymentDetails

    字段名 类型 说明
    chain string 网络
    channelId string 客户名称
    currency string 币种
    address string 收款方Web3地址
    amount string 到账金额
    status string 订单状态
    txTime int 订单创建时间,单位毫秒
    fromAddress string 付款方Web3地址
    txHash string 交易hash
    transactionId string 交易流水号

    请求示例

    curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/order/query?page=0&count=10' \
    --header 'Content-Type: application/json' \
    --header 'X-GatePay-Timestamp: 1727244774062' \
    --header 'X-GatePay-Nonce: 6528576972' \
    --header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
    --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'
    

    响应示例

    {
      "status": "SUCCESS",
      "code": "000000",
      "errorMessage": "",
      "data": {
        "total": 1,
        "details": [
          {
            "chain": "ETH",
            "channelId": "123456",
            "currency": "USDT",
            "address": "0x67C30f439D7734f393c2F4a587B198b8F4086Ccb",
            "amount": "0.62345679",
            "status": "PAID",
            "txTime": 1730960078091,
            "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN",
            "txHash": "1820949498602496000930038912",
            "transactionId": "343656213785650801"
          }
        ]
      }
    }
    

    # 5. 其它