Create Stable Order

This API is off-ramp / Convert only (stablecoin → fiat). On-ramp does not use
submit-order: after onboarding, fund the VA. Side, currency and VA come from
get-quote; do not pass virtualAccountId.

Request

field	required	notes
`quoteId`	yes	from get-quote; must not be expired
`merchantOrderId`	recommended	merchant idempotency / reconciliation key
`remarks`	no	free text
`beneficiaryBank`	no*	payout bank for this order. Omit the whole object to use the KYB default (`extra.bankAccounts`). If present, `accountName`, `accountNo` and `bankId` must all be set
`beneficiaryBank.accountName`	with `beneficiaryBank`	account holder name
`beneficiaryBank.accountNo`	with `beneficiaryBank`	local account number (NGN: 10-digit NUBAN)
`beneficiaryBank.bankId`	with `beneficiaryBank`	local bank code from the bank list, not a bank name

* HKD off-ramp still requires userRefundCryptoAddress and extInfo.travelRule.
NGN / KES must not send those fields.

Bank code validation (submit-time)

For NGN / KES, beneficiaryBank.bankId is validated when the order is
submitted, before the order is created. An unknown or unsupported code is
rejected immediately; it is not deferred to payout.

Call GET /v1/account/list-banks?currency={quote fiat} (NGN or KES).

Copy the returned bankCode into beneficiaryBank.bankId.

Do not invent codes, use clearing names, or reuse another currency’s list.

currency	`bankId`	`accountNo`
NGN	NIBSS code from list-banks (e.g. `058`)	10-digit NUBAN
KES	local bank code from list-banks (e.g. `01`)	local account number

If beneficiaryBank is omitted, the same rule applies to the KYB default
bankAccounts[].bankCode when that default is used for the order.

Submit-time errors:

ODR00001047 — bank code is not in the quote channel's currency catalog.

ODR00001048 — bank catalog is unavailable; the order is not created.

ODR00001049 — beneficiary account format is invalid (NGN requires a 10-digit NUBAN).

Response `data`

merchantOrderId, orderId, orderStatus (processing | success | fail).

Async final state via webhook STABLE_ORDER_UPDATED. Do not treat HTTP 200 alone as funds settled.
Guide: Guides → Convert.

Request

Body Params application/json

Examples

HKD/off-rampNGN/Off-rampKES/Off-ramp

{
    "quoteId": "e49ddd0a21404dbc95df1d35771d7024",
    "merchantOrderId": "BPN_RD_OFFRAMP_1788788907",
    "userRefundCryptoAddress": {
        "address": "0xUserBinanceWithdrawAddress",
        "network": "ETH",
        "currency": "USDT"
    },
    "beneficiaryBank": {
        "accountName": "Sample Trading Limited",
        "accountNo": "12345678901",
        "bankId": "003"
    },
    "extInfo": {
        "returnUrl": "https://merchant.example.com/rd/return",
        "cancelUrl": "https://merchant.example.com/rd/cancel",
        "travelRule": {
            "originatorName": "Sample Trading Limited",
            "beneficiaryName": "Sample Trading Limited",
            "customerType": "CORPORATE",
            "country": "HK",
            "address": "1 Queen's Road Central, Hong Kong",
            "residenceCountry": "HK"
        }
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Bodyapplication/json

Examples

P0 SuccessHKD off-ramp

{
    "status": 200,
    "code": "SUCCESS",
    "msg": "OK",
    "success": true,
    "traceId": "tr_3",
    "data": {
        "merchantOrderId": "m_20260730_001",
        "orderId": "ord_123",
        "orderStatus": "processing"
    }
}

Request#

Bank code validation (submit-time)#

Response data#

Request

Request Code Samples

Responses

Request

Bank code validation (submit-time)

Response `data`