Skip to main content
POST
Create a payout

Authorizations

Authorization
string
header
required

Your Jenzy API key: Authorization: Bearer jz_live_…

Headers

Idempotency-Key
string
required

Required. A key you mint per payout 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
amount
required

What the beneficiary receives, in asset. Fees are on top, in source_asset.

Example:

"10000.00"

asset
string
required

The asset the beneficiary receives.

Minimum string length: 1
Example:

"USDC"

destination
object
required
source_asset
string

The asset you pay from. Defaults to asset. A USD payout pays from USDC; any other pair is unsupported_pair.

Minimum string length: 1
Example:

"USDC"

invoice_document_id
string<uuid>

Only on a USD payout: the id of an invoice you uploaded with POST /v2/documents. Required when the USD beneficiary is a third party (invoice_required). One invoice justifies one payout.

Response

Created. status is normally pending; it can be held (the payment network has not yet acknowledged — poll) or already failed.

id
string<uuid>
required

Payout id — your handle for polling and support.

status
enum<string>
required

Lifecycle: held (money reserved, the payment network has not yet acknowledged) → pending → succeeded | failed. succeeded, failed and reversed are terminal. A payout may already be failed in its creation response: the destination was accepted but the payment network refused it at once, and the reserved money is released. reversed means the payout succeeded and was then clawed back — it is not a failure and carries no failure object.

Available options:
received,
validated,
held,
submitted,
pending,
succeeded,
failed,
reversed
Example:

"pending"

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:

"USDC"

amount
string
required

What the beneficiary receives, as an exact decimal string in asset.

Example:

"10000.00"

source_asset
string
required

What you paid from.

Minimum string length: 1
Example:

"USDC"

source_amount
string
required

What is debited from your source_asset balance for the beneficiary amount; equals amount when the assets are the same. Your fee is on top.

Example:

"10000.00"

fee
string
required

Jenzy’s payout fee, one total, in source_asset. Known at creation. On a USD payout: the all-in fee, everything beyond amount.

Example:

"0.8"

rate
string | null
required

source_amount ÷ amount at 8 decimal places — source_asset per 1 asset — when the assets differ; null otherwise. Informational: the two amounts are the contract.

Example:

null

destination
object
required
failure
object | null
required

Set only when status is failed: one of the published codes with its fixed message. Detail from the payment network is never included.

created_at
string<date-time>
required
terminal_at
string<date-time> | null
required

When the payout reached succeeded, failed or reversed; null while in flight.

receipt_url
string<uri> | null
required

The public link to the receipt of a USD payout to a saved beneficiary. Send it to your beneficiary: the page shows the status of the payment, not your fee or rate. Null for every other payout. In the sandbox the link is on track.sandbox.jenzy.com.

tx_hash
string | null
required

The on-chain hash of a wallet payout: an Ethereum transaction hash or a Solana signature. Set while the payout is pending, from the first read that has it, so you can follow the transfer on a block explorer. Null before Hermes has the hash, and for each payout that is not a wallet payout.

Example:

null