NAV
go php js java

提现

提现申请

请求示例:

POST <base_path>/v2/transfer HTTP/1.1
Host: api.xxxx.com
Content-Type: application/json
X-Cbc-App-Id: hxgmau9imt86qky9
X-Cbc-Key-Version: admin
X-Cbc-Timestamp: 1792382460
X-Cbc-Nonce: 7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>

{"user_id":"0","coin":"hc","address":"HsRDEePh7WBCsdJPfo1UsjfurwLBU6HD5Vi","amount":"0.02","trade_id":"20200114202903274786"}

resp, err := client.Post("/v2/transfer", map[string]any{
    "user_id":  "0",
    "coin":     "hc",
    "address":  "HsRDEePh7WBCsdJPfo1UsjfurwLBU6HD5Vi",
    "amount":   "0.02",
    "trade_id": "20200114202903274786",
})
$resp = $client->post('/v2/transfer', [
    'user_id' => '0',
    'coin' => 'hc',
    'address' => 'HsRDEePh7WBCsdJPfo1UsjfurwLBU6HD5Vi',
    'amount' => '0.02',
    'trade_id' => '20200114202903274786',
]);
const resp = await client.post('/v2/transfer', {
  user_id: '0',
  coin: 'hc',
  address: 'HsRDEePh7WBCsdJPfo1UsjfurwLBU6HD5Vi',
  amount: '0.02',
  trade_id: '20200114202903274786',
});
String resp = client.post("/v2/transfer", Map.of(
        "user_id", "0",
        "coin", "hc",
        "address", "HsRDEePh7WBCsdJPfo1UsjfurwLBU6HD5Vi",
        "amount", "0.02",
        "trade_id", "20200114202903274786"));

返回结果示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: 4bf92f3577b34da6a3ce929d0e0e4736
X-Cbc-Timestamp: 1792382461
X-Cbc-Nonce: 3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>

{ "status":200, "msg":"请求成功", "data":{ "trade_id":"20200114005026028784" }, "date_time":"2020-01-14 00:50:27" }

商户发起链上提币,请求此接口 开通提现功能时 ,同时需要提供 风控接口(见:风控回调api -> 商户提现订单二次复核)

HTTP Request

POST /v2/transfer

请求参数

公共 Header 见签名规则,下表只列 body 中的业务参数。

参数名 必选 类型 说明
user_id 否 string 用户ID,字母、数字和下划线组成,长度40以内
coin 是 string 币种简称-平台约定为准
amount 是 string 提现数量,超范围会出错
address 是 string 收款地址,超范围会出错
memo 否 string memo/tag 当前币为 eos及其代币时需要填写
trade_id 是 string 商户端交易唯一ID(建议格式:年月日时分秒+6位随机数案列:20200311202903000001)

返回参数说明

参数名 类型 说明
status integer 状态码
msg string 状态描述
data object trade_id-由商户提供
data.trade_id string 商户端交易唯一ID
date_time string 响应时间
time_stamp integer 无时区的秒

提现列表

请求示例:

POST <base_path>/v2/transfer/list HTTP/1.1
Host: api.xxxx.com
Content-Type: application/json
X-Cbc-App-Id: hxgmau9imt86qky9
X-Cbc-Key-Version: admin
X-Cbc-Timestamp: 1792382460
X-Cbc-Nonce: 7c1e9a3b5d7f9b1d3f5a7c9e1b3d5f7a
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>

{"page":1}
resp, err := client.Post("/v2/transfer/list", map[string]any{
    "page": 1,
})
$resp = $client->post('/v2/transfer/list', [
    'page' => 1,
]);
const resp = await client.post('/v2/transfer/list', {
  page: 1,
});
String resp = client.post("/v2/transfer/list", Map.of("page", 1));

返回结果示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: 4bf92f3577b34da6a3ce929d0e0e4736
X-Cbc-Timestamp: 1792382461
X-Cbc-Nonce: 3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>

