# 1.商户接入

    # 1.1 线上服务地址

    https://openplatform.gateapi.io

    # 1.2 配置新增小程序

    • 登录商户后台，商户后台地址https://www.gate.com/zh/merchant#/get-started
    • 填写基本资料，申请成为商户
    • 进入应用配置页面，配置新应用
    • 查看已配置应用列表，获取应用ClientId

    # 1.3 生成支付秘钥

    • 进入开发者页面，生成"支付API秘钥"，用于计算支付接口签名验签
    • 进入开发者页面，生成"授权秘钥"，用于计算授权接口签名验签

    # 1.4 关键参数

    • 支付API秘钥，⽤于请求签名
    • ClientId，用于识别身份，配合支付API秘钥进行验签

    # 2. 安全要求

    # 2.1 协议规则

    # 2.1.1 表接口规则

    字段 描述
    传输方式 为保证交易安全性，采用HTTPS传输，并使用TLS1.2及以上
    数据格式 请求和响应数据都为JSON格式
    签名算法 HMAC-512算法。
    签名要求 请求和接收数据均需要校验签名，详细方法请参考,接口签名章节
    判断逻辑 先判断协议status字段返回，再判断业务返回，最后判断交易状态

    # 2.1.2 响应格式

    所有接口响应返回JSON格式

    字段名 类型 说明
    status string 接口响应结果，SUCESS成功，FAIL失败
    code string 响应错误码
    label string 响应错误名称
    errorMessage string 错误描述
    data string JSON格式业务响应数据

    请求成功响应示例:

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "43013197477711872",
        "merchantId": 10002,
        "merchantTradeNo": "13683379532935164644",
        "currency": "USDT",
        "totalFee": "1.6",
        "merchant_name": "MINIAPP PAYMENT TEST",
        "goods_name": "NFT",
        "status": "PENDING",
        "qrcode": "http://openplatform.gate.io/qr/P_6uSR4icI56VUdM2lbYdVihLxR_SsrcNfbdzNzfgp0=",
        "create_time": 1672216745425,
        "expire_time": 1672220345420
    }
}

    失败响应示例：

    {
  "status": "FAIL",
  "code": "400002",
  "label": "INVALID_SIGNATURE",
  "errorMessage": "Incorrect signature result",
  "data": {}
}

    # 2.2 API协议头规范

    为确定GatePay API收到的请求一定来自于被授权的合法第三方平台，GatePay API接口会检查HTTP请求头部的必须字段对请求进行签名验证。

    # 2.2.1 新版本协议头

    新版协议头，使用在商户后台生成的秘钥计算签名

    Head字段 为保证交易安全性，采用HTTPS传输
    X-GatePay-Certificate-ClientId 商户在Gate商户后台注册应用时分配的clientId
    X-GatePay-Timestamp 请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
    X-GatePay-Nonce 随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
    X-GatePay-Signature 请求签名。GatePay通过此签名来确定此请求是否合法

    # 2.3 接口签名

    # 2.3.1 签名规范

    构造签名串

    我们希望商户的技术开发人员按照当前文档约定的规则构造签名串。 GatePay会使用同样的方式构造签名串。如果商户构造签名串的方式错误，将导致签名验证不通过。下面先说明签名串的具体格式。

    每一行为一个参数。行尾以\n（换行符，ASCII编码值为0x0A）结束。如果参数本身以\n结束，也需要附加一个\n。

    请求时间戳\n请求随机串\n请求报文主体\n

    # 2.3.2 签名算法

    签名算法示例见右侧

    GO语言

    import 
