Price and send in one call

post

https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payouts

The endpoint to build on. It prices and sends in a single request,
which is what makes a retry safe: the body you send is the body you can
send again. Pricing separately and then sending means a retry re-prices,
produces a different request, and the Idempotency-Key meant to protect
the retry conflicts with itself instead.

Pass expectDestination — the amount you told the payer they would
receive. If the binding quote has moved further than maxDriftBps from
it, we refuse and nothing is sent.

If this times out the outcome is unknown and the payout may exist.
Retry with the same Idempotency-Key.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

orgId

string

required

length ≥ 1

The opaque organization id issued to you, normally CUID-shaped (for
example cmsx…). It is not an org_-prefixed alias. Pass it unchanged
in every organization-scoped path.

Body Params

amount

string

required

^\d+(\.\d{1,2})?$

How much, as a decimal string. What you SEND by default; what
the beneficiary RECEIVES, in their currency, when amountLeg
is destination.

destinationAccountId

string

required

length ≥ 1

From the beneficiary's paymentMethods[0].

amountLeg

string

enum

Defaults to source

Which side of the payout amount describes.

source takes every fee out of what you sent, so the
beneficiary receives less than the figure you named.

destination pays them that figure exactly, in THEIR
currency, and adds the fees to your debit instead — naming
3400 MXN on a live corridor debited 201.879397 USDC and paid
out 3400.00.

source_net keeps the figure in YOUR currency but means it
the same way: "send them $200 worth". We convert at the
market rate published by GET /rates and lock that
destination, so the fees land on your debit. Naming 200 USD
on a live corridor paid out 3426.81 MXN and debited
203.447236 — the fees, plus the difference between the market
rate we quoted you and the rate the network executed at.

The two locking modes need capabilities.exactOutput on the
corridors call; elsewhere they are refused with
EXACT_OUTPUT_UNSUPPORTED rather than quietly pricing the
other side.

Allowed:

expectDestination

string

^\d+(\.\d{1,6})?$

What you told the payer they would receive. Omit it and you
send at whatever the market did between quoting and sending.

maxDriftBps

integer

0 to 10000

Defaults to 200

Tolerated drift in basis points. Defaults to 200 (2%).

reference

string

length between 1 and 128

^[A-Za-z0-9 :._-]*$

Your payment reference. Echoed back and searchable.

purposeOfPayment

string

endUser

object

Who you are paying on behalf of. Attribution only — it is not forwarded
to the payment network and does not change the sender of record, which
stays your organization. Echoed on the payout and in every webhook, so a
support question is answerable without your own id map.

Headers

Idempotency-Key

string

required

length between 1 and 255

^[A-Za-z0-9_.:-]+$

A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.

Reuse it to retry. Same key with the same body replays the stored
response; same key with a different body is a 409, because
answering with the first call's result would hand you a receipt for a
payout you did not request. A 4xx releases the key, so you can fix the
body and reuse it.

Reuse it — do not generate one per attempt. A key minted per attempt
defeats replay entirely: every retry looks like a new request, so every
retry pays. We also watch for an identical body arriving under a
different key within 15 minutes and refuse it with
DUPLICATE_REQUEST_DETECTED.

Records are kept for 7 days. That is a retention window, not a
correctness one — there is no path where an expired key is re-executed.

X-Allow-Duplicate

string

enum

Set to true to send a request that is byte-identical to one you sent
seconds ago under a different key. Only set it deliberately: it switches
off the guard that catches a retry arriving under a fresh key.

Allowed:

Responses

200The payout. A replayed idempotent request returns the original and sets the Idempotency-Replayed response header.

400Validation, an underfunded balance, or the drift guard refusing. RATE_DRIFT_EXCEEDED and QUOTE_UNVERIFIABLE both mean nothing was sent — re-quote and send again.

401Missing, invalid, or revoked key — or a key on a route that does not accept one.

403Valid key, wrong organization.

409Either the key was reused with a different body, or an identical request is still in flight. The second is safe to retry after a backoff; the first means you should use a new key.