接入概览

iBitPay 开放接口让你的系统直接向客户收取法币（入金）、向收款人支付法币（出金），平台按汇率用 USDT 和你结算。

接入步骤

1. 开通：联系平台开通商户账号和开放接口。
2. 拿到接口地址和密钥：登录商户后台，在「开发者 → API 与回调」查看接口地址、公钥和私钥（要先通过安全验证和资金密码）。接口地址和两把钥匙都不要公开，见安全建议。
3. 设置 IP 白名单：把调用接口的服务器出口 IP 填进白名单。不在白名单里的请求会被拒绝（40005）。
4. 设置回调地址：分别填入金回调地址、出金回调地址（必须是 https）。也可以在每笔订单里单独指定。
5. 联调：联系平台把你的商户先接到测试交易员，用小额订单把下单、回调、查询走通，再正式开放给客户。

接口地址

接口地址在商户后台「开发者 → API 与回调」里，和密钥在同一页。每个接口的完整地址 = 接口地址 + 文档里写的路径，例如「接口地址 + /api/open/order/createBuyOrder」。

通用约定

• 请求：全部是 POST，Content-Type: application/json。业务参数先加密，再放进请求体，格式见请求格式与加密。

• 返回：HTTP 状态码都是 200，以返回内容里的 code 为准：

  { "code": 0, "message": "success", "data": { } }

  code 为 0 表示成功，其他值见错误码。message 是英文说明。返回的内容不加密。

• 字段名：返回的字段名是小驼峰（如 merchantOrderNo）；请求参数的字段名不区分大小写。

• 金额：法币金额必须大于 0、最多两位小数。返回里的数字最多保留两位小数（汇率也是）。建议用十进制类型处理金额，不要用浮点数直接比较。

• 时间：返回的时间格式是 yyyy-MM-dd HH:mm:ss，时区 UTC+8，不带时区标记。

• 空值：返回里没有值的文字字段是空字符串 ""，不是 null。

• 商户订单号：每笔订单都请自己生成并保存一个唯一的 merchantOrderNo。查询、对账、核对回调都靠它，同一个号不能重复下单（40007），这也能防止网络超时后重试造成重复出款。

• 频率：平台有防刷限制，短时间内请求过多会被暂时封禁 IP。建议每秒不超过 10 次请求，查询类接口不要轮询过密，到账以回调为准。

一笔入金的流程

1. 你的系统调用创建入金订单，拿到收银台地址，把客户带过去。
2. 客户在收银台按页面上的收款账户付款。
3. 平台确认收到钱后，订单变成「已释放」（6），平台向你的入金回调地址发通知。
4. 你收到回调后，先用查询订单复核状态和金额，再给客户入账，然后返回 success。
5. 平台收到 success，订单变成「成功」（3）。USDT 在订单释放时已经记入你的余额。

自建收银台的流程见创建入金订单（自建收银台）。

一笔出金的流程

1. （可选）调用查询收款方式，知道每个法币要填哪些收款信息。
2. 调用创建出金订单。平台按出金汇率从你的 USDT 余额里扣款并冻结。
3. 出款处理成功（4）或被拒绝（5）后，平台向你的出金回调地址发通知；被拒绝的会退回 USDT。
4. 你收到回调后用查询订单复核，再更新自己的订单。

接口列表

分类	接口	路径
收款	创建入金订单（收银台）	/api/open/order/createBuyOrder
收款	创建入金订单（自建收银台）	/api/open/order/createBuyOrder2
收款	标记已付款	/api/open/order/complete2
收款	取消订单	/api/open/order/cancel2
收款	获取入金汇率	/api/open/order/getBuyRate
出款	创建出金订单	/api/open/order/createSellOrder
出款	获取出金汇率	/api/open/order/getSellRate
出款	查询收款方式	/api/open/order/getPaymentMethods
查询	查询订单	/api/open/order/getDetail
查询	查询余额	/api/open/order/getBalance
查询	查询资金流水	/api/open/order/getFlows
查询	查询黑名单	/api/open/blocked/user/list