开发者文档
官网控制台

创建订单

POST
/openapi/v1/collections/on-ramp/orders

创建 On-Ramp 订单，返回付款指引。成功返回 HTTP 200，创建后 status 为 AWAITING_PAYMENT。

付款人必须在 expiresAt 之前，向 paymentInfo.clabe 转账 fiatAmount MXN。

下单价格由渠道实时确定，可能与报价不同。以下单响应为准。

fiatAmount 和 cryptoAmount 必须传且只传一个。

按 fiatAmount 下单时，到账 USDT 由渠道确认，记账金额以响应中的 cryptoAmount 为准。渠道确认前，cryptoAmount 可能为空。

paymentInfo 为空时，表示渠道收款还没确认。用同一 Idempotency-Key 重试下单，或稍后查单。

渠道拒绝时，订单置为 FAILED。用同一 Idempotency-Key 重放会返回该 FAILED 订单。

付款人 KYC 只用于转发给渠道。Stabo 不保存，也不在响应中返回证件号和联系方式。

付款人的收款账号必须已开通，见开通收款账号接口。未开通时，下单返回「收款账号开通中」，不建单。

鉴权

bearerAuth
header鉴权Bearer <令牌>

通过 POST /oauth2/token 获取的 access_token。请求头格式为 Authorization: Bearer {accessToken}。商户身份从 Token 解析，请求体不接受商户或租户字段。

Header 参数

Idempotency-Key*string

唯一请求标识，最长 128 字符，建议用 UUID。同一商户内已存在时，返回原订单，不新建订单

长度length <= 128

请求体

application/json
  1. body
referenceNo?string

商户订单号，原样返回。最长 64

长度length <= 64
country*"MX"

固定 MX

可选值"MX"
fiatCurrency*"MXN"

固定 MXN

可选值"MXN"
cryptoCurrency*"USDT"

固定 USDT

可选值"USDT"
fiatAmount?string

付款人支付的 MXN 金额，大于 0，最多 2 位小数。与 cryptoAmount 二选一。可以传数字或字符串，建议传字符串

cryptoAmount?string

商户希望到账的 USDT 金额，大于 0。与 fiatAmount 二选一。可以传数字或字符串，建议传字符串

payerId*string

商户侧付款人唯一标识。由商户生成，1～64 位，只允许字母、数字、_、-。不得使用邮箱、手机号、证件号等个人信息。同一商户的同一 payerId，总是对应同一个 CLABE

匹配^[A-Za-z0-9_-]{1,64}$
payer*

付款人 KYC 信息。

payerAccount*

付款人银行账户。

remark?string

备注。最长 255

长度length <= 255

响应体

返回订单。示例中的付款人信息均为虚构数据。

application/json
  1. response
code?integer

业务状态码

message?string
traceId?string

请求追踪 ID。联系技术支持时请提供

data?

On-Ramp 订单。创建订单、查询订单和 Webhook 使用相同结构。

请求示例
curl -X POST 'https://api.test.stabofx.com/openapi/v1/collections/on-ramp/orders' \  -H 'Idempotency-Key: 7f9c2a1e-0b6d-4c2f-9d7e-1a2b3c4d5e6f' \  -H 'Content-Type: application/json' \  -d '{  "referenceNo": "merchant-order-0001",  "country": "MX",  "fiatCurrency": "MXN",  "cryptoCurrency": "USDT",  "cryptoAmount": "50.000000",  "payerId": "payer-0001",  "payer": {    "name": "Juan Perez Lopez",    "email": "juan@example.com",    "phone": "+5215512345678",    "country": "MX",    "address": "Av. Reforma 1, Ciudad de Mexico",    "dateOfBirth": "1990-01-31",    "idType": "NATIONAL_ID",    "idNumber": "XEXX010101HNEXXXA4"  },  "payerAccount": {    "accountType": "BANK",    "accountNumber": "012180001234567891",    "accountName": "Juan Perez Lopez"  },  "remark": "optional"}'
响应示例
{  "code": 200,  "message": "OK",  "traceId": "trace-uuid-string",  "data": {    "orderId": "bco_8f3k2m9q1x7z4t6w",    "referenceNo": "merchant-order-0001",    "status": "AWAITING_PAYMENT",    "country": "MX",    "fiatCurrency": "MXN",    "fiatAmount": "954.77",    "fiatFee": "13.50",    "cryptoCurrency": "USDT",    "cryptoAmount": "50.000000",    "price": "18.8253",    "paymentInfo": {      "method": "SPEI",      "clabe": "706180000000000001",      "reference": "REF123456"    },    "payer": {      "name": "Juan Perez Lopez"    },    "expiresAt": "2026-11-01T06:15:00Z",    "createdAt": "2026-11-01T10:15:00+08:00",    "completedAt": null,    "failureReason": null  }}