Skip to main content
POST
Create a desk order

Authorizations

Authorization
string
header
required

Your Jenzy API key: Authorization: Bearer jz_live_…

Headers

Idempotency-Key
string
required

Required. A key you mint per order intent (a UUID works). Replays of the same key + body return the original response; the same key with a different body is a 409.

HERMES-ORG
string<uuid>

The id of one of your Child orgs. The call then acts on that Child org, not on your organization. If you do not send it, the call acts on your organization. An id that is not one of your Child orgs gives 404.

Example:

"3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10"

Body

application/json
quote_id
string<uuid>
required

A quote_id from POST /v2/orders/quotes, not yet expired or used.

client_ref
string
required

Your reference for this order, at most 64 characters, unique across your orders; reuse is client_ref_used (409). Jenzy does not send it to the bank.

Required string length: 1 - 64
Example:

"inv-1042"

beneficiary
object

Required on a to-bank order (stablecoin → corridor currency): who receives the fiat. Must be absent on a from-bank order (beneficiary_not_allowed).

Response

Created: accepted (to-bank order, stablecoin held) or awaiting_instructions (from-bank order).

id
string<uuid>
required

The order id — your handle for polling and support.

client_ref
string
required
Example:

"inv-1042"

from_asset
string
required

An asset code as GET /v2/assets lists it — uppercase, never compound (USDC, USD; never USDC-ETHEREUM). Network and rail live on the payment object.

Minimum string length: 1
Example:

"USDT"

from_amount
string
required

What you pay, in from_asset. On a to-bank order this is held from your balance at creation.

Example:

"1000"

to_asset
string
required

An asset code as GET /v2/assets lists it — uppercase, never compound (USDC, USD; never USDC-ETHEREUM). Network and rail live on the payment object.

Minimum string length: 1
Example:

"BIF"

to_amount
string
required

What the beneficiary receives (to-bank order) or you are credited (from-bank order), in to_asset.

Example:

"2850500"

rate
string
required

The quote’s rate: corridor currency per one stablecoin.

Example:

"2850.5"

status
enum<string>
required

To-bank order: accepted (your stablecoin is held) → processing (the desk is paying the beneficiary) → completed | failed | cancelled. From-bank order: awaiting_instructions → awaiting_funds (see funding; wire before expires_at) → proof_submitted → funds_confirmed → completed | expired | failed | cancelled. There is no cancel endpoint; ask Jenzy operations.

Available options:
accepted,
processing,
awaiting_instructions,
awaiting_funds,
proof_submitted,
funds_confirmed,
expired,
completed,
failed,
cancelled
Example:

"accepted"

failure
object | null
required

Set only on failed: one of the published codes with its fixed message.

proofs
object
required

Your newest funding proof on a from-bank order, if any.

created_at
string<date-time>
required
updated_at
string<date-time>
required
receipt_url
string<uri> | null
required

The public link to the receipt of an order that pays a bank beneficiary. Send it to your beneficiary: the page shows the status of the payment, not your fee or rate. Null on an order that pays you. In the sandbox the link is on track.sandbox.jenzy.com.

refund
object

Present on a to-bank order that failed after the coins had left. pending — your stablecoin is on its way back; returned — it has been credited to your balance as a collection.

beneficiary
object

To-bank orders only, exactly as you sent it.

funding
object

From-bank orders only, present from awaiting_funds: where to wire your from_amount. Immutable once set.

expires_at
string<date-time>

From-bank orders only: the funding deadline. Past it with no proof the order is expired.