Sign in

v3

latestOpenAPI 3.0.3UNLICENSED2026-07-2796235396.3 KB
orders-orders

Create BUY order (returns OrderResponse with pay-in details)

Client BUY order — the buyer deposits fiat into a merchant-controlled pay-in account, and once the fiat lands, the merchant-locked asset is released to the buyer's wallet. The request carries sender (buyer identity for the pay-in) and optional creditAccountId (asset destination — defaults to the buyer's default base-currency account). The pay-in mode (DEPOSIT / INTERNAL_TRANSFER) is chosen on POST /quotes and inherited from the referenced quote; it is not specified here.

For DEPOSIT paymentMode orders, the server waits briefly (a few seconds) for the pay-in account to be provisioned and returns the full OrderResponse including payinPaymentDetails so the buyer knows where and how to deposit fiat. If provisioning is still in flight when the wait elapses, payinPaymentDetails is null — poll GET /clients/orders/{orderRef} until it appears or the order fails. INTERNAL_TRANSFER orders return immediately with payinPaymentDetails as null; poll the order until it appears. The same details are re-surfaced on GET /clients/orders/{orderRef} at any point.

post/orders/clients/orders/buy

Request body

quoteIdstring uuid required

General format for UUID

amountnumber required

Positive double

referencestring required
twoFaCodestring required
narrationstring

A description for the transfer that's passed to the recipient of the orders

creditAccountIdstring uuid

Wallet account on the buyer's side that should receive the asset. When omitted, the buyer's default base-currency account is used.

Example request

{
  "quoteId": "3a5aaea8-504a-4404-ad3d-b82574fba5e5"
}

Response

Order created successfully

idstring uuid required

General format for UUID

merchantIdstring uuid

General format for UUID

merchantAccountIdstring uuid

General format for UUID

clientIdstring uuid

General format for UUID

referencestring required
assetCurrencystring required
payoutCurrencystring required
payoutReferencestring
payoutRequestReferencestring
paymentChannel'BANK_TRANSFER' | 'MOBILE_MONEY' | 'P2P_WALLET'

Payment channel a provider is used for

type'BUY' | 'SELL' required
status'FAILED' | 'ONGOING' | 'COMPLETED' required
createdAtstring date-time required

Timestamp field.

responseTypestring required
amountnumber required

Amount for the order, always specified in the base currency. In merchant's view, this is the amount to receive (SELL) or amount to be sent (BUY) In the client's view, this is the amount they'll receive (BUY) or amount they are sending (SELL)

ratenumber required

The rate displayed to merchant or client.

paymentMode'DEPOSIT' | 'INTERNAL_TRANSFER'

How the buyer is paying fiat for a BUY order. Chosen at quote time on POST /quotes and persisted on the resulting quote; the BUY order then inherits the value when it references the quote. Clients do not (and cannot) re-specify it on the order request — the quote is the binding contract.

  • DEPOSIT — buyer transfers fiat from an external bank account into the merchant's pay-in account. Every payouts provider supports this and it is the default when the field is omitted.
  • INTERNAL_TRANSFER — buyer pays via an internal transfer routed through a configured override provider (currently onb-nuban for merchants on onb-nuban-collections). Quote generation filters out merchants whose payment account doesn't have providerDetails.supportsCustomPayin=true, or whose provider has no configured internal-transfer override on the order service. If no merchant satisfies the request, quote generation returns NoMatchingQuoteException rather than producing a quote that would later fail at order placement.

Example response

{
  "id": "3a5aaea8-504a-4404-ad3d-b82574fba5e5",
  "merchantId": "3a5aaea8-504a-4404-ad3d-b82574fba5e5",
  "merchantAccountId": "3a5aaea8-504a-4404-ad3d-b82574fba5e5",
  "clientId": "3a5aaea8-504a-4404-ad3d-b82574fba5e5"
}