# 1. 功能介绍

    ​ OTC提币支持商户先进行数字货币和法币间询价，询价后将所持有的数字货币通过 OTC 方式卖出，并将结算后的法币出金至指定的银行账户。仅限Gate Pay商户调用。

    # 2. API 接口

    # 2.1 询价

    • API描述：商户创建法币出金订单前,需先询价并获取可执行报价和有效期；在有效期内,报价token将锁定汇率、金额、币种；报价成功后,需要在有效期内使用报价token执行报价并创建订单

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

    • 请求方式：POST

    • 路径Path: /withdraw/open/otc/api/v1/quote

    • 验证方式：签名验证

    • 请求体内容:

    字段名 类型 是否必须 说明
    cryptoCurrency string 是 数字货币币种 当前仅支持：USDT
    fiatCurrency string 是 法币币种 当前仅支持：USD
    cryptoAmount string 否 数字货币数量,side为CRYPTO时必传
    fiatAmount string 否 法币数量, side为FIAT时必传
    side string 是 询价方向 CRYPTO：以数字货币为基准询价，此时cryptoAmount必传； FIAT：以法币为基准询价，此时fiatAmount必传
    promotionCode string 否 优惠码
    type string 是 BUY:入金, SELL:出金 本期仅支持SELL
    • 响应内容:
    字段名 类型 说明
    cryptoCurrency string 数字货币币种
    fiatCurrency string 法币币种
    cryptoAmount string 数字货币数量
    fiatAmount string 法币数量
    fiatRate string 法币汇率 法币/数字货币
    cryptoRate string 数字货币汇率 数字货币/法币
    validPeriod integer 询价有效期,单位：秒
    quoteToken string 询价token,下单使用

    CURL 请求

    curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/otc/api/v1/quote' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769588949' \
