Skip to main content
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"
  }'

{
  "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"
}
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

CredencialAcesso
JWT de usuárioRequer acesso à organização.
API key da organizaçãoRequer escopo write ou admin.
API key da plataformaOrganização conectada indicada no header Organization.

​
Attributes

​
bank_code
string
required
Código do banco.
​
bank_name
string
Nome do banco. Opcional; use null ou omita quando indisponível.
​
routing_number
string
required
Agência ou identificador de roteamento.
​
account_number
string
required
Número completo da conta. Usado apenas para cadastrar a conta; a resposta retorna somente account_number_last4.
​
type
string
required
Tipo da conta: checking ou savings.
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"
  }'

​
Resposta

200 OK com o objeto bank_account completo. 
{
  "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"
}

​
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

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