Criar uma conta bancária

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

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

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

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.

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.

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

string

required

Código do banco.

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.

string

required

Agência ou identificador de roteamento.

string

required

Número completo da conta. Usado apenas para cadastrar a conta; a resposta retorna somente account_number_last4.

string

required

Tipo da conta para saques.

Valor	Descrição
`checking`	Conta corrente.
`savings`	Conta poupança.

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.

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.

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

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

Resposta

200 OK com o objeto payout_account completo.

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

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.

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

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

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

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar uma conta bancária

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Webhooks

Erros

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Resposta

​Webhooks

​Erros

Autenticação

Attributes

O que a Chargefy resolve sozinha

Resposta

Webhooks

Erros