(
"crypto/hmac"
"crypto/sha512"
"encoding/hex"
"fmt"
)
// GenerateSignature 生成请求签名
// timestamp: 转换成字符串的UTC时间戳，精度是millisecond
// nonce: 随机字符串
// body: 请求体
// secretKey: Gate提供的api_secret
// return: 字符串签名
func GenerateSignature(timestamp string, nonce string, body string, secretKey string) string {
  payload := fmt.Sprintf("%s\n%s\n%s\n", timestamp, nonce, body)
  mac := hmac.New(sha512.New, []byte(secretKey))
  mac.Write([]byte(payload))
  signature := mac.Sum(nil)
  return hex.EncodeToString(signature)
}

    JAVA语言

    import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.security.InvalidKeyException;
  import java.security.NoSuchAlgorithmException;
  import java.util.Formatter;
  
  public class Main {
  
      private static final String HMAC_SHA512 = "HmacSHA512";
  
      private static String toHexString(byte[] bytes) {
          Formatter formatter = new Formatter();
          for (byte b : bytes) {
              formatter.format("%02x", b);
          }
          return formatter.toString();
      }
  
      public static String calculateHMAC(String data, String key)
              throws  InvalidKeyException, NoSuchAlgorithmException {
          SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(), HMAC_SHA512);
          Mac mac = Mac.getInstance(HMAC_SHA512);
          mac.init(secretKeySpec);
          return toHexString(mac.doFinal(data.getBytes()));
      }
  
      public static void main(String[] args) throws Exception {
          String timeStamp = "1673613945439";
          String nonce = "3133420233";
          String body = "{\"code\":\"ac8B7Pl7C-XgfH6zxtd3SidYt7XIfWKU\",\"grant_type\":\"authorization_code\",\"redirect_uri\":\"https://gate.bytetopup.com\",\"client_id\":\"2Ugf9YGMCFRk85Yy\"}";
          String data = String.format("%s\n%s\n%s\n", timeStamp, nonce, body);
          String key = "zgsN5DntmQ2NCQiyJ4kJLyyEO25ewdDHydOSFIHdGrM=";
          String hmac = calculateHMAC(data, key);
          System.out.println(hmac);
      }
  }

    Python语言

    import hashlib
  import hmac
  def generate_signature(timestamp: string, nonce: string, body string, secret: string) -> string:
      '''
      生成请求签名
      :param timestamp: 转换成字符串的UTC时间戳，精度是millisecond
      :param nonce: 随机字符串
      :param body: 请求体
      :param secret: GatePay提供的api_secret
      :return: 返回字符串签名
      '''
      payload = '%s\n%s\n%s\n' % (timestamp, nonce, body)
      signed = hmac.new(secret.encode(), payload.encode(), hashlib.sha512)
      return signed.digest().hex()

    PHP语言

    <?php

function generateSignature($timestamp, $nonce, $body, $secretKey) {
    $payload = "$timestamp\n$nonce\n$body\n";
    $signature = hash_hmac('sha512', $payload, $secretKey, true);
    return bin2hex($signature);
}

$timestamp = "1631257823000";
$nonce = "abcd1234";
$body = 'the post request body content';
$secretKey = "your_secret_key";