{
  "status": 200,
  "msg": "处理成功",
  "data": {
    "page": 1,
    "max_page": 1,
    "count": 1,
    "list": [{
      "trade_id": "20200114202903274786",
      "coin": "hc",
      "chain": "hc",
      "txid": "",
      "amount": "0.02",
      "fee": "0",
      "total": "0.02",
      "address": "HsRDEePh7WBCsdJPfo1UsjfurwLBU6HD5Vi",
      "from_address": "the transaction from address",
      "status": "2",
      "time": "1658482253",
      "type": "2",
      "gas_fee": "0.1"
    }]
  },
  "date_time": "2022-07-22 18:36:36",
  "time_stamp": 1658486196
}

通过此接口查询查询订单状态情况,可以只查一个,也可以模糊查询多个。

HTTP Request

POST /v2/transfer/list

请求参数

公共 Header 见签名规则,下表只列 body 中的业务参数。

参数名 必选 类型 说明
trade_id 否 string 如果传trade_id为精准查找,下面参数失效
coin 否 string 币名,按币种筛选
page 否 integer 1<= N <=Max,对于超过Max的取Max,小于1或没有传参数的返回1
status 否 integer 0 待审核 1 提现成功、2 等待风控处理中、5 等待出币、10 审核不通过、20 转账失败
start_time 否 integer 开始时间(创建时间) 格式 :时间戳
end_time 否 integer 结束时间(创建时间) 格式 :时间戳
page_size 否 integer 每页数量 (20 ~100),默认 20
sort_num 否 integer 列表排序规则 默认按入系统时间正序排列( 1 正序 ; 2 倒序)

返回参数说明

参数名 类型 说明
status integer 状态码
msg string 状态描述
data object trade_id-由商户提供
data.page integer 第几页
data.count integer 本页记录数
data.list array 具体每条记录
data.list.trade_id string 交易id
data.list.coin string 币种
data.list.txid string 链上txid
data.list.amount string 总金额
data.list.fee string 手续费 (业务规则fee不是链上gasfee),外扣模式
data.list.total string 提现总金额 total = amount+fee
data.list.address string 提现收款地址
data.list.from_address string 提现出款地址,正式环境2025-01-22之后接入的商户才会返回该属性
data.list.chain string 主链币名
data.list.memo string memo/tag 当前为 eos 及其代币 时 会回传该字段
data.list.status string 0 待审核、1 提现成功、2 等待风控处理中、5 等待出币、10 审核不通过、20 转账失败
data.list.time string 状态时间,最终固定在status=1时候的时间
data.list.type string 1站内交易 2链上交易 5中心化提现
data.list.gas_fee string 链上消耗Gas费,正式环境2024-08-14接入的商户才会返回该属性,精度统一8位
date_time string 响应时间
time_stamp integer 无时区的秒

提现结果回调通知

回调请求示例:

POST <商户提供的回调地址>
Content-Type: application/json
X-Cbc-Timestamp: 1792382460
X-Cbc-Nonce: 9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c
X-Cbc-Sign-Alg: RSA-SHA256
X-Cbc-Signature: <base64>

