Trade Desk Orders

Orders are Zuba’s channel for large currency transfers that are executed manually by our trade desk rather than dispatched straight through to a payment rail. You request a firm quote, create the order against it, fund it, and Zuba’s desk sources liquidity and delivers to your beneficiary within an execution window stated on the order. The flow is deliberately different from payouts in three ways:

Quote-first. Every order starts from a firm quote (POST /v1/quotes with intent: "order"). There is no auto-priced path.
Fund-first. The desk executes only against funds that are already secured. If your Zuba balance covers the order it is funded at creation; otherwise the order returns funding instructions and waits for your transfer. Zuba never extends credit, and nothing moves outbound until the order is funded.
Manually executed. A human trading team fills the order and a second operator approves the execution before any funds move. Orders complete within the execution window returned on the order, not in seconds.

If you need automated, straight-through delivery for everyday amounts, use payouts instead. Amounts above a payout corridor’s cap are served by this channel.

Orders vs payouts

	Payouts	Orders
Execution	Automated, straight-through	Manual, by Zuba’s trade desk
Pricing	Quote or auto-priced; rate plus a fixed fee	Always quote-first; a single all-in rate, no separate fee
Funding	Your balance, at creation	Your balance, or a per-order transfer against funding instructions
Typical size	Everyday amounts, subject to corridor caps	Large transfers, including amounts above payout corridor caps
Speed	Seconds to minutes	Within the execution window on the order
Cancellation	While still pending	Any time before the desk approves execution

Prerequisites

Orders enabled on your account. Orders are enabled per account, configured with the currency pairs (corridors) and transaction limits agreed during onboarding. Contact your account manager to get set up.
A beneficiary holding an active account in the buy currency (see Beneficiaries).
Valid API credentials (see Authentication).

The examples below use the sandbox host https://api.sandbox.zuba.com. In production, swap it for https://api.zuba.com; everything else is identical.

Step 1: Get a firm quote

Request a quote with intent: "order". Fix exactly one side of the trade:

fromAmount fixes what you sell (the total debit), or
toAmount fixes what your beneficiary receives.

curl -X POST "https://api.sandbox.zuba.com/v1/quotes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "order",
    "fromCurrency": "USDT",
    "toCurrency": "NGN",
    "toAmount": "1500000.00"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fromCurrency": "USDT",
  "toCurrency": "NGN",
  "targetAmount": "1500000.00",
  "totalDebitAmount": "1006.50",
  "rate": "0.00067100",
  "expiresAt": "2026-07-08T12:00:30.000Z"
}

Three things to know about order quotes:

The rate is all-in. totalDebitAmount is exactly what the order costs you; there is no separate fee added at order creation. rate is expressed as fromCurrency per 1 toCurrency.
The quote is firm. The rate you see is the rate your order executes at, regardless of market movement while the desk works the order.
The quote is single-use and short-lived. It typically expires within about 30 seconds; always read expiresAt rather than assuming a TTL. Create the order before it expires, or request a fresh quote.

A quote request is rejected with UNSUPPORTED_CORRIDOR if the currency pair is not available on the orders channel, or with AMOUNT_OUT_OF_BOUNDS if the amount is below the corridor minimum.

Step 2: Create the order

Create the order with the quote id and a beneficiary. The Idempotency-Key header is required.

curl -X POST "https://api.sandbox.zuba.com/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d9f6c2a-8f6e-4b1a-9d3e-2c7b5a1e0f48" \
  -d '{
    "quotationId": "550e8400-e29b-41d4-a716-446655440000",
    "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
    "clientRef": "ORD-2026-0001",
    "purpose": "Supplier settlement"
  }'

Creation consumes the quote (it cannot be used again) and picks a funding path based on your available balance in the sell currency: If your balance covers fromAmount, it is debited into a hold reserved for this order in the same step, and the order is created directly in funds_received, queued for the desk:

{
  "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
  "status": "funds_received",
  "fromCurrency": "USDT",
  "toCurrency": "NGN",
  "fromAmount": "1006.5000",
  "toAmount": "1500000.0000",
  "rate": "0.00067100",
  "clientRef": "ORD-2026-0001",
  "purpose": "Supplier settlement",
  "fundingDeadlineAt": "2026-07-08T12:30:00.000Z",
  "executionDeadlineAt": "2026-07-08T18:00:00.000Z",
  "fundedAt": "2026-07-08T12:00:05.000Z",
  "createdAt": "2026-07-08T12:00:05.000Z",
  "updatedAt": "2026-07-08T12:00:05.000Z"
}

Otherwise, no money moves: the order is created in awaiting_funds and the response carries a settlement block with the funding instructions, the exact amount to transfer, and a unique reference:

{
  "id": "1b7e4a90-2c5d-4e8f-9a0b-3c6d7e8f9a0b",
  "quoteId": "6a1f9511-f3ac-52e5-b827-557766551111",
  "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
  "status": "awaiting_funds",
  "fromCurrency": "XOF",
  "toCurrency": "USD",
  "fromAmount": "6500000.0000",
  "toAmount": "10000.0000",
  "rate": "650.00000000",
  "clientRef": "ORD-2026-0002",
  "settlement": {
    "settlementId": "8c2d5e7f-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
    "method": "virtual_account",
    "requiredAmount": "6500000.0000",
    "currency": "XOF",
    "reference": "SETTLE-4F7A2C91B0",
    "status": "open",
    "instructions": {
      "bankName": "Example Bank",
      "accountNumber": "00012345678",
      "accountName": "Zuba Collections",
      "note": "Include the settlement reference in the transfer narration."
    },
    "expiresAt": "2026-07-08T12:30:00.000Z"
  },
  "fundingDeadlineAt": "2026-07-08T12:30:00.000Z",
  "createdAt": "2026-07-08T12:00:05.000Z",
  "updatedAt": "2026-07-08T12:00:05.000Z"
}

Either way the quoted rate is locked: funding the order within the window executes at the rate on the order, regardless of market movement in between. Idempotency. Retrying the same request returns the original order rather than creating a duplicate. Two independent guards apply: the quote is single-use (a retry carrying the same quotationId returns the order it already created), and clientRef is unique per account (reusing one on a different order returns 409 CLIENT_REF_ALREADY_USED).

Step 3: Fund the order

Balance-funded orders skip this step; they are already funds_received. For a settlement-funded order, transfer requiredAmount to the instructions before fundingDeadlineAt (mirrored on settlement.expiresAt):

Bank transfer (method: "virtual_account"): send to the account in instructions and include the reference in the transfer narration wherever your bank supports one. How funding is confirmed depends on the account, stated in instructions.note:
- Narration-matched accounts: a referenced transfer attributes to the order at any amount — a short payment sits on your balance until you top it up under the same reference, and an overpayment attributes with the excess left on your balance. Without the reference, only a transfer of exactly requiredAmount auto-matches; anything else is credited to your balance and attributed manually.
- Confirmation-upload accounts (the note asks you to upload your payment confirmation): after sending the transfer, request an upload URL with POST /v1/orders/{id}/settlement/proof-upload-url (body: the document’s contentType and contentLength; PDF, JPG or PNG, up to 10 MB), PUT the confirmation document to it, then submit the returned proofKey with POST /v1/orders/{id}/settlement/proof. Funding is confirmed from the uploaded document, and the order moves on automatically once it is verified. Still include the reference on the wire: it speeds up verification.
Crypto transfer (method: "wallet_address"): send exactly requiredAmount to your own deposit address from instructions.addresses (any listed network). The receiving address identifies you, so no reference is needed.