--header 'x-GatePay-Nonce: 2730095202' \
--header 'x-GatePay-Signature: 7f780aa07e120dda16f0b0139e86a32ebe9833f10b3bf75fafc55dea46658e14a3f18078fa45ecfd9b81b4edf2c0bc91d1d9dc9ca4de5eed3189437f8e31fd69' \
--header 'Content-Type: application/json' \
--data-raw '{
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "1000",
    "side": "CRYPTO",
    "type": "SELL"
}'

    响应:

    {
  "code": "",
  "data": {
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "10000",
    "fiatAmount": "9898.72",
    "fiatRate": "0.989872",
    "cryptoRate": "1.01023613",
    "validPeriod": 300,
    "quoteToken": "adhk543"
  },
  "status": "",
  "label": "",
  "errorMessage": ""
}

    # 2.2 下单

    • API描述：获取报价后,需要在有效期内执行报价并创建法币出金订单

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

    • 请求方式：POST

    • 路径Path: /withdraw/open/otc/api/order/create

    • 验证方式：签名验证

    • 请求体内容:

    字段名 类型 是否必须 说明
    quoteToken string 是 询价token
    bankAccountId string 是 银行账户ID
    cryptoCurrency string 是 数字货币币种
    fiatCurrency string 是 法币币种
    cryptoAmount string 是 数字货币数量
    fiatAmount string 是 法币数量
    type string 是 BUY:入金, SELL:出金 本期仅支持SELL
    clientOrderId string 是 商户订单号,下单失败需要变更单号
    • 响应内容:
    字段名 类型 说明
    orderId string 订单ID
    status string 订单状态
    createTime interger 创建时间
    createTime interger 创建时间
    clientOrderId string 商户订单号

    CURL 请求

    curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/otc/api/order/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769669668127' \
--header 'x-GatePay-Nonce: 7508857261' \
--header 'x-GatePay-Signature: 9636bd4c3edac24af5ea2b410c38aa0bafc7e73d6333158205a3f3652cfd97e2a94e38a259a057bee565889b1c686a22b03943a196c19d1eaa43ecb5a045cec1' \
--data-raw '{
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "10000",
    "fiatAmount": "9800",
    "type": "SELL",
    "quoteToken": "qdfh34543",
    "bankAccountId": "2897434",
    "clientOrderId": "7490324045"
}'

    响应:

    {
  "code": "000000",
  "data": {
    "orderId": "2016768770965639168",
    "status": "PROCESSING",
    "createTime": 1769670119407,
    "clientOrderId": "7490324045"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

    # 2.3 查询订单详情

    • API描述：执行报价并创建订单后,可以根据返回的订单ID单笔查询订单状态及相关信息

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

    • 请求方式：GET

    • 路径Path: /withdraw/open/otc/api/order/detail

    • 验证方式：签名验证

    • 请求体内容:

    字段名 类型 是否必须 说明
    orderId string 否 订单ID,商户订单号为空时必填
    clientOrderId string 否 商户订单号,订单ID为空时必填
    • 响应内容:
    字段名 类型 说明
    orderId string 订单ID
    status string 订单状态 PROCESSING：处理中、FAIL 失败、DONE 成功、DISPATCHED：已出款
    cryptoCurrency string 数字货币币种
    fiatCurrency string 法币币种
    type string BUY:入金, SELL:出金
    cryptoAmount string 数字货币数量
    fiatAmount string 法币数量
    fiatRate string 法币汇率 法币/数字货币
    bankAccountId string 银行账户ID
    createTime integer 创建时间
    updateTime integer 更新时间
    clientOrderId string 商户订单号
    errMsg string 错误原因
    tradeFee string 手续费(币种同fiatCurrency)
    finalFiatAmount string 实际到账金额(币种同fiatCurrency)

    CURL 请求

    curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/otc/api/order/detail?orderId=35599620284481595' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769670845426' \
--header 'x-GatePay-Nonce: 9099836565' \
--header 'x-GatePay-Signature: 3eef45b012cf9710eb06587775f5fc2807b7445fb0fdd3c830cf453ee07b34824c0b4bf187a1ad783f886c592b04da7b0ab5d8bf47b8741c82bd408db7b811b4' \

    响应:

    {
  "code": "000000",
  "data": {
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "100000",
    "fiatAmount": "99810.08",
    "orderId": "35599620284481595",
    "status": "DONE",
    "createTime": 1761205415973,
    "updateTime": 1761205416189,
    "bankAccountId": "123141284812832183",
    "type": "SELL",
    "fiatRate": "0.9981",
    "clientOrderId": "7490324045"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

    # 2.4 查询订单列表

    • API描述：执行报价并创建订单后,可以根据返回的订单ID批量查询订单状态及相关信息

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

    • 请求方式：POST

    • 路径Path: /withdraw/open/otc/api/order/list

    • 验证方式：签名验证

    • 请求体内容:

    字段名 类型 是否必须 说明
    status string 否 订单状态 PROCESSING：处理中、FAIL 失败、DONE 成功、DISPATCHED：已出款
    type string 否 BUY:入金, SELL:出金
    cryptoCurrency string 否 数字货币币种
    fiatCurrency string 否 法币币种
    startTime string 否 创建时间起
    endTime string 否 创建时间止
    page integer 否 页码,默认第1页
    pageSize integer 否 每页数量,默认10条,最大500条
    clientOrderId string 否 商户订单号
    • 响应内容:
    字段名 类型 说明
    data array 订单列表
    data[].order_id string 订单ID
    data[].status string 订单状态 PROCESSING：处理中、FAIL 失败、DONE 成功、DISPATCHED：已出款
    data[].cryptoCurrency string 数字货币币种
    data[].fiatCurrency string 法币币种
    data[].bankAccountId string 银行账户ID
    data[].cryptoAmount string 数字货币数量
    data[].fiatAmount string 法币数量
    data[].fiatRate string 法币汇率 法币/数字货币
    data[].createTime integer 创建时间
    data[].updateTime integer 更新时间
    data[].type string BUY:入金 SELL:出金
    data[].clientOrderId string 商户订单号
    data[].errMsg string 失败原因
    data[].tradeFee string 手续费(币种同fiatCurrency)
    data[].finalFiatAmount string 实际到账金额(币种同fiatCurrency)
    page integer 当前页
    pageSize integer 每页数量
    total integer 总条数

    CURL 请求

    curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/otc/api/order/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \
--data-raw '{
    "page": 1,
    "pageSize": 10
}'

    响应:

    {
  "code": "000000",
  "data": {
    "page": 1,
    "pageSize": 10,
    "total": 49,
    "data": [
      {
        "cryptoCurrency": "USDT",
        "fiatCurrency": "USD",
        "cryptoAmount": "10000",
        "fiatAmount": "99810.08",
        "orderId": "2016769960466059264",
        "status": "DONE",
        "createTime": 1769670404763,
        "updateTime": 1769670720469,
        "type": "SELL",
        "bankAccountId": "2897434",
        "fiatRate": "0.9981",
        "clientOrderId": "980932432"
      },
      {
        "cryptoCurrency": "USDT",
        "fiatCurrency": "USD",
        "cryptoAmount": "10000",
        "fiatAmount": "99810.08",
        "orderId": "2016768770965639168",
        "status": "DONE",
        "createTime": 1769670119407,
        "updateTime": 1769670300606,
        "type": "SELL",
        "bankAccountId": "2897434",
        "fiatRate": "0.9981",
        "clientOrderId": "980932433"
      }
    ]
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

    # 2.5 查询银行账户可选国家列表

    • API描述：如需要添加银行账户，可以先查询添加银行账户可选的国家列表信息

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

    • 请求方式：GET

    • 路径Path: /withdraw/open/otc/api/bank/country/list

    • 验证方式：签名验证

    • 请求体内容:

    • 响应内容:

    字段名 类型 说明
    data array 国家列表
    data[].countryId int 国家id
    data[].countryName string 国家名称
    data[].countryCn string 国家名称中文

    CURL 请求

    curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/otc/api/bank/country/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \

    响应:

    {
  "code": "000000",
  "data": [
    {
      "countryId": 260,
      "countryCn": "阿富汗",
      "countryName": "Afghanistan"
    },
    {
      "countryId": 3,
      "countryCn": "阿尔巴尼亚",
      "countryName": "Albania"
    },
    {
      "countryId": 4,
      "countryCn": "阿尔及利亚",
      "countryName": "Algeria"
    }
  ],
  "status": "SUCCESS",
  "errorMessage": ""
}

    # 2.6 创建银行账户

    • API描述：OTC法币出金时需要新增银行账户；新增银行账户时，需要同时上传银行对账单文件

    • 数据类型：JSON （content-type：multipart/form-data）

    • 请求方式：POST

    • 路径Path: /withdraw/open/otc/api/bank/create

    • 验证方式：签名验证

    • 请求体内容:

    字段名 类型 是否必须 说明
    bankAccountName string 是 银行账户名称
    bankName string 是 银行名称
    countryId int 是 国家ID
    address string 是 银行地址
    iban string 是 账号/IBAN
    swift string 是 swift
    remittanceLineNumber string 否 路由/清算代码
    agentBankName string 否 代理银行名称
    agentBankSwift string 否 代理银行swift
    file file 是 文件不超过4MB,只允许jpg、jpeg、png;3个月内出具的银行对账单，银行账户名称必须与身份认证的姓名完全一致，若因语种等原因导致差异，请提供相关证明（比如银行证明文件、护照、政府更名回执等）
    • 响应内容:
    字段名 类型 说明
    bankAccountId string 银行账户ID

    CURL 请求

    curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/otc/api/bank/create' \
--header 'X-GatePay-MerchantId;' \
--form 'bankAccountName="bank001"' \
--form 'bankName="bankName01"' \
--form 'countryId="260"' \
--form 'address="123"' \
--form 'iban="123213213"' \
--form 'swift="21321"' \
--form 'remittanceLineNumber="312"' \
--form 'agentBankName="213"' \
--form 'agentBankSwift="454"' \
--form 'file=@"/Downloads/bank.jpg"'

    响应:

    {
  "code": "000000",
  "data": {
    "bankAccountId": "2897434"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

    # 2.7 查询银行账户列表

    • API描述：支持查询已绑定的银行账户信息，查询后返回商户全量银行账户信息

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

    • 请求方式：GET

    • 路径Path: /withdraw/open/otc/api/bank/list

    • 验证方式：签名验证

    • 请求体内容: (模糊查询)

    字段名 类型 是否必须 说明
    bankAccountName string 否 银行账户名称
    iban string 否 账号/IBAN
    swift string 否 swift
    bankName string 否 银行名称
    • 响应内容:
    字段名 类型 说明
    data array 列表
    data[].bankAccountId string 银行账户ID
    data[].bankAccountName string 银行账户名称
    data[].bankName string 银行名称
    data[].countryId int 国家ID
    data[].countryName string 国家名称
    data[].address string 银行地址
    data[].iban string 账号/IBAN
    data[].swift string swift
    data[].remittanceLineNumber string 路由/清算代码
    data[].agentBankName string 代理银行名称
    data[].agentBankSwift string 代理银行swift

    CURL 请求

    curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/otc/api/bank/list?bankAccountName=bank001&bankName=bankName01&iban=123213213&swift=21321' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \

    响应:

    {
  "code": "000000",
  "data": [
    {
      "bankAccountId": 501,
      "bankAccountName": "12312",
      "bankName": "123123",
      "countryId": 260,
      "countryName": "Afghanistan",
      "address": "123123",
      "iban": "12313123",
      "swift": "123132123",
      "remittanceLineNumber": "3123123",
      "agentBankName": "",
      "agentBankSwift": ""
    },
    {
      "bankAccountId": 642,
      "bankAccountName": "testname",
      "bankName": "123123",
      "countryId": 11,
      "countryName": "Australia",
      "address": "123123",
      "iban": "UYTU****GFHG",
      "swift": "13123",
      "remittanceLineNumber": "1231",
      "agentBankName": "",
      "agentBankSwift": ""
    }
  ],
  "status": "SUCCESS",
  "errorMessage": ""
}

    # 2.8 删除银行账户

    • API描述：支持删除指定银行账户信息

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

    • 请求方式：POST

    • 路径Path: /withdraw/open/otc/api/bank/delete

    • 验证方式：签名验证

    • 请求体内容:

      字段名 类型 是否必须 说明
      bankAccountId string 是 银行账户ID

    • 响应内容:

    CURL 请求

    curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/otc/api/bank/delete' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \
--data-raw '{
    "bankAccountId": 796
}'

    响应:

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

    # 3. 订单状态异步通知

    # 3.1 订单状态变更异步通知

    1. 在OTC订单状态发生改变时，如提现成功，提现失败等操作，GatePay后台会向商户发送订单状态通知。通知地址是商户注册时提供的callback url参数。

    2. 如果由于网络或者其他未知原因导致通知失败，GatePay 后台会在 15 秒 / 30 秒 / 3 分钟 / 10 分钟 / 20 分钟 / 30 分钟 / 60 分钟 / 3 小时 / 6 小时后进行重试，如果重试也失败，商户可以通过调用订单查询接口获取订单状态。

    3. 商户接受到的异步通知信息，必须校验消息签名参数来验证消息合法性。参考接口签名

    # 3.2 消息结构

    字段名 类型 说明
    bizType string 通知类别， 固定值：OTC
    bizId string 订单ID
    bizStatus string 通知状态，WITHDRAW_SUCCESS(提现成功)，WITHDRAW_FAIL(提现失败)，WITHDRAW_DISPATCHED(已出款)
    clientId string 创建订单的商户clientId
    data string 消息内容

    消息结构示例:

    {
    "bizType":"OTC",
    "bizId":"6948484859590",
    "bizStatus":"WITHDRAW_SUCCESS",
    "clientId":"cdhu-fgrfg44-5ggd-cdvsa",
    "data":"{...Json格式数据...}"
}

    商户在收到异步回调消息后，需响应成功收到消息，消息结构示例:

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

    # 3.3 Data结构

    字段名 类型 说明
    orderId string 订单ID
    clientOrderId string 商户订单号
    fiatRate string 法币汇率 法币/数字货币
    type string BUY:入金, SELL:出金 本期仅支持SELL
    fiatCurrency string 法币币种
    fiatAmount string 法币数量
    cryptoCurrency string 数字货币币种
    cryptoAmount string 数字货币数量
    updateTime string 更新时间
    errMsg string 失败原因
    tradeFee string 手续费(币种同fiatCurrency)
    finalFiatAmount string 实际到账金额(币种同fiatCurrency)

    # 4. 错误码

    错误码 描述 解决方案
    400001 无效请求参数 检查请求参数是否合法
    400002 签名校验失败 检查商户签名是否正确
    400003 请求时间戳超时 检查请求head里的时间戳字段
    400004 API身份秘钥不存在或无效 检查API身份密钥是否存在或有效
    400611 余额不足 检查余额
    550175 查询订单不存在 请检查订单是否发起过交易或订单号是否正确
    5503001 接口限频 稍后重试
    5502961 用户所属国家无法提供服务 检查用户所属国家是否允许
    5502971 用户不符合otc交易资格 检查用户otc资格
    5502761 下单商户订单号重复 更换商户订单号
    550018 风控拒绝 稍后重试
    550301 用户未完成Global OTC相关认证 -
    550302 用户未完成个人OTC专业认证申请 -
    550303 用户未完成企业OTC专业认证申请 -
    550304 用户OTC专业认证申请被驳回 -
    550305 用户OTC专业认证被冻结 -
    550306 用户专业认证审核中 -
    550307 用户交易额度不足，需要进行提额申请 -
    550308 用户提额申请审核中 -
    550309 提额申请拒绝，需要重新进行申请 -
    550310 用户未绑定银行账户 请绑定银行账户后重试
    550311 当前操作受限，请联系客服处理 -
    550312 币种禁止提现 -
    550313 询价过期 请重新询价并使用新的token下单
    550314 幂等校验失败 -
    550315 询价金额限制 请调整询价金额，详情可联系客服确认
    550316 创建银行账户失败 -
    550317 删除银行账户失败 -
    550318 优惠码无效 请更换有效优惠码
    Last Updated: 4/9/2026, 2:05:54 PM