$signature = generateSignature($timestamp, $nonce, $body, $secretKey);
echo "Signature: " . $signature;

    # 3. 提现API列表

    # 3.1 提现下单

    • 数据类型：JSON （content-type：application/json）

    • 请求⽅式：POST

    • 路径Path: /v1/pay/withdraw

    • 验证方式：签名验证

    • 请求体内容:

      字段名 类型 是否必须 说明
      batch_id string 是 由商户侧生成并保证唯一，只能由大小写字符，数字，下划线组成,最大长度32字符
      withdraw_list 数组对象 是 描述各提现子单详情
      channel_id string 否 客户名称

      withdraw_list 列表字段:

      字段名 类型 是否必须 说明
      merchant_withdraw_id string 是 商户生成子单唯一ID,只能由大小写字符，数字，下划线组成，最大长度32字符
      amount string 是 单笔提现金额,精度最大长度为6位，超过8位会截取后保留
      currency string 是 提现币种
      chain string 是 链网络
      address string 是 提现地址
      memo string 是 转账等备注信息，个别网络转账时必须有，不需要时填写可能会导致失败。最大长度为128字符
      fee_type Int 是 提现手续费的收取方式：
      *如果选择内扣，则手续费将从提现金额中收取，到账金额为提现金额扣除手续费；
      *如果选择外收，则手续费将从账户余额中扣除，到账金额即为提现金额。
      存量不传默认为内扣的方式
      类型枚举：
      0-内扣
      1-外收

    ​ 请求示例:

    curl --location 'https://openplatform.gateapi.io/v1/pay/withdraw' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1725956825391' \
--header 'X-GatePay-Nonce: 1698252264' \
--header 'X-GatePay-Signature: fee74083ef2f64b8c0acbc4c0638586e6352b0d307d74aac038b2a7f40b396f8b47e6c18a6ed3da296168c9ff5a2a973b55115f969e95c0231c2bbbc70f7dea7' \
--data '{
  "batch_id" : "237394559478075350",
  "withdraw_list": [
    {
      "merchant_withdraw_id": "M137394559478075550",  
      "currency": "USDT",
      "amount": "1",
      "chain": "ETH",
      "address": "0x1234567890abcdef",
      "memo" : "Payment for services-1",
      "fee_type": 1
    },
    {
      "merchant_withdraw_id": "M137394559478075551",    
      "currency": "USDT",
      "amount": "0.001",
      "chain": "ETH",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "memo" : "Payment for services-1",
      "fee_type": 0
    }
  ]
}'

    响应实例:

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "batch_id": "237394559478075550"
    }
}

    响应体内容:

    字段名 类型 说明
    batch_id string 由商户侧生成的唯一ID

    # 3.2 提现订单状态查询

    • 数据类型：JSON （content-type：application/json）
    • 请求⽅式：POST
    • 路径Path: /v1/pay/withdraw/query
    • 验证方式：签名验证
    • 请求体内容:
    字段名 类型 是否必须 说明
    batch_id string 是 由商户侧在/v1/pay/withdraw生成的唯一ID
    detail_status string 是 想查询子订单状态
    ALL 全部子订单
    PENDING 待处理子订单
    PROCESSING 已提交提现请求，待确认子订单
    CHECK 审核中子订单
    FAIL 失败子订单
    DONE 提现成功子订单
    • 响应体内容:

    # withdraw_list 列表字段

    字段名 类型 说明
    id int64 记录ID
    batch_id string 商家批量提现id
    merchant_id int64 商家ID
    channel_id string 客户名称
    suborder_id string gatepay生成的子单id
    withdraw_id string 提现的交易id，用这个id查询提现单
    chain string gate_chain链名称
    address string 提现地址
    currency string 币种
    amount decimal.Decimal 发起提现金额
    fee decimal.Decimal 手续费
    tx_id string 交易hash
    timestamp int64 充提侧操作时间
    memo string 转账memo等备注信息
    status string 状态
    merchant_withdraw_id string 商家提现ID
    err_msg string 发起提现失败原因
    client_id string 创建订单的商户client_id
    create_time int64 创建时间
    update_time int64 更新时间
    fee_type int8 0-金额为扣款金额，1-金额为到账金额
    batch_withdraw_id string 已废弃
    desc string 非column字段，客户渠道备注
    reconciliation_status int8 提现对账状态 0-未对账 1-对账处理中 2-对账匹配失败 3-对账匹配成功
    is_placed int 0 - 未下单， 1- 已下单
    finish_time int64 订单结束时间
    sub_amount decimal.Decimal 总扣减金额（手续费金额+到账金额）
    done_amount decimal.Decimal 到账金额

    # 主订单信息

    字段名 类型 说明
    batch_id string 批次ID
    merchant_id int64 商家ID
    client_id string 创建订单的商户client_id
    status string 总单的状态
    create_time int64 总单创建时间
    withdraw_list array 子单信息
    channel_id string 客户名称

    请求示例:

    curl --location 'https://openplatform.gateapi.io/v1/pay/withdraw/query' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1726027137585' \
--header 'X-GatePay-Nonce: 2290830087' \
--header 'X-GatePay-Signature: 601d560c54d53412aca5901256f101e7078b5779f61f30bedfe9a5f0b92f049589952a151ea477371e4a99ac0e1c3cc8dec62654b3c6a1794ef981efe19232bc' \
--data '{
    "batch_id":"237394559478075555",
    "detail_status":"ALL"
}'

    响应实例:

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "batch_id": "237394559478075350",
        "merchant_id": 10002,
        "client_id": "mZ96D37oKk-HrWJc",
        "status": "FAIL",
        "create_time": 1726055849126,
        "channel_id": "123456",
        "withdraw_list": [
            {
                "id": 35,
                "batch_id": "237394559478075350",
                "merchant_id": 10002,
                "suborder_id": "268830764354768896",
                "chain": "ETH",
                "address": "0x1234567890abcdef",
                "currency": "USDT",
                "amount": "1",
                "fee": "0",
                "tx_id": "",
                "timestamp": 0,
                "memo": "Payment for services-1",
                "status": "FAIL",
                "merchant_withdraw_id": "M137394559478075550",
                "err_msg": "unexpected http code error",
                "client_id": "mZ96D37oKk-HrWJc",
                "create_time": 1726055848856,
                "update_time": 1726055856011,
                "channel_id": "123456",
                "fee_type": 1,
                "done_amount": "1"
            },
            {
                "id": 36,
                "batch_id": "237394559478075350",
                "merchant_id": 10002,
                "suborder_id": "268830764354768897",
                "chain": "ETH",
                "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
                "currency": "USDT",
                "amount": "0.001",
                "fee": "0",
                "tx_id": "",
                "timestamp": 0,
                "memo": "Payment for services-1",
                "status": "FAIL",
                "merchant_withdraw_id": "M137394559478075551",
                "err_msg": "unexpected http code error",
                "client_id": "mZ96D37oKk-HrWJc",
                "create_time": 1726055848856,
                "update_time": 1726055856010,
                "channel_id": "123456",
                "fee_type": 1,
                "done_amount": "0.001"
            }
        ]
    }
}

    batch_id不存在返回空

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "batch_id": "237394559478075358",
        "merchant_id": 0,
        "client_id": "",
        "status": "",
        "create_time": 0,
        "withdraw_list": []
    }
}

    # 3.3 查询币种支持的链

    • 数据类型：JSON （content-type：application/json）

    • 请求⽅式：GET

    • 路径Path: /v1/pay/wallet/currency_chains

    • 验证方式：无

    • 请求体内容:

      字段名 类型 是否必须 说明
      currency string 是 指定币种名称查询

    • 返回格式:

      状态码 200

    字段名 类型 是否必须 说明
    chain string 是 区块链网络名称（如ERC20、TRC20、BEP20等）
    name_cn string 是 区块链网络中文名称（如以太坊、波场等）
    name_en string 是 区块链网络英文名称（如Ethereum、Tron等）
    contract_address string 是 币种智能合约地址（原生币如BTC、ETH主网币为空字符串）
    is_disabled integer(int32) 是 全局禁用状态：
    0-启用
    1-禁用
    is_deposit_disabled integer(int32) 是 充值功能状态：
    0-启用
    1-禁用
    is_withdraw_disabled integer(int32) 是 提现功能状态：
    0-启用
    1-禁用
    decimal string 是 提币精度（小数点位数，如BTC为"6"）

    示例代码

    # coding: utf-8