When the transfer is confirmed, the funds are held into the order, the status moves to funds_received, executionDeadlineAt is set, and the order.funds_received webhook fires. In the sandbox, no real bank transfer exists to verify, so a confirmation-upload settlement is confirmed immediately when you submit the proof document — upload any PDF/JPG/PNG and the order moves to funds_received on submission, letting you integration-test the full awaiting_funds lifecycle. Narration-matched funding is simulated with POST /v1/sandbox/deposits carrying the settlement reference in narration. If the funding window closes first, the order lands expired (webhook order.expired) and the settlement is closed. Nothing was held, so there is nothing to refund; a transfer that arrives after expiry is simply credited to your balance. On confirmation-upload accounts this includes a confirmation you submitted before expiry: it is still verified and the funds are credited to your balance once confirmed. A confirmation cannot be submitted against an expired order, so if you sent the transfer but missed the window, contact support to have the payment applied. Re-quote and create a fresh order, which your now-funded balance can fund directly.

Step 4: Wait for desk execution

This is the part that makes orders different: there is nothing to call. Your order is now in a queue worked by Zuba’s trading team. An operator fills the order at or better than your quoted rate, and a second operator independently reviews and approves the execution before any funds move. This dual-control step is why orders are not instant. What you can rely on:

An order the desk has not approved never outlives executionDeadlineAt. If execution is not approved by then, the order automatically fails with reason review_expired and your held funds are returned — you never need to chase an unapproved order.
While the desk works, the order reports funds_received. Once execution is approved it briefly reports executing; at that point it can no longer be cancelled and proceeds to completion — any post-approval issue is resolved by Zuba operations.
Desk internals (venues, fills, operators) are never exposed on the API. Your contract is the quoted rate and the execution window.

Track progress by webhook (recommended) or by polling:

curl "https://api.sandbox.zuba.com/v1/orders/9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 5: Completion

When the desk delivers to your beneficiary, the order lands completed and the order.completed webhook fires. For orders delivered over a wire rail, the response and webhook carry the outbound wire reference (uetr) for your beneficiary’s bank to trace the payment.

{
  "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "status": "completed",
  "uetr": "e8b1a9d2-7c4f-4a2b-8e6d-1f3a5b7c9d0e",
  "completedAt": "2026-07-08T14:21:07.000Z",
  "...": "..."
}

The hold is settled: you paid exactly fromAmount at the quoted rate, and the ledger shows the order’s legs against the order id. See Ledger for how to reconcile.

Order lifecycle

Status	Meaning
`created`	The order exists but no funding path has resolved yet. Transient: creation moves straight on to `funds_received` or `awaiting_funds`, so polling never observes it (the `order.created` webhook still fires).
`awaiting_funds`	Funding instructions are issued and the order is waiting for your transfer. No funds are held.
`funds_received`	The source amount is held and the order is queued for the desk.
`executing`	The desk has approved execution. The order can no longer be cancelled and proceeds to completion.
`completed`	Delivered to your beneficiary. `uetr` is set for wire deliveries. Terminal.
`failed`	The desk could not execute the order, or the execution window lapsed before execution was approved. `failureReason` is set and any held funds are returned to your balance in full. Terminal.
`expired`	The funding window closed before the order was funded. Nothing was held; late-arriving funds credit your balance. Terminal.
`cancelled`	You cancelled before execution was approved. Any held funds are returned in full. Terminal.

Webhooks

Order webhooks share the envelope, signing, and retry behaviour described in Webhook Notifications. Subscribe your endpoint to the order.* events:

Event	Fires when
`order.created`	The order is created. Arrives together with `order.funds_received` or `order.awaiting_funds`.
`order.awaiting_funds`	Funding instructions are issued; the payload’s `settlement` block carries the account or address, amount, and reference.
`order.funds_received`	Funds are held and the order is queued for the desk.
`order.completed`	The desk delivered; `uetr` present for wire deliveries.
`order.failed`	The order failed; `failureReason` set, any held funds returned.
`order.expired`	The funding window closed before the order was funded.

