--- title: "Pay out from a named account to a payout destination" method: POST path: "/accounts/{account_id}/payouts" tags: ["Accounts"] --- # Pay out from a named account to a payout destination `POST /accounts/{account_id}/payouts` ## Request - Base URL: `https://developers.ozav.io/v2` - URL: `https://developers.ozav.io/v2/accounts/{account_id}/payouts` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Sends fiat from the customer's own named account to one of that customer's registered payout destinations, in the account's currency. No conversion happens on this endpoint: the destination must be in the same currency as the account (use `POST /transfers` to convert first). The payment leaves **the customer's account**, with the customer as the sender of record. It is refused, with a named code, when the account cannot send yet or the customer who owns it is not approved and active (`422 ACCOUNT_NOT_READY`, with the exact reason in `details.reason`), when a compliance hold applies to that customer (`403 COMPLIANCE_HOLD`), when the customer profile lacks fields the payment rail requires (`422 ACCOUNT_PAYOUT_SENDER_INCOMPLETE`), when the destination belongs to a different customer (`422 PAYOUT_DESTINATION_NOT_OWNED`) or lacks data the rail requires (`422 PAYOUT_DESTINATION_INCOMPLETE`), when the amount is above the per-payout limit for your organization (`422 ACCOUNT_PAYOUT_ABOVE_LIMIT`), or when the account's available balance does not cover it - payouts still in flight count (`422 ACCOUNT_BALANCE_INSUFFICIENT`). Payouts from named accounts are enabled per organization: until yours is, the endpoint answers `403 ACCOUNT_PAYOUT_NOT_ENABLED`. **BRL by Pix key.** A BRL account pays only to an account of the same holder: the destination document must be the account holder's (`422 PAYOUT_DESTINATION_HOLDER_MISMATCH`). Before anything is sent, OZAV asks the Central Bank of Brazil who owns the Pix key, with the same codes `POST /transfers` uses: a key of someone else is refused (`422 DESTINATION_PIX_KEY_HOLDER_MISMATCH`), a key that does not exist too (`422 DESTINATION_PIX_KEY_NOT_FOUND`), and when the check cannot be completed the payout is refused with `503 PAYOUT_DESTINATION_HOLDER_UNVERIFIABLE` - nothing was sent, and retrying the same request later is safe; if it keeps failing, the Central Bank's answer for that key does not show the holder's document, so pay to another key of the same holder. Unlike `POST /transfers`, a key whose holder cannot be confirmed is never paid here. The destination needs the holder's document (`422 PAYOUT_DESTINATION_INCOMPLETE` without it). Where the Pix-key check is not available for the account, Pix-key payouts answer `403 ACCOUNT_PAYOUT_NOT_ENABLED`. Repeating a payout that already went out returns it with `200` before any of these checks, and before the destination is checked again. **`reference` is the idempotency lever.** Repeating a request with the same `reference` and `amount` for the same account returns the existing payout with `200` instead of sending a second payment. The destination is not part of that match: the `200` shows the destination the existing payout went to, even when the repeated request names another one. It also travels to the receiving bank as the remittance information. ## Path parameters - `account_id` string, required ## Request body - AccountPayoutCreateRequest: A payment out of the customer's own named account, in the account's currency, to one of the customer's registered payout destinations. - `amount` string, required: Decimal string with exactly two fractional digits (`"50.00"`). Never a float. - `destination` object, required - `type` 'payout_destination', required - `payout_destination_id` string, required: The `ozav_pd_` id of a destination registered for the same customer, in the same currency as the account. - `reference` string, required: 1-35 characters (letters, digits, space, `.`, `_`, `/`, `-`). Your idempotency lever: the same `reference` with the same `amount` on the same account is the same payout. Also sent to the receiving bank as remittance information. - `purpose` string: Optional purpose code or short description, passed to the payment institution when the rail carries one. - `metadata` Metadata: Free-form string map (max 50 keys). ## Response `200` The same payout already existed (same `reference` and `amount`); nothing was sent again. - AccountPayout: A payment sent out of a customer's named account. `status` follows the payment institution: `accepted` means the order was taken, not that the money arrived; `settled` means it did; `rejected` is final; `pending` means the institution has not classified the outcome yet - read the account's `/movements` rather than assuming either way. - `id` string, required: Opaque payout id, prefixed `ozav_apo_`. Stable for the same `reference` and `amount`. - `object` 'account_payout', required - `account_id` string, required: The `ozav_acc_` id the money left. - `destination` object, required - `type` 'payout_destination', required - `payout_destination_id` string, required - `amount` string, required: Decimal string with two fractional digits. - `currency` string, 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. - `reference` string, required - `status` 'pending' | 'accepted' | 'settled' | 'rejected', required - `purpose` string - `metadata` Metadata, required: Free-form string map (max 50 keys). ## Other responses - `201`: Payout accepted by the payment institution and recorded. - `400`: The request is invalid. - `401`: Missing or invalid API key. - `403`: The organization lacks the entitlement (code ENTITLEMENT_REQUIRED) or the key lacks the scope (code INSUFFICIENT_SCOPE). On money-moving requests (POST /transfers, POST /wallets/{wallet_id}/transfers) a compliance hold on the customer answers with code COMPLIANCE_HOLD: the hold is reviewed and lifted on OZAV's side; retrying does not clear it. When the only hold is a pause until pending onboarding documents are received, a withdrawal answers CUSTOMER_DOCUMENTS_PENDING instead: send what `requirements` on GET /customers/{id} lists; OZAV lifts the pause after reviewing it. On OZAV Services (live without the platform's KYB), any API outside decisions, screenings, lists and self-custody wallets answers with code PRODUCTION_NOT_ACTIVATED. - `404`: The resource does not exist, is not visible to the caller, or the id was malformed for this position (see "Resource ids" under Errors). These share one status; `code` and `message` tell them apart. - `422`: The request is well-formed but cannot be fulfilled - e.g. a `rail` that is not served (see `Rail.x-ozav-rail-availability`). - `502`: The payment institution did not accept the order (`ACCOUNT_PAYOUT_DISPATCH_FAILED`). Nothing left the account; read `GET /accounts/{account_id}/movements` before retrying. - `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one. --- [API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)