import requests

host = "https://openplatform.gateapi.io/"
prefix = "/v1/pay"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/currency_chains'
query_param = 'currency=GT'
r = requests.request('GET', host + prefix + url + "?" + query_param, headers=headers)
print(r.json())

    返回示例

    200 返回

    [
  {
    "chain": "ETH",
    "name_cn": "以太坊ERC20",
    "name_en": "ETH/ERC20",
    "contract_address": "",
    "is_disabled": 0,
    "is_deposit_disabled": 0,
    "is_withdraw_disabled": 0
  }
]

    # 3.4 查询个人账户总额

    • 数据类型：JSON （content-type：application/json）

    • 请求⽅式：GET

    • 路径Path: /v1/pay/wallet/total_balance

    • 验证方式：签名验证

    • 请求体内容:

      字段名 类型 是否必须 说明
      currency string 是 指定币种名称查询

    • 返回格式:

      状态码 200

    字段名 类型 是否必须 说明
    total object 是 换算成目标币种的账户总额汇总
    › amount string 是 账户总额数字
    › currency string 是 目标币种
    › unrealised_pnl string 否 未实现盈亏总和（仅futures/options/delivery/total账户出现）
    › borrowed string 否 杠杆借贷总和（仅margin/cross_margin账户出现）
    details object 是 各账户类型明细
    › account_type object 是 账户类型键名（见下方账户类型说明）
    ›› amount string 是 该账户类型总额数字
    ›› currency string 是 目标币种
    ›› unrealised_pnl string 否 未实现盈亏（仅futures/options/delivery/total账户出现）
    ›› borrowed string 否 杠杆借贷（仅margin/cross_margin账户出现）

    请求示例:

    # coding: utf-8