There is no webhook for executing (desk review is internal) and none for cancelled (cancellation is your own synchronous API call). Every event for a settlement-funded order carries the settlement block, so you can correlate by reference at any point in the lifecycle; on balance-funded orders settlement is null. Example delivery:

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "order.completed",
  "createdAt": "2026-07-08T14:21:08.000Z",
  "test": false,
  "data": {
    "id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "clientRef": "ORD-2026-0001",
    "status": "completed",
    "fromCurrency": "USDT",
    "toCurrency": "NGN",
    "fromAmount": "1006.5000",
    "toAmount": "1500000.0000",
    "rate": "0.00067100",
    "failureReason": null,
    "uetr": "e8b1a9d2-7c4f-4a2b-8e6d-1f3a5b7c9d0e",
    "settlement": null,
    "fundingDeadlineAt": "2026-07-08T12:30:00.000Z",
    "executionDeadlineAt": "2026-07-08T18:00:00.000Z",
    "fundedAt": "2026-07-08T12:00:05.000Z",
    "completedAt": "2026-07-08T14:21:07.000Z",
    "createdAt": "2026-07-08T12:00:05.000Z"
  }
}

Cancelling an order

You can cancel an order at any point before the desk approves execution:

curl -X POST "https://api.sandbox.zuba.com/v1/orders/9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d/cancel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful cancel returns the order with status: "cancelled". While the order is awaiting_funds nothing is held, so cancellation simply closes it; after funds_received the held funds are returned to your balance in full. Retrying a successful cancel returns the already-cancelled order. Once execution has been approved (executing, or a terminal status other than cancelled), cancel returns 409 ORDER_NOT_CANCELLABLE. Because approval can happen at any moment while the order is funds_received, treat cancellation as a race you can lose: a 409 means the trade is executing and will complete at the quoted rate.

Failures and refunds

A failed order is terminal and automatically refunds the full held amount to your balance; there is no partial execution and nothing to claim. (The desk can also reject an order that is still awaiting_funds — nothing was held, so there is nothing to refund.) failureReason carries a fixed taxonomy:

`failureReason`	Meaning	What to do
`execution_failed`	The desk could not execute the order.	Funds are back on your balance. Request a fresh quote and create a new order, or contact support if it recurs.
`review_expired`	The execution window lapsed before the desk approved execution.	Same: funds are returned; re-quote and retry.

A failed order is a normal, fully-resolved outcome, not a stuck state: the terminal status and the refund arrive together. Refunds always land on your Zuba balance, never as an outbound transfer back to you; withdraw them with a payout if you need them off-platform. Reconcile by matching the hold and its reversal against the order id in your ledger history.

An expired order held nothing, so there is no refund; any transfer that arrives after expiry is credited to your balance.

Listing orders

GET /v1/orders returns your orders newest-first with cursor pagination, filterable by status and a from/to creation-time window:

curl "https://api.sandbox.zuba.com/v1/orders?status=completed&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use distinct clientRef values per order; they surface on the order, the webhooks, and your ledger history, and make reconciliation trivial.

Testing in the sandbox

The sandbox exercises the real order machinery end to end. Two mechanisms cover the parts that involve other actors in production: Deterministic desk outcomes. Orders are executed manually in production, so two magic sell amounts drive a funded order through the real desk workflow to a terminal state without a human operator. Any other amount stays in funds_received awaiting manual execution, exactly as in production.

Sell amount	Outcome
`1111.11`	Lands `completed`, with a `sandbox-` prefixed `uetr`.
`2222.22`	Lands `failed` (`execution_failed`), with the held funds returned to your balance.

The match is on the order’s source (sell) amount, is numeric (1111.11 matches 1111.1100), and works in any sell currency. Simulated settlement funding. The sandbox deposit endpoint accepts a narration field; include an order’s settlement reference in it to exercise the real automatic matcher. A complete settlement-funded run, using a fiat sell currency (settlements in crypto sell currencies fund through your own deposit addresses by exact amount, so the narration mechanism below does not apply to them):

