Payout Destinations

Register a payout destination

One canonical resource for every payout rail. details is a discriminated union keyed by rail. BRL/Pix destinations use a Pix key (details.pix_key). Do not submit a Pix BR code here: BR codes are pay-in instructions for a specific charge, not reusable payout destinations. Rails that require external venue provisioning may still fail closed until enabled.

Which corridor, which rail, which details

A payout destination is a third party you pay. It is not the same thing as a named account you hold at OZAV, and the two do not share a table: Rail.x-ozav-rail-availability is about opening an account, and it does not describe the corridors below. OZAV keeps no nominal account in yen or in rand, and still pays a beneficiary in both.

Currency	rail	details shape	Required in details	Also required by the corridor	Availability
BRL	pix	Pix	pix_key	-	live
USD	fedwire	UsBank	account_number, routing_number	-	live
EUR	sepa	Sepa	iban	-	live
GBP	faster_payments	FasterPayments	account_number, sort_code	a business account holder; an individual is refused with 422 ACCOUNT_HOLDER_TYPE_NOT_SUPPORTED	live
MXN	spei	Spei	clabe	-	live
AED	uaefts	IbanLocal	iban	bic	live
JPY	zengin	Zengin	account_number, account_holder_name_kana	bank_code, branch_code	live
NGN	nip	LocalBank	account_number, bank_code	a contact on the holder	live
PEN	cce	LocalBank	account_number	bic, a contact, postal code and state on the holder, and nationality for an individual	live

Every corridor in the table is live for every organization with access to payouts.

Not currently served for payouts: USD/swift, EUR/swift, CAD/eft, CNY/cnaps and ZAR/rtc. Registering a destination in one of them is refused. ach and co_transfer are not offered and cannot be requested. A GBP destination is registered on faster_payments: swift destinations are USD only. The rail values stay in the enum so records that already carry them keep reading. A corridor enters the table above only when it pays.

"Also required by the corridor" is not required to register. Those fields are enforced when the payment is created, with a refusal that names the field - because a destination that serves one corridor must not be invalidated the day another corridor asks for more. The bank_code values in NGN and JPY come from a closed directory; the refusal carries the accepted list.

account_holder.birth_date is required for every individual beneficiary in the corridors above, and bank_name is required on the rails that have a bank. Both are accepted here.

post/payout-destinations

Request

Base URL
https://developers.ozav.io/v2
Auth
- API key in header X-API-Key
- or HTTP bearer

Headers

Idempotency-Keystring

Optional idempotency key (16-256 characters of [A-Za-z0-9_-]); same semantics as on money-moving operations.

Request body

customer_idstring required

The ozav_cus_ id of the customer this destination belongs to.

currencystring required

Uppercase ISO 4217 code or stablecoin symbol (e.g. BRL, USD, EUR, MXN, USDC, USDT). Uppercase is the canonical form: values are accepted case-insensitively on input but are always uppercase in responses.

The rails a request can name: every value of Rail except ach and co_transfer, which are not offered and appear only on older records.

metadataMetadata

Free-form string map (max 50 keys).

Response

Payout destination registered.

idstring required

Opaque payout-destination identifier, prefixed ozav_pd_.

object'payout_destination' required

Resource type discriminator; always the literal payout_destination.

customer_idstring

The ozav_cus_ id of the owning customer.

currencystring required

Canonical payment-rail vocabulary, shared by named accounts and payout destinations. The table below answers one question: can you open a named account on this rail (machine-readable in x-ozav-rail-availability)? Paying out is a different question, answered by the corridor table in POST /payout-destinations. The two differ: fedwire, for example, is live for payouts, while opening a USD account on it is sandbox only.

Rail	Corridor	Availability
pix	BRL - Brazil instant payments	available
fedwire	USD - US wire	sandbox only
sepa	EUR - SEPA credit transfer	live (behind enablement)
spei	MXN - Mexico SPEI	sandbox only
swift	Cross-border SWIFT	live (behind enablement)
faster_payments	GBP - UK Faster Payments	live (behind enablement)

ach and co_transfer are not offered. Requests for accounts, payout destinations and quotes use RequestRail, which leaves both out, and a fiat_payment source on ach is refused with 422 RAIL_NOT_AVAILABLE. They stay in this enum only because older records carry them.

live (behind enablement) means the corridor is served in production, but not to everyone: opening an account still requires that OZAV has enabled the specific customer for foreign-currency named accounts. Until then a live request is refused with a named error that says which step is missing - not with ACCOUNT_RAIL_NOT_AVAILABLE, which would send you looking at the corridor instead of the customer.

sandbox only is a real, usable state, and not a promise of later. The corridor is fully exercisable with a test key: you can open the account, read its receiving instructions and build against the exact response shape production will return. What it does not have is a settlement partner behind it, so a live key is refused with ACCOUNT_RAIL_NOT_AVAILABLE rather than opening something that cannot receive. Build against it in sandbox; the request you write does not change when the corridor goes live.

status'active' | 'inactive' required

Whether the destination has been deactivated by you:

active - not deactivated.
inactive - deactivated; reactivate it before using it again.

active does not mean the destination is ready to receive a transfer. A newly created destination is active immediately, but stays unusable until OZAV finishes registering it with the settlement rail. Using one before then is refused with 422 PROVISIONING_REQUIRED ("Complete destination registration first"), and no field on this resource distinguishes the two states yet. Until one exists, treat 422 PROVISIONING_REQUIRED as retryable rather than as a bad request, and do not gate your UI on status alone.

created_atstring date-time

When the destination was registered (RFC 3339 / ISO 8601, UTC).