Orders

Create an order from an order-intent quote; idempotent

Executes a held order quote: debits the source amount from your balance into a hold and queues the order for desk execution. The quote is single-use; retrying with the same quotationId returns the original order. Orders are executed manually by the trade desk within the execution window returned on the order; funds return to your balance in full on any non-delivered outcome (failed, expired, cancelled).

POST

orders

curl --request POST \
  --url https://api.example.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
  "quotationId": "550e8400-e29b-41d4-a716-446655440000",
  "clientRef": "ORD-2026-0001",
  "purpose": "Supplier settlement"
}
'

import requests

url = "https://api.example.com/v1/orders"

payload = {
    "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
    "quotationId": "550e8400-e29b-41d4-a716-446655440000",
    "clientRef": "ORD-2026-0001",
    "purpose": "Supplier settlement"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    beneficiaryId: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7',
    quotationId: '550e8400-e29b-41d4-a716-446655440000',
    clientRef: 'ORD-2026-0001',
    purpose: 'Supplier settlement'
  })
};

fetch('https://api.example.com/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'beneficiaryId' => 'cc82fa1d-fc7a-478c-a734-d3bce40464e7',
    'quotationId' => '550e8400-e29b-41d4-a716-446655440000',
    'clientRef' => 'ORD-2026-0001',
    'purpose' => 'Supplier settlement'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/orders"

	payload := strings.NewReader("{\n  \"beneficiaryId\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\",\n  \"quotationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"clientRef\": \"ORD-2026-0001\",\n  \"purpose\": \"Supplier settlement\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/orders")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiaryId\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\",\n  \"quotationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"clientRef\": \"ORD-2026-0001\",\n  \"purpose\": \"Supplier settlement\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"beneficiaryId\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\",\n  \"quotationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"clientRef\": \"ORD-2026-0001\",\n  \"purpose\": \"Supplier settlement\"\n}"

response = http.request(request)
puts response.read_body

{
  "beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "<string>",
  "fromAmount": "1006.5000",
  "fromCurrency": "USDT",
  "fundingDeadlineAt": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rate": "0.00067100",
  "status": "funds_received",
  "toAmount": "1500000.0000",
  "toCurrency": "NGN",
  "updatedAt": "<string>",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRef": "<string>",
  "completedAt": "<string>",
  "executionDeadlineAt": "<string>",
  "fundedAt": "<string>",
  "purpose": "<string>",
  "uetr": "<string>",
  "settlement": {
    "settlementId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "requiredAmount": "1006.5000",
    "currency": "XOF",
    "reference": "SETTLE-4F7A2C91B0",
    "instructions": {},
    "expiresAt": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Headers

Idempotency-Key

string

required

Client-generated idempotency key (UUID). Retrying with the same quotationId also replays the original order: the quote is single-use and one order per quote is enforced.

Zuba-Account-Id

string<uuid>

Optional. Names an owned sub-account (UUID) to create the order for: the order funds from that sub-account's balance and carries its accountId. Omit to act at the master (tenant) level. Naming an account this key does not own returns 403 not_account_owner.

Body

application/json

beneficiaryId

string<uuid>

required

Id of the saved beneficiary to deliver to. The beneficiary must hold an active account in the quote target currency.

Example:

"cc82fa1d-fc7a-478c-a734-d3bce40464e7"

quotationId

string<uuid>

required

Id of the order-intent quote to execute (from POST /v1/quotes with intent 'order'). Single-use; the order must be created within the quote's TTL.

Example:

"550e8400-e29b-41d4-a716-446655440000"

clientRef

string

Client-supplied reference, unique per client. Surfaces on the order and ledger history.

Maximum string length: 100

Example:

"ORD-2026-0001"

purpose

string

Free-text purpose of the order.

Maximum string length: 500

Example:

"Supplier settlement"

Response

Order created and queued for desk execution

beneficiaryId

string<uuid>

required

Beneficiary id

createdAt

string

required

Creation time (ISO 8601)

fromAmount

string

required

Total source debit, in fromCurrency (decimal string)

Example:

"1006.5000"

fromCurrency

string

required

Funded (source) currency

Example:

"USDT"

fundingDeadlineAt

string

required

Deadline for funds to be attributed to the order before it expires (ISO 8601)

string<uuid>

required

Order id

quoteId

string<uuid>

required

Consumed quote id

rate

string

required

All-in rate: fromCurrency per 1 toCurrency

Example:

"0.00067100"

status

enum<string>

required

Order lifecycle status. Orders are executed manually by the trade desk: funds_received means the order is queued for execution, executing means execution is approved and in flight, completed means delivered.

Available options:

created,

awaiting_funds,

funds_received,

executing,

completed,

failed,

expired,

cancelled

Example:

"funds_received"

toAmount

string

required

Amount delivered, in toCurrency (decimal string)

Example:

"1500000.0000"

toCurrency

string

required

Delivered (target) currency

Example:

"NGN"

updatedAt

string

required

Last update time (ISO 8601)

accountId

string<uuid>

Owning sub-account; present when the order was created in a sub-account context (Zuba-Account-Id header). Absent = the order belongs to your master account.

clientRef

string

Client-supplied reference

completedAt

string

When the order completed (ISO 8601)

executionDeadlineAt

string

Desk execution deadline, set when funds are received (ISO 8601)

failureReason

enum<string>

Fixed failure code; present only when status is failed

Available options:

execution_failed,

review_expired

fundedAt

string

When funds were received (ISO 8601)

purpose

string

Free-text purpose

uetr

string

Outbound wire reference (UETR); present once the order completes over a wire rail

settlement

object

Funding instructions for an order created without sufficient balance; present while the order awaits funds and after matching

Show child attributes

List ordersReturns your orders newest-first with opaque cursor pagination. Filter by `status` and a `from`/`to` creation-time window.

Create an order from an order-intent quote; idempotent

curl --request POST \
  --url https://api.example.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
  "quotationId": "550e8400-e29b-41d4-a716-446655440000",
  "clientRef": "ORD-2026-0001",
  "purpose": "Supplier settlement"
}
'

import requests

url = "https://api.example.com/v1/orders"

payload = {
    "beneficiaryId": "cc82fa1d-fc7a-478c-a734-d3bce40464e7",
    "quotationId": "550e8400-e29b-41d4-a716-446655440000",
    "clientRef": "ORD-2026-0001",
    "purpose": "Supplier settlement"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    beneficiaryId: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7',
    quotationId: '550e8400-e29b-41d4-a716-446655440000',
    clientRef: 'ORD-2026-0001',
    purpose: 'Supplier settlement'
  })
};

