提现
提现申请
请求示例:
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是可能会变化的。
* 异步通知时间点
平台端执行发现客户端错误,或平台端确定成功后或成功后变。