import requests
import time
import hashlib
import hmac
import math
import random

host = "https://openplatform.gateapi.io/"
prefix = "/v1/pay"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/total_balance'
query_param = ''

sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

    返回示例:

    {
  "details": {
    "cross_margin": {
      "amount": "0",
      "currency": "USDT"
    },
    "spot": {
      "currency": "USDT",
      "amount": "42264489969935775.5160259954878034182418"
    },
    "finance": {
      "amount": "662714381.70310327810191647181",
      "currency": "USDT"
    },
    "margin": {
      "amount": "1259175.664137668554329559",
      "currency": "USDT",
      "borrowed": "0.00"
    },
    "quant": {
      "amount": "591702859674467879.6488202650892478553852",
      "currency": "USDT"
    },
    "futures": {
      "amount": "2384175.5606114082065",
      "currency": "USDT",
      "unrealised_pnl": "0.00"
    },
    "delivery": {
      "currency": "USDT",
      "amount": "1519804.9756702",
      "unrealised_pnl": "0.00"
    },
    "warrant": {
      "amount": "0",
      "currency": "USDT"
    },
    "cbbc": {
      "currency": "USDT",
      "amount": "0"
    }
  },
  "total": {
    "currency": "USDT",
    "amount": "633967350312281193.068368815439797304437",
    "unrealised_pnl": "0.00",
    "borrowed": "0.00"
  }
}

    # 3.5 查询提现状态

    • 数据类型：JSON （content-type：application/json）

    • 请求⽅式：GET

    • 路径Path: /v1/pay/wallet/withdraw_status

    • 验证方式：签名验证

    • 请求体内容:

      字段名 类型 是否必须 说明
      currency string 是 指定币种名称查询

    • 返回格式:

      状态码 200

    字段名 类型 是否必须 说明
    currency string 是 币种，例如：BTC, ETH
    name string 是 币种名称，例如：Bitcoin, Ethereum
    name_cn string 是 币种中文名称，例如：比特币，以太坊
    deposit string 是 充值手续费，通常为0，但这里用字符串表示，例如："0"
    withdraw_percent string 是 提现手续费率百分比，例如："0.1" 表示0.1%
    withdraw_fix string 是 固定提现手续费用，例如："0.0005"
    withdraw_day_limit string 是 日提现额度（该币种当天最大可提现总额）
    withdraw_amount_mini string 是 最少提现额度（单次提现不能低于这个值）
    withdraw_day_limit_remain string 否 剩余日提现额度（当天还能提现的总额）
    withdraw_eachtime_limit string 是 单次最多提现额度（单次提现不能超过这个值）
    withdraw_fix_on_chains object 否 多链的固定提现手续费用，对象属性为链的名称，值为固定费用字符串
    withdraw_percent_on_chains object 否 多链的百分比提现手续费用，对象属性为链的名称，值为百分比字符串

    • 调用「查询提现状态」这个接口,会返回币种支持链所需要的手续费。选取需要的链就好:

    • 参考下面这俩参数:

      「withdraw_fix_on_chains」 是固定手续费 「withdraw_percent_on_chains」是百分比提现手续费用(有些特殊币种提现的时候需要用提现数量x这个百分比)

    • 提现手续费就是这两部分相加:固定费用+百分比费率*提现数量

    • 现在常用的链基本上只有这个固定费用(这里的固定费用是每小时更新的)

    • 每次提现的时候,都需要调用下这个接口,确认下手续费。手续费是每小时更新的。

    请求示例:

    import requests
import time
import hashlib
import hmac
import math
import random

host = "https://openplatform.gateapi.io/"
prefix = "/v1/pay"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/withdraw_status'
query_param = ''