fetch('https://api.example.com/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'beneficiaryId' => 'cc82fa1d-fc7a-478c-a734-d3bce40464e7',
    'quotationId' => '550e8400-e29b-41d4-a716-446655440000',
    'clientRef' => 'ORD-2026-0001',
    'purpose' => 'Supplier settlement'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/orders"

	payload := strings.NewReader("{\n  \"beneficiaryId\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\",\n  \"quotationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"clientRef\": \"ORD-2026-0001\",\n  \"purpose\": \"Supplier settlement\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/orders")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiaryId\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\",\n  \"quotationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"clientRef\": \"ORD-2026-0001\",\n  \"purpose\": \"Supplier settlement\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"beneficiaryId\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\",\n  \"quotationId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"clientRef\": \"ORD-2026-0001\",\n  \"purpose\": \"Supplier settlement\"\n}"

response = http.request(request)
puts response.read_body

{
  "beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "<string>",
  "fromAmount": "1006.5000",
  "fromCurrency": "USDT",
  "fundingDeadlineAt": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rate": "0.00067100",
  "status": "funds_received",
  "toAmount": "1500000.0000",
  "toCurrency": "NGN",
  "updatedAt": "<string>",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRef": "<string>",
  "completedAt": "<string>",
  "executionDeadlineAt": "<string>",
  "fundedAt": "<string>",
  "purpose": "<string>",
  "uetr": "<string>",
  "settlement": {
    "settlementId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "requiredAmount": "1006.5000",
    "currency": "XOF",
    "reference": "SETTLE-4F7A2C91B0",
    "instructions": {},
    "expiresAt": "<string>"
  }
}