--- title: "Deactivate a payout destination" method: POST path: "/payout-destinations/{payout_destination_id}/deactivate" tags: ["Payout Destinations"] --- # Deactivate a payout destination `POST /payout-destinations/{payout_destination_id}/deactivate` ## Request - Base URL: `https://developers.ozav.io/v2` - URL: `https://developers.ozav.io/v2/payout-destinations/{payout_destination_id}/deactivate` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Deactivates a payout destination so it can no longer be used as a transfer destination; existing transfers are unaffected. Idempotent - deactivating an already-inactive destination is a no-op. Returns the `PayoutDestination` with `status: inactive`. Reverse it with the reactivate endpoint. ## Path parameters - `payout_destination_id` string, required ## Response `200` Deactivated. - PayoutDestination: Where a customer's funds land off-ramp - a bank account, PIX key, or other rail endpoint. - `id` string, required: Opaque payout-destination identifier, prefixed `ozav_pd_`. - `object` 'payout_destination', required: Resource type discriminator; always the literal `payout_destination`. - `customer_id` string: The `ozav_cus_` id of the owning customer. - `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. - `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` '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. - `capabilities` PayoutDestinationCapabilities - `receive` boolean, required: Whether OZAV can pay this destination right now. Read this, not `status`. A destination is `active` from the moment you create it, and `status` never says anything about readiness. - A **local BRL/Pix** destination (a Pix key) is paid directly to the key on the domestic rail: `true` as soon as it is `active`, in `live` and in the sandbox. - Any other destination is `true` once it is registered with the settlement venue. While it is `false`, a route that needs that registration is refused with `422 PROVISIONING_REQUIRED`; the stablecoin-to-fiat off-ramp does not need it. `true` does not validate the Pix key itself: a key that does not exist, or whose holder does not match, still fails at payout time. - `account_holder` AccountHolder: The legal owner of a payout-destination account. - `name` string, required: The account holder's legal name. - `type` 'individual' | 'business', required: Whether the account holder is a natural person (`individual`) or a company (`business`). - `tax_id` HolderTaxId: Tax / registration identifier of the **account holder**, who may be a person or a company. The `type` enum is the union of the personal (`cpf`, `ssn`, `nif`, `passport`) and company (`cnpj`, `ein`, `company_number`) identifiers, because a payout destination can be held by either. Use `other` only when none applies - it is the one value that carries no meaning and gets no validation. `cpf` and `cnpj` are checked against their own check digits and rejected with `400` when the number does not add up. - `country` string, required: Issuing country as an ISO 3166-1 alpha-2 code. - `type` 'cpf' | 'cnpj' | 'ssn' | 'ein' | 'nif' | 'company_number' | 'passport' | 'other', required: The kind of identifier carried in `value`: - `cpf` - Brazilian individual taxpayer registry. Check digits are verified. - `cnpj` - Brazilian company registry. Check digits are verified. - `ssn` - US Social Security Number. - `ein` - US Employer Identification Number. - `nif` - Iberian/European tax identification number. - `company_number` - company registry number outside Brazil/US. - `passport` - passport number. - `other` - any identifier not covered above. Carries no meaning and gets no validation. - `value` string, required: The identifier itself. Punctuation is accepted and ignored. - `address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - `details` union: Rail-specific beneficiary details; the applicable schema is selected by `rail`. - object: BRL / PIX payout destination. Provide a reusable PIX key; do not provide a one-time Pix BR Code. - `pix_key` string, required: A PIX key - CPF/CNPJ, email, phone number, or random (EVP) key. - object: USD / fedwire. Older `ach` destinations carry the same shape. - `account_number` string, required: The beneficiary bank account number. - `routing_number` string, required: The 9-digit ABA routing number of the beneficiary bank. - `account_type` 'checking' | 'savings': The bank account type - `checking` or `savings`. - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: EUR / sepa. - `iban` string, required: The beneficiary IBAN. - `bic` string: Optional. The beneficiary bank's SWIFT/BIC code (8 or 11 characters). - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: swift - beneficiary reached by SWIFT wire. This is a payout destination shape; it is not the account-opening corridor of the same name, and `Rail.x-ozav-rail-availability` does not describe it. - `account_number` string, required: The beneficiary account number or IBAN. - `bic` string, required: The beneficiary bank's SWIFT/BIC code. - `intermediary` object: Optional intermediary / correspondent bank details, when the route requires one. - `purpose_of_funds` string: Purpose-of-payment statement required for some cross-border corridors. - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: MXN / spei. - `clabe` string, required: The 18-digit CLABE identifying the beneficiary account. - `bank_name` string: The beneficiary bank's name. Payouts in MXN carry it, so send it. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: GBP / faster_payments - beneficiary reached by UK Faster Payments. This is a payout destination shape; it is not the account-opening corridor of the same name, and `Rail.x-ozav-rail-availability` does not describe it. - `account_number` string, required: The 8-digit UK account number. - `sort_code` string, required: The 6-digit UK sort code. - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: COP / co_transfer. Not offered and not requestable; this is the shape of older destinations that carry it. - `account_number` string, required: The beneficiary bank account number. - `bank_code` string, required: The Colombian bank code identifying the beneficiary bank. - `account_type` string: The account type (e.g. ahorros, corriente). - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: AED / uaefts - the beneficiary account is an IBAN, and the bank is identified by its BIC (the corridor carries no clearing-system code). - `iban` string, required: The beneficiary IBAN. - `bic` string, required: The beneficiary bank's SWIFT/BIC. Required: no clearing system identifies the bank in this corridor. Checked when you register the destination (`BIC_REQUIRED` / `BIC_INVALID`, ISO 9362), not at payment time - a destination that is missing it would otherwise fail after the quote is locked. - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: A domestic account in a corridor with no shape of its own - the account number plus whatever identifies the bank there. Serves `cnaps` (CNY), `nip` (NGN), `cce` (PEN), `rtc` (ZAR) and `eft` (CAD). Japan (`zengin`) has its own shape, `PayoutDestinationDetailsZengin`. **Which of the optional fields a corridor actually needs is the corridor's rule, not this schema's.** Registering a destination that serves one corridor must not be invalidated because another asks for more, so the requirement is enforced when the payment is created, with a named refusal (except `bic` in **PEN**, checked when you register the destination): - `bank_code` - required in **NGN**, checked when you register the destination against the published list of 741 Nigerian bank codes, in the form `RPL:NG::BNK` (for example `RPL:NG:ABNGNGLA:BNK` for Access Bank). An unlisted or missing code is refused with `400 BANK_CODE_UNKNOWN`; the bank's official name is taken from the list. Accepted and unconstrained elsewhere. - `bic` - required in **PEN**, where no clearing system identifies the bank. A missing or malformed one is refused when you register the destination (`400 BIC_REQUIRED` / `400 BIC_INVALID`). - `account_number` alone is enough in **CNY** and **ZAR**. - `account_number` string, required: The beneficiary account number, as the corridor writes it. - `bank_code` string: The identifier of the beneficiary bank in the corridor's own scheme (CNAPS in China, the NIBSS code in Nigeria, the Zengin bank code in Japan). - `branch_code` string: The beneficiary bank branch. - `bic` string: The beneficiary bank's SWIFT/BIC. Required in Peru, and checked when you register the destination. - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - object: A Japanese bank account (`zengin`, JPY). `bank_code` and `branch_code` are required when the payment is created; `bank_code` is checked against the 1,150 Zengin bank codes when you register the destination (`400 BANK_CODE_UNKNOWN`). - `account_number` string, required: The beneficiary account number. - `account_holder_name_kana` string, required: The account holder's name in katakana, as the Japanese bank holds it (for example `スズキ タロウ`). Full or half width; spaces, digits, uppercase Latin letters and `( ) . , - /` are allowed alongside the katakana. A name with no katakana is refused (`400 ACCOUNT_HOLDER_NAME_KANA_INVALID`). - `bank_code` string: The Zengin bank code, 1 to 4 digits. Required to pay. - `branch_code` string: The beneficiary bank branch. Required to pay. - `account_type` 'ordinary' | 'current': `ordinary` for a futsu account, `current` for a toza account. Optional; a destination registered without it is paid as a current account. - `bank_name` string: The beneficiary bank's name. - `bank_address` Address: A postal address. `line1`, `city`, and `country` are required; the rest are optional. Jurisdictions that structure the address (Brazil among them) need it broken out - provide the discrete `number`, `neighborhood`, and (where relevant) `complement` fields, with `line1` then holding the street name alone. Which of these are required to onboard depends on jurisdiction and is reported in `Customer.requirements.missing_fields` (a Brazilian customer needs `line1`, `number`, `neighborhood`, `city`, `state`, and `postal_code`). - `line1` string, required: Street. Where an address is not structured into discrete components, the building number may be included here; when the `number` field is provided, `line1` is the street name alone. - `line2` string: Second address line - unit or suite. Optional. See also `complement`. - `number` string: Building / house number, kept separate from the street. Optional in general; required for Brazilian onboarding. - `neighborhood` string: Neighborhood or district (e.g. Brazilian `bairro`). Optional in general; required for Brazilian onboarding. - `complement` string: Address complement - apartment, block, or reference (e.g. Brazilian `complemento`). Optional. - `city` string, required: City or municipality. - `state` string: State or province - an ISO 3166-2 subdivision code where applicable. - `postal_code` string: Postal or ZIP code. - `country` string, required: Country as an ISO 3166-1 alpha-2 code (e.g. BR, US). - `created_at` string, date-time: When the destination was registered (RFC 3339 / ISO 8601, UTC). - `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)