nonce = math.floor(((random.random() * 9 + 1) * 1000000000))
secret = ""

sign_headers = generate_signature(str(int(time.time()*1000)),nonce,"",secret)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())```

    响应:

    [
  {
    "currency": "GT",
    "name": "GateToken",
    "name_cn": "GateToken",
    "deposit": "0",
    "withdraw_percent": "0%",
    "withdraw_fix": "0.01",
    "withdraw_day_limit": "20000",
    "withdraw_day_limit_remain": "20000",
    "withdraw_amount_mini": "0.11",
    "withdraw_eachtime_limit": "20000",
    "withdraw_fix_on_chains": {
      "BTC": "20",
      "ETH": "15",
      "TRX": "0",
      "EOS": "2.5"
    },
    "withdraw_percent_on_chains": {
      "ETH": "0%",
      "GTEVM": "0%"
    }
  }
]

    # 3.6 提现记录

    • 数据类型：JSON （content-type：application/json）

    • 请求⽅式：GET

    • 路径Path: /v1/pay/wallet/withdrawals

    • 验证方式：签名验证

    • 请求体内容:

      字段名 类型 是否必须 说明
      currency string 否 指定查询币种，不指定返回全部币种
      withdraw_id string 否 提现记录id，以w开头（如：w1879219868），指定时只查询该条记录
      asset_class string 否 币种类型（主区/创新区），默认为空
      withdraw_order_id string 否 用户自定义提现单号，查询指定自定义单号的记录
      from integer(int64) 否 查询起始时间（Unix时间戳）单位为秒，默认7天内
      to integer(int64) 否 查询结束时间（Unix时间戳）单位为秒，默认当前时间
      limit integer 否 返回记录的最大数量
      offset integer 否 返回记录的偏移量（从0开始）

      记录查询时间范围不允许超过 30 天

      详细描述:

          asset_class: 提现记录币种类型，默认为空。即支持用户按需查询主区和创新区的提现记录。 取值范围：SPOT、PILOT
    SPOT ： 主区
    PILOT： 创新区

    • 返回格式:

      状态码 200

    字段名 类型 说明
    id string 交易记录 ID
    txid string 区块转账哈希记录
    block_number string 区块编号
    withdraw_order_id string 用户端订单编号,最长32个，输入内容只能包含数字、字母、下划线(_)、中划线(-) 或者点(.)
    timestamp string 操作时间
    amount string 币的数量
    fee string 手续费
    currency string 币种名称
    address string 提现地址
    fail_reason string 提现失败原因，当 status = CANCEL时有值，其余状态时为空
    timestamp2 string 提现终态时间，即： 提现取消时间或提现成功时间
    当 status = CANCEL 时，对应 取消时间
    当 status = DONE 且block_number > 0 时，为提现成功时间
    memo string 转账memo等备注信息
    status string 交易状态
    - DONE: 完成 (block_number > 0 才算真的上链完成)
    - CANCEL: 已取消
    - REQUEST: 请求中
    - MANUAL: 待人工审核
    - BCODE: 充值码操作
    - EXTPEND: 已经发送等待确认
    - FAIL: 链上失败等待确认
    - INVALID: 无效订单
    - VERIFY: 验证中
    - PROCES: 处理中
    - PEND: 处理中
    - DMOVE: 待人工审核
    - REVIEW: 审核中
    chain string 提现的链名称

    请求:

    # coding: utf-8
import requests
import time
import hashlib
import hmac

host = "https://openplatform.gateapi.io"
prefix = "/v1/pay"
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}

url = '/wallet/withdrawals'
query_param = ''

sign_headers = gen_sign('GET', prefix + url, query_param)
headers.update(sign_headers)
r = requests.request('GET', host + prefix + url, headers=headers)
print(r.json())

    响应:

    [
  [
    {
      "id": "w1879219868",
      "currency": "USDT",
      "address": "THISISTESTADDRESSFORGATEPAY",
      "amount": "4.023",
      "fee": "0",
      "txid": "Internal transaction 260594131",
      "chain": "BSC",
      "timestamp": "1745220149",
      "status": "DONE",
      "withdraw_order_id": "202504211521368538928",
      "block_number": "1000",
      "fail_reason": "",
      "type": "appbankgp",
      "timestamp2": "1745220149",
      "memo": ""
    }
  ]
]

    # 3.7 回调通知

    提现单回调通知字段：

    字段名 类型 说明
    main_order 对象结构 主提现单信息描述
    suborders 数组 子订单信息描述

    # 3.7.1 回调

    # 主订单

    字段名 类型 是否必须 说明
    batch_id string 是 批次ID
    merchant_id integer 是 商户ID
    status string 是 订单状态
    client_id string 是 创建订单的商户client_id
    pay_back_status string 是 回退状态
    channel_id string 是 客户名称

    # 子订单

    字段名 类型 是否必须 说明
    merchant_id integer 是 商户ID
    channel_id string 是 客户名称
    suborder_id string 是 子订单ID
    chain string 是 区块链网络
    address string 是 收款地址
    currency string 是 币种
    amount string 是 转账金额
    fee string 是 手续费
    tx_id string 是 交易哈希
    memo string 是 备注
    status string 是 状态(DONE) (FAIL)
    merchant_withdraw_id string 是 商户提现ID
    fee_type integer 是 手续费类型 0-提现数量包含手续费,1-提现数量为实际到账数量
    batch_withdraw_id string 是 批量提现ID
    desc string 是 描述
    reconciliation_status integer 是 对账状态
    is_placed integer 是 是否已处理 0-未提交，1-已提交
    finish_time integer 是 完成时间
    sub_amount string 是 子订单总金额
    done_amount string 是 实际完成金额

    回调示例:

    {
  "main_order": {
    "batch_id": "831618381568",
    "merchant_id": 17329983,
    "status": "SUCCESS",
    "client_id": "igasgasdbub",
    "pay_back_status": "NO",
    "channel_id": ""
  },
  "suborders": [
    {
      "merchant_id": 130559,
      "channel_id": "",
      "suborder_id": "30969031299072",
      "chain": "TRX",
      "address": "QBTW9qTMQBTW9qnoeMMmUxaAWEqVDDUgUw",
      "currency": "USDT",
      "amount": "2362.1",
      "fee": "1",
      "tx_id": "aaa33e642d6fb6e3272ae3c21c60f1248d1cd7ccdc000458308d690699",
      "memo": "",
      "status": "DONE",
      "merchant_withdraw_id": "1839295815",
      "fee_type": 1,
      "batch_withdraw_id": "",
      "desc": "",
      "reconciliation_status": 0,
      "is_placed": 1,
      "finish_time": 1748581414000,
      "sub_amount": "2363.1",
      "done_amount": "2362.1"
    }
  ]
}

    # 4.商户批量提现常见错误码

    http状态码 错误码 descriptions 描述
    200 550233 Insufficient withdrawal balance. 提现划转余额不足
    200 550234 Memo exceeds length limit. 提现memo超过长度限制
    200 550235 The minimum precision limit of the withdrawal currency, the precision can not be less than 6 decimal places 提现币种最小精度限制,精度不能小于小数点6位
    200 550236 The user does not have withdrawal permissions. 当前提现用户无权限,可联系运营人员申请开通
    200 550237 Failure to transfer. 提现划转失败
    200 550238 The number of withdrawals exceeds the limit of {xx} 提现子单数量超限制
    200 550239 amount is required. 提现金额不能为空
    200 550240 currency is required. 提现币种不能为空
    200 550241 address is required. 提现地址不能为空
    200 550242 chain is required. 提现链名不能为空
    200 550243 withdraw_order_id is required. 子单withdraw_order_id参数不能为空
    200 550244 batch_id is required. batch_id不能为空
    200 550245 batch_id duplicates batch_id重复
    200 550246 currency withdrawals are not supported yet. 不支持的币种提现
    200 550247 Incorrect state parameters. 提现查询接口状态参数不合法
    200 550248 Sub-order parameter error. 子订单参数错误
    200 550249 Invalid merchant order id. batch_id,或者withdraw_order_id参数不合法
    200 550251 Fee type invalid fee_type参数不合法
    Last Updated: 6/11/2025, 9:38:28 AM