Accounts

Request a customer's named fiat account

Creates or returns a customer's named fiat receiving account. The same endpoint serves every currency and rail; which ones can be opened is in Rail.x-ozav-rail-availability.

The customer must already be approved. In sandbox, BRL/BR/pix materializes a simulated account with deterministic Pix and bank-account instructions; no real bank account is opened and no real funds can move. Every corridor OZAV serves uses this same contract, and a corridor OZAV cannot currently open answers a named error rather than a partial account, so your integration learns the outcome from the response instead of from a status label. The public response never exposes the banking venue behind the account.

post/accounts

Request

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

Request body

customer_idstring required

The ozav_cus_ id of the approved customer receiving the account.

account_type'named_fiat_account'

Account kind. API v2 exposes named fiat accounts here.

currency'BRL' | 'USD' | 'EUR' | 'GBP' | 'MXN' required

Account currency. BRL is the first sandbox-active fiat account currency.

countrystring

Account country or region code. BR is active for BRL/Pix sandbox accounts.

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

An account already exists for this customer and was returned idempotently.

idstring required

Opaque account identifier, prefixed ozav_acc_.

object'account' required

Resource type discriminator; always the literal account.

customer_idstring required

The ozav_cus_ id of the owning customer.

account_type'named_fiat_account' required

The only account kind v2 exposes today - a fiat account in the customer's own name. Present so a future kind is additive rather than a breaking change.

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.

countrystring required

ISO 3166-1 alpha-2 country of the account that was actually opened. OZAV picks the banking route, so read this back rather than assuming your request was echoed - see the note on this schema.

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'pending' | 'active' | 'suspended' | 'failed' required

Public lifecycle state for a named account:

pending - opening is in progress or waiting for review.
active - receiving instructions can be shown to the customer.
suspended - account is blocked or deactivated.
failed - opening did not complete.

created_atstring date-time required

When the account record was created (RFC 3339, UTC). Not when it became usable - status and capabilities decide that.

updated_atstring date-time required

When the account record last changed (RFC 3339, UTC).

failure_reasonstring

Present only while status is failed, and only when a reason was recorded. Absent means we did not record one. It never means "a reason exists and we withheld it".

A comma-separated list of codes. Never free text, and never a message written by the underlying institution. Every value is one of:

billing_address, registered_address, company_documents, representatives, representative_address, representative_documents, time_in_business, tax_document, legal_name: the holder still owes us this. Collect it and retry.
counterparty_block: the block is not the holder's paperwork. Sending more documents will not clear it. Contact us.
other_requirement: a reason was recorded that we could not map to a code above. When it appears alongside other codes, the rest of the list is not exhaustive.

Branch on exact values, and treat an unrecognised value the way you treat other_requirement. The list grows. Every value is a member of AccountFailureCode, which carries the full enum.