> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar uma conta bancária

> Cria e conecta uma conta bancária.

Cria uma `payout_account` no cadastro financeiro da organização atuante e conecta
essa conta à organização. Quando já existe uma conta principal no cadastro
financeiro, a nova passa a ser a principal para recebimentos.

**Apenas `bank_code`, `routing_number`, `account_number` e `type` são
obrigatórios. `bank_name` é opcional; quando omitido, a Chargefy tenta usar o
nome retornado pela infraestrutura financeira. O titular da conta é resolvido
automaticamente pela Chargefy — não é input.**

O titular e o documento da conta são resolvidos a partir do cadastro financeiro
da organização. A API não aceita esses campos no payload para evitar cadastrar
contas em nome de terceiros.

<Note>
  A organização precisa ter **concluído o cadastro financeiro** antes de criar
  contas para saques — antes disso a chamada retorna `409`. O endpoint só opera
  em produção: em sandbox retorna `409` com `code: "sandbox_unsupported"`. A
  conta coletada **dentro da ativação** é outra história: essa é simulada
  normalmente em test mode e volta como `payout_account` na organização.
</Note>

## Autenticação

| Credencial             | Acesso                                                   |
| ---------------------- | -------------------------------------------------------- |
| API key da organização | Requer escopo `write` ou `admin`.                        |
| API key da plataforma  | Organização conectada indicada no header `Organization`. |

## Attributes

<ParamField body="bank_code" type="string" required>
  Código do banco.
</ParamField>

<ParamField body="bank_name" type="string">
  Nome do banco. Opcional; use `null` ou omita quando indisponível. A Chargefy
  tenta preencher o nome durante o cadastro e retorna `null` somente quando
  nenhuma fonte confiável o informa.
</ParamField>

<ParamField body="routing_number" type="string" required>
  Agência ou identificador de roteamento.
</ParamField>

<ParamField body="account_number" type="string" required>
  Número completo da conta. Usado apenas para cadastrar a conta; a resposta
  retorna somente `account_number_last4`.
</ParamField>

<ParamField body="type" type="string" required>
  Tipo da conta para saques.

  | Valor      | Descrição       |
  | ---------- | --------------- |
  | `checking` | Conta corrente. |
  | `savings`  | Conta poupança. |
</ParamField>

## O que a Chargefy resolve sozinha

* **`holder_name` e documento do titular** — vêm do cadastro financeiro da
  organização; não são aceitos no payload.
* **Conta principal** — a conta nova substitui a conta principal anterior como
  principal para recebimentos.
* **`bank_name`** — quando omitido, é preenchido a partir da infraestrutura
  financeira quando disponível.

<Warning>
  Tornar a conta principal define o destino cadastrado para os repasses, mas não
  garante o crédito bancário. A organização deve acompanhar o extrato e
  conciliar os recebimentos com as `transactions`.
</Warning>

<RequestExample>
  ```bash Mínimo theme={"theme":"css-variables"}
  curl -X POST "https://api.chargefy.io/v1/payout-accounts" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "account_number": "123455678",
      "bank_code": "001",
      "routing_number": "0001",
      "type": "checking"
    }'
  ```

  ```bash Com bank_name theme={"theme":"css-variables"}
  curl -X POST "https://api.chargefy.io/v1/payout-accounts" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "account_number": "123455678",
      "bank_code": "001",
      "bank_name": "Banco Exemplo S.A.",
      "routing_number": "0001",
      "type": "savings"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto [`payout_account`](/api-reference/payout-accounts/object) completo.

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "id": "pa_oUJ151Lx7Eo64qHG",
    "object": "payout_account",
    "account_number_last4": "5678",
    "bank_code": "001",
    "bank_name": "Banco Exemplo S.A.",
    "created_at": "2026-05-16T14:09:27Z",
    "holder_name": "Acme Ltda",
    "is_active": true,
    "is_verified": false,
    "livemode": true,
    "metadata": {},
    "routing_number": "0001",
    "type": "checking",
    "updated_at": "2026-05-16T14:20:00Z"
  }
  ```
</ResponseExample>

## Webhooks

Criação bem-sucedida emite `payout.account.created` com a `payout_account`
completa. Quando a conta conectada da organização muda, também emite
`organization.updated` com `data.previous_attributes.payout_account`.

## Erros

| Status | `code`                    | Quando                                                                                     |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| `400`  | `invalid_request`         | Payload inválido (`bank_code`, `routing_number`, `account_number` ou `type`).              |
| `401`  | `authentication_failed`   | API key ausente, inválida, revogada ou expirada.                                           |
| `403`  | `permission_denied`       | API key sem acesso à organização ou sem escopo suficiente.                                 |
| `409`  | `sandbox_unsupported`     | Contas para saques ainda não são suportadas no sandbox.                                    |
| `409`  | `resource_state_conflict` | Organização ainda não concluiu o cadastro financeiro ou não permite troca no estado atual. |
| `422`  | `invalid_request`         | Não foi possível resolver o titular da conta.                                              |
| `500`  | `internal_error`          | Erro temporário criando a conta para saques. Faça retry.                                   |
| `502`  | `internal_error`          | Falha temporária cadastrando a conta. Faça retry.                                          |