NAV
go php js java

H5充值

创建订单

请求示例:

POST <base_path>/v2/h5Order/create 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>

{"merchant_order_id":"8MrxIV1lJd","amount":"0.0013","currency":"usd","return_url":"http://xxxx.com","success_url":"https://xxx.com/success.html","fail_url":"https://xxx.com/fail.html","hide_back":1,"lang":"en"}

resp, err := client.Post("/v2/h5Order/create", map[string]any{
    "merchant_order_id": "8MrxIV1lJd",
    "amount":            "0.0013",
    "currency":          "usd",
    "return_url":        "http://xxxx.com",
    "success_url":       "https://xxx.com/success.html",
    "fail_url":          "https://xxx.com/fail.html",
    "hide_back":         1,
    "lang":              "en",
})
$resp = $client->post('/v2/h5Order/create', [
    'merchant_order_id' => '8MrxIV1lJd',
    'amount' => '0.0013',
    'currency' => 'usd',
    'return_url' => 'http://xxxx.com',
    'success_url' => 'https://xxx.com/success.html',
    'fail_url' => 'https://xxx.com/fail.html',
    'hide_back' => 1,
    'lang' => 'en',
]);
const resp = await client.post('/v2/h5Order/create', {
  merchant_order_id: '8MrxIV1lJd',
  amount: '0.0013',
  currency: 'usd',
  return_url: 'http://xxxx.com',
  success_url: 'https://xxx.com/success.html',
  fail_url: 'https://xxx.com/fail.html',
  hide_back: 1,
  lang: 'en',
});
String resp = client.post("/v2/h5Order/create", Map.of(
        "merchant_order_id", "8MrxIV1lJd",
        "amount", "0.0013",
        "currency", "usd",
        "return_url", "http://xxxx.com",
        "success_url", "https://xxx.com/success.html",
        "fail_url", "https://xxx.com/fail.html",
        "hide_back", 1,
        "lang", "en"));

返回结果示例:

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":"success", "data":{ "order_no":"BCTOTNI57P", "merchant_order_id":"8MrxIV1lJd", "amount":"0.0013", "currency":"usd", "status":0, "created_at":1665659047, "expires_at":1665660847, "addresses":[ { "coin":"usdt_erc20", "address":"0x1708F6b16D5437730D410D983B8D0235c345433c", "amount":"0.0013" }, { "coin":"usdt_trc20", "address":"TKzqd9hTDgeeQcHf1RXiCuG6vPPFJK8BDP", "amount":"0.0013" } ], "return_url":"https://xxx.com/pay", "checkout_url":"http://api.xxxx.com/order/BCTOTNI57P?lang=en" }, "date_time":"2022-10-13 19:04:07", "time_stamp":1665659047 }

HTTP Request

POST /v2/h5Order/create

请求参数

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

参数名 必选 类型 说明
merchant_order_id 是 string 商家⾃定义订单号
amount 是 string 订单⾦额
currency 否 string 法币币种,默认usd,支持:usd, cny, hkd, rub, thb 等,更多请咨询客服
return_url 否 string 返回按钮默认的跳转链接,优先级低于success_url / fail_url
success_url 否 string 支付成功时,返回按钮的跳转链接,优先级高于return_url
fail_url 否 string 支付异常时,返回按钮的跳转链接,优先级高于return_url
hide_back 否 integer 隐藏返回按钮:传1隐藏,默认0显示
lang 否 string 语⾔ “en”, “ko”, “zh”

返回参数说明

参数名 类型 说明
status integer 状态码
msg string 状态描述
data object 具体见下面 “data细节说明”。
data.order_no string 订单号
data.merchant_order_id string 商家⾃定义订单号
data.amount string 订单⾦额
data.currency string 法币币种
data.status integer 0待⽀付 1已完成 2异常支付 10已取消
data.return_url string 返回地址
data.checkout_url string 收银台地址
data.expires_time integer 订单过期时间
data.create_time integer 创建时间
data.addresses array 地址信息
data.addresses.coin string 币名
data.addresses.address string 地址
data.addresses.amount string 应支付币种数额
date_time string 响应时间
time_stamp integer 响应时间单位秒

订单取消

请求示例:

POST <base_path>/v2/h5Order/cancel 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>

{"order_no":"test123"}
resp, err := client.Post("/v2/h5Order/cancel", map[string]any{
    "order_no": "test123",
})
$resp = $client->post('/v2/h5Order/cancel', [
    'order_no' => 'test123',
]);
const resp = await client.post('/v2/h5Order/cancel', {
  order_no: 'test123',
});
String resp = client.post("/v2/h5Order/cancel", Map.of("order_no", "test123"));

返回结果示例:

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": "success",
  "data": [],
  "date_time": "2020-11-23 16:51:51",
  "time_stamp": 1606121511
}

HTTP Request