Quote with the sell side pinned to a magic amount: {"intent": "order", "fromCurrency": "USD", "toCurrency": "NGN", "fromAmount": "1111.11"}.
Create the order with the returned quote id and a beneficiary holding an active account in the buy currency. With no balance in the sell currency, the order lands awaiting_funds and returns the settlement block (order.created + order.awaiting_funds fire).
Simulate your transfer: POST /v1/sandbox/deposits with amount set to requiredAmount, currency set to the sell currency, and narration containing the settlement reference. The matcher attributes it, holds the funds, and fires order.funds_received.
The magic sell amount then drives the desk flow: order.completed (or order.failed for 2222.22) arrives shortly after. Do not assume a fixed delay; wait on the webhook or poll.

To test the balance-funded path instead, fund your sandbox balance first and create the order; it goes straight to funds_received. To test cancellation, use a non-magic amount (the order will sit in awaiting_funds or funds_received) and call the cancel endpoint. To test expiry, create a settlement-funded order and let the funding window lapse. See Sandbox Testing for the full sandbox reference.

Error reference

Status	Code	Cause
400	`Idempotency-Key header is required`	Missing the required header on create.
400	`QUOTE_NOT_FOUND` / `QUOTE_EXPIRED` / `QUOTE_ALREADY_USED` / `QUOTE_INTENT_MISMATCH`	The quote is unknown, past `expiresAt`, already consumed, or was not minted with `intent: "order"`. Request a fresh order quote.
400	`UNSUPPORTED_CORRIDOR`	The currency pair is not available on the orders channel.
400	`NO_PRICING_PLAN` / `CORRIDOR_NOT_ENABLED`	The pair is not enabled on your account’s pricing plan. Contact your account manager.
400	`AMOUNT_OUT_OF_BOUNDS`	The amount is below the corridor minimum.
400	`BENEFICIARY_NOT_FOUND`	The beneficiary id does not exist on your account.
400	`NO_SUITABLE_ACCOUNT_FOR_ORDER_CURRENCY`	The beneficiary has no active account in the buy currency.
403	`insufficient_scope`	Your API credentials lack the `create:orders` / `read:orders` scopes — orders are not enabled on your account.
409	`CLIENT_REF_ALREADY_USED`	The `clientRef` was already used on a different order.
409	`ORDER_NOT_CANCELLABLE`	Cancel arrived after execution was approved.
422	`INSUFFICIENT_LIQUIDITY`	A live rate for the pair is temporarily unavailable. Retry shortly; contact support if it persists.
422	`INSUFFICIENT_BALANCE`	Your balance does not cover `fromAmount` and settlement funding is not available for the sell currency on your account.
422	limit exceeded	The order exceeds your per-transaction or monthly limit. Limits are agreed at onboarding; contact your account manager to raise them.

Next steps

Webhook Notifications for endpoint setup, signature verification, and retries
Sandbox Testing for the full deterministic test-value reference
Ledger for reconciling order holds, settlements, and refunds
Orders API reference for full request and response schemas

Get Started

Core Concepts

Guides

Trade Desk Orders

Orders vs payouts

Prerequisites

Step 1: Get a firm quote

Step 2: Create the order

Step 3: Fund the order

Step 4: Wait for desk execution

Step 5: Completion

Order lifecycle

Webhooks

Cancelling an order

Failures and refunds

Listing orders

Testing in the sandbox

Error reference

Next steps

​Orders vs payouts

​Prerequisites

​Step 1: Get a firm quote

​Step 2: Create the order

​Step 3: Fund the order

​Step 4: Wait for desk execution

​Step 5: Completion

​Order lifecycle

​Webhooks

​Cancelling an order

​Failures and refunds

​Listing orders

​Testing in the sandbox

​Error reference

​Next steps

Orders vs payouts

Prerequisites

Step 1: Get a firm quote

Step 2: Create the order

Step 3: Fund the order

Step 4: Wait for desk execution

Step 5: Completion

Order lifecycle

Webhooks

Cancelling an order

Failures and refunds

Listing orders

Testing in the sandbox

Error reference

Next steps