> ## 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.

# Create a Bank Account

> Cria e conecta uma conta bancária.

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

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.

## Autenticação

| Credencial             | Acesso                                                   |
| ---------------------- | -------------------------------------------------------- |
| JWT de usuário         | Requer acesso à organização.                             |
| 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.
</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: `checking` ou `savings`.
</ParamField>

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

## Resposta

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

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "ba_123",
    "object": "bank_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 `bank.account.created` com a `bank_account`
completa. Quando a conta conectada da organização muda, também emite
`organization.updated` com `data.previous_attributes.bank_account`.

## Erros

| Status | Quando                                                                                                            |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `400`  | Payload inválido (`bank_code`, `routing_number`, `account_number` ou `type`).                                     |
| `401`  | Credencial ausente, inválida, revogada ou expirada.                                                               |
| `403`  | Credencial sem acesso à organização ou sem escopo suficiente.                                                     |
| `409`  | Organização ainda não concluiu o cadastro financeiro, não permite troca no estado atual ou sandbox não suportado. |
| `422`  | Não foi possível resolver o titular da conta a partir do cadastro financeiro.                                     |
| `500`  | Erro temporário criando a conta bancária. Faça retry.                                                             |
| `502`  | Falha temporária cadastrando a conta. Faça retry.                                                                 |