POST /v2/h5Order/cancel

请求参数

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

参数名 必选 类型 说明
order_no 是 string 平台订单号

返回参数说明

参数名 类型 说明
status integer 状态码
msg string 状态描述
data array 为空
date_time string 响应时间
time_stamp integer 响应时间单位秒

订单详情

请求示例:

POST <base_path>/v2/h5Order/detail 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>

{"order_no":"JDYFJEEA7T"}
resp, err := client.Post("/v2/h5Order/detail", map[string]any{
    "order_no": "JDYFJEEA7T",
})
$resp = $client->post('/v2/h5Order/detail', [
    'order_no' => 'JDYFJEEA7T',
]);
const resp = await client.post('/v2/h5Order/detail', {
  order_no: 'JDYFJEEA7T',
});
String resp = client.post("/v2/h5Order/detail", Map.of("order_no", "JDYFJEEA7T"));

返回结果示例:

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":"success",
  "data":{
    "order_no":"JDYFJEEA7T",
    "merchant_order_id":"8MrxIV1lJd",
    "amount":"0.0013",
    "currency":"usd",
    "status":1,
    "created_at":1664360232,
    "expires_at":1664362032,
    "addresses":[
      {
        "coin":"usdt_erc20",
        "address":"0x1708F6b16D5437730D410D983B8D0235c345433c",
        "amount":"0.0013"
      },
      {
        "coin":"usdt_trc20",
        "address":"TKzqd9hTDgeeQcHf1RXiCuG6vPPFJK8BDP",
        "amount":"0.0013"
      }
    ],
    "payments":[
      {
        "coin":"usdt_trc20",
        "address":"TKzqd9hTDgeeQcHf1RXiCuG6vPPFJK8BDP",
        "txid":"422a7eef6af75960efa3e204fee1e642caf0b7d25dccd2678d6ae4e086733096",
        "amount":"0.0013",
        "confirm_time":1664360357,
        "status":1,
        "check_status":0
      }
    ],
    "return_url":"https://xxx.com/pay"
  },
  "date_time":"2022-10-13 19:24:26",
  "time_stamp":1665660266
}

HTTP Request

POST /v2/h5Order/detail

请求参数

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

参数名 必选 类型 说明
order_no 是 string 平台订单号

返回参数说明

参数名 类型 说明
status integer 状态码
msg string 状态描述
data object 具体见下面 “data细节说明”。
data.order_no string 平台订单号
data.merchant_order_id string 商家⾃定义订单号
data.amount string 订单⾦额
data.currency string 法币币种
data.status integer 0待⽀付 1已完成 2异常支付 10已取消
data.return_url string 返回地址
data.expires_time integer 订单过期时间
data.create_time integer 创建时间
data.addresses object 具体见下面 “addresses细节说明”。
data.addresses.coin string 币名
data.addresses.address string 地址
data.addresses.amount string 应支付币种数额
data.payments object 具体见下面 “payments细节说明”。
data.payments.coin string 支付币种
data.payments.address string 支付地址
data.payments.txid string txid
data.payments.amount string 支付金额
data.payments.confirm_time integer 确认时间
data.payments.status integer 状态: 0 待支付 1 正常支付 2 异常支付
data.payments.check_status integer 异常原因: 1001⽀付⾦额不匹配 1002已完成订单重复⽀付
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": {
    "order_no": "2020010211153423123456",
    "merchant_order_id": "ESIOqIfhKnY",
    "status": 1,
    "payments": [
      {
        "coin": "eth",
        "address": "0x038B8E7406dED2Be112B6c7E4681Df5316957cad",
        "txid": "0x735dc8becd0d5dc0023b526584b75c8772551fc9268668991608dadc69facb39",
        "amount": "0.1",
        "confirm_time": 1650011196,
        "check_code": 0
      }
    ]
  }
}
http.HandleFunc("/notify/h5", 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/h5', 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/h5", 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.order_no 是 string 订单号
data.merchant_order_id 是 string 商户订单号
data.status 是 integer 0待支付 1正常支付 2异常支付 10已取消
data.payments 是 array 支付信息
data.payments.coin 是 string 支付币种
data.payments.address 是 string 支付地址
data.payments.txid 是 string txid
data.payments.amount 是 string 支付金额
data.payments.confirm_time 是 integer 确认时间
data.payments.check_code 是 integer 0正常 1001⽀付⾦额不匹配 1002已完成订单重复⽀付
data.received_amount 否 string 已收到的支付金额合计。配置了支付容差时下发
data.within_tolerance 否 integer 1 表示实付金额与订单金额不完全一致,但在容差范围内并按支付成功处理;否则为 0。配置了支付容差时下发

返回参数说明

参数名 必选 类型 说明
status 是 integer 状态码
data 是 object 返回数据对象
data.success_data 是 string success 接收成功