{
  "data": {
    "trade_id": "20200114202903274786",
    "coin": "usdt_erc20",
    "chain": "eth",
    "txid": "0x735dc8becd0d5dc0023b526584b75c8772551fc9268668991608dadc69facb39",
    "address": "0x038B8E7406dED2Be112B6c7E4681Df5316957cad",
    "from_address": "0xf854AC319A546ae11e367ef80a203AaC923ca6A3",
    "amount": "10.1",
    "fee": "0",
    "total": "10.1",
    "status": 1,
    "msg": "提现成功",
    "time": "1650011196",
    "type": 2,
    "gas_fee": "0.000105"
  }
}
http.HandleFunc("/notify/withdraw", func(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    if err := cbc.VerifyBody(r.Header, body, client.PlatformKey, true); err != nil {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }
    // 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"status":200,"data":{"success_data":"success"}}`))
})
$body = file_get_contents('php://input');
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
try {
    CbcClient::verifyBody($headers, $body, $platformPublicKeyPem, true);
} catch (RuntimeException $e) {
    http_response_code(401);
    exit;
}
// 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
$notify = json_decode($body, true);
header('Content-Type: application/json');
echo '{"status":200,"data":{"success_data":"success"}}';
app.post('/notify/withdraw', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    verifyBody((name) => req.get(name), req.body, platformPublicKeyPem, true);
  } catch (e) {
    return res.status(401).end();
  }
  // 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
  const notify = JSON.parse(req.body);
  res.type('application/json').send('{"status":200,"data":{"success_data":"success"}}');
});
@PostMapping(value = "/notify/withdraw", produces = "application/json")
public ResponseEntity<String> notify(@RequestHeader HttpHeaders headers, @RequestBody byte[] body) {
    Map<String, String> sig = new HashMap<>();
    for (String name : new String[]{"X-Cbc-Timestamp", "X-Cbc-Nonce", "X-Cbc-Sign-Alg", "X-Cbc-Signature"}) {
        sig.put(name, headers.getFirst(name));
    }
    try {
        CbcClient.verifyBody(sig, body, platformKey, true);
    } catch (Exception e) {
        return ResponseEntity.status(401).build();
    }
    // 验签已通过:按 X-Cbc-Nonce 去重后再解析 body,处理 data
    return ResponseEntity.ok("{\"status\":200,\"data\":{\"success_data\":\"success\"}}");
}

商户应答示例:

{
  "status": 200,
  "data": {
    "success_data": "success"
  }
}

HTTP Request

POST: 具体回调地址,由商户提供给平台方

请求参数

请求 Header 与接收端校验步骤见回调与复核签名。先用平台公钥验签,通过后再解析 body;下表为 body 中的字段。

参数名 必选 类型 说明
data 否 string 如下
data.trade_id 是 string 交易ID
data.coin 是 string 币名
data.chain 是 string 主链币名
data.txid 是 string txid
data.address 是 string 提现收款地址
data.from_address 是 string 交易出款地址,正式环境2025-01-22之后接入的商户才会返回该属性
data.time 是 string 订单最后更新时间
data.amount 是 string 提现数额,精度统一8位
data.fee 是 string 手续费,精度统一8位
data.total 是 string 提现总额 total=amount+fee,精度统一8位
data.status 是 string 提现状态 : 1 成功;5 出币处理中(此时会推送 txid,但是txid值以最终确认时为准。主要考虑前端展示对用户友好,像btc 类等链交易确认较慢);10 审核不通过;20 转账失败 ;其他错误码(参考错误码说明)
data.msg 是 string 状态描述
data.type 是 integer 1站内充值 2链上充值
data.gas_fee 否 string 链上消耗Gas费,正式环境2024-08-14接入的商户才会返回该属性,精度统一8位
data.refund_txid 否 string 兑换退款出款时下发,对应的退款 txid
data.tr_transfer_id 否 string Travel Rule 合规提币时下发,对应的 Travel Rule 交易授权 ID

返回参数说明

参数名 必选 类型 说明
status 是 integer 状态码
data 是 object 返回数据对象
data.success_data 是 string success 接收成功
类型 内容 商户处理办法
成功 对应trade_id的status=1 商户端可以认为一定成功
成功后变1 因链故障回滚,txid变化。trade_id和状态不变 商户端可以认为一定成功,只需更新txid
成功后变2 平台广播失败,平台处理 商户端可以认为一定成功,只需更新txid
失败1 因商户给错地址,把btc地址给了eth 平台不扣款,这种需要商户端重新请求
失败2 因用户余额不足 平台不扣款,这种需要商户端重新请求

简单来说:商户端错误导致失败,都有商户端重新请求处理。平台端错误由平台处理。对平台处理来说订单是绝对唯一的。txid是可能会变化的。
* 异步通知时间点
平台端执行发现客户端错误,或平台端确定成功后或成功后变。