--- title: "Deactivate a sandbox account" method: POST path: "/accounts/{account_id}/deactivate" tags: ["Accounts"] --- # Deactivate a sandbox account `POST /accounts/{account_id}/deactivate` ## Request - Base URL: `https://developers.ozav.io/v2` - URL: `https://developers.ozav.io/v2/accounts/{account_id}/deactivate` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Suspends a sandbox BRL/Pix account so you can test inactive-account handling. Live account lifecycle changes remain gated until the operating procedure for your organization is enabled. ## Path parameters - `account_id` string, required ## Response `200` Account deactivated. - Account: A customer-owned named fiat account. The account id is OZAV-owned and remains stable. `currency`, `country` and `rail` describe the account that was actually opened, which may differ from the values in your request. OZAV selects the banking route, and the receiving coordinates decide the rail: an account reachable by IBAN is not reachable by the same instructions as one reachable by a domestic account number. Read these three fields from the response rather than assuming your request was echoed back, and publish `receiving_instructions` to your payers exactly as returned. - `id` string, required: Opaque account identifier, prefixed `ozav_acc_`. - `object` 'account', required: Resource type discriminator; always the literal `account`. - `customer_id` string, 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. - `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. - `country` string, 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. - `rail` 'pix' | 'ach' | 'fedwire' | 'sepa' | 'spei' | 'swift' | 'faster_payments' | 'co_transfer' | 'uaefts' | 'eft' | 'cnaps' | 'zengin' | 'nip' | 'cce' | 'rtc', 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` '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. - `holder` object, required: Who the account is in the name of. Taken from the customer record, not from this request - the account cannot be opened in a name the customer has not been verified under. - `name` string, required: The legal holder name. - `type` 'individual' | 'business', required: Mirrors the owning customer's type; a business customer's account is held in the company name, an individual's in the person's. - `receiving_instructions` AccountReceivingInstructions, required: Rail-specific instructions to receive funds into this customer account. - `pix` AccountPixInstructions - `key` string, required: Pix key customers can use to receive BRL into this account. - `key_type` 'cpf' | 'cnpj' | 'email' | 'phone' | 'random' | 'evp', required: What kind of Pix key `key` is. Payer apps validate the key against its type, so publish the pair together - a correct key presented as the wrong type is refused. - `bank_account` AccountBankInstructions - `bank_name` string: Bank or payment institution name, when assigned. - `branch` string: Branch number, when assigned. - `account_number` string: Account number, including check digit when assigned. - `routing_number` string: Domestic routing number for supported rails such as FedWire. - `iban` string: IBAN for supported rails such as SEPA. - `bic` string: BIC or SWIFT code, when assigned. - `sort_code` string: UK sort code (six digits, usually shown as `00-00-00`). Present on `faster_payments` accounts. - `clabe` string: Mexican CLABE - 18 digits, including its own check digit. Present on `spei` accounts. - `bre_b_key` string: Colombian Bre-B key (the payer-facing alias). Present on `co_transfer` accounts. - `account_type` 'payment': The account category to state on a transfer form. `payment` is a payment account (conta de pagamento), which some payer flows require to be selected explicitly instead of checking or savings. - `capabilities` AccountCapabilities, required - `receive` boolean, required: Whether this account can currently receive on its configured rail. - `send` boolean, required: Whether this account can currently initiate sends on its configured rail through API v2. - `balance` AccountBalance, required: A balance reading mirrored from the institution that holds the account. Amounts are decimal strings in the account currency's own precision (two decimals for USD, EUR, GBP and BRL). Never a JSON number. - `available` string, required: The balance available at `as_of`, as a decimal string (`"965.00"`). - `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. - `as_of` string, date-time, required: When OZAV took this reading (RFC 3339, UTC). Readings refresh every few minutes; a payment received after this instant is not yet reflected. - `created_at` string, date-time, required: When the account record was created (RFC 3339, UTC). Not when it became usable - `status` and `capabilities` decide that. - `updated_at` string, date-time, required: When the account record last changed (RFC 3339, UTC). - `pending_action` object: Present only while `status` is `pending`, and only when something is actually being waited on from the holder. `url` is omitted when the verification link cannot be verified as belonging to the institution that holds the account, in which case the action is still reported so the holder knows verification is outstanding. - `type` 'complete_verification', required: What is being waited on. `complete_verification` - the holder must finish a verification step, at `url` when one could be published. - `url` string, uri: Verification webview for the account holder. HTTPS, on a host of the institution that holds the account. - `failure_reason` string: 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. - `metadata` Metadata: Free-form string map (max 50 keys). ## Other responses - `401`: Missing or invalid API key. - `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. --- [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)