Guia de Transferências Internas

Este guia explica como realizar transferências internas entre contas do mesmo banco, cobrindo os três métodos disponíveis e seus casos de uso.

Visão Geral

Transferências internas movem valores entre contas dentro do mesmo banco, sem passar pela rede PIX. São processadas instantaneamente.

Existem três formas de identificar a conta de destino:

Método	Endpoint	Requisito da conta destino	Caso de uso
Por Account ID	`/transfers/internal`	Deve ter API habilitada	Transferências entre suas próprias contas
Por Documento	`/transfers/internal/by-document`	Qualquer conta do banco	Transferências para qualquer correntista
Por Agência/Conta	`/transfers/internal/by-bank-account`	Deve ter API habilitada	Quando você tem agência e número da conta

1. Transferência por Account ID

O método mais performático. Use quando ambas as contas (origem e destino) estão registradas na API.

Endpoint: POST /v1/accounts/{accountId}/transfers/internal

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/transfers/internal" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: int-001" \
  -d '{
    "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
    "value": 1500.00,
    "description": "Transferência entre filiais",
    "identifier": "transf-filial-001"
  }'

Campos:

Campo	Tipo	Obrigatório	Descrição
`destinationAccountId`	string (UUID)	Sim	Account ID de destino (UUID interno da API)
`value`	number	Sim	Valor em reais (máx. 2 casas decimais)
`description`	string	Sim	Descrição da transferência
`identifier`	string	Não	Identificador único para rastreamento

Resposta (200):

{
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
  "value": 1500.00,
  "status": "COMPLETED",
  "description": "Transferência entre filiais",
  "identifier": "transf-filial-001",
  "createdAt": "2026-03-18T15:30:00Z"
}

2. Transferência por Documento (CPF/CNPJ)

Use quando a conta de destino não está registrada na API. Funciona para qualquer conta do ecossistema bancário.

Endpoint: POST /v1/accounts/{accountId}/transfers/internal/by-document

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/transfers/internal/by-document" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: int-002" \
  -d '{
    "document": "12345678000190",
    "value": 500.00,
    "description": "Pagamento fornecedor",
    "identifier": "pgto-fornecedor-002"
  }'

Campos:

Campo	Tipo	Obrigatório	Descrição
`document`	string	Sim	CPF ou CNPJ do titular da conta destino (somente números)
`value`	number	Sim	Valor em reais
`description`	string	Sim	Descrição da transferência
`identifier`	string	Não	Identificador único para rastreamento

3. Transferência por Agência e Conta

Use quando você tem agência e número da conta. Ambas as contas devem estar registradas na API.

Endpoint: POST /v1/accounts/{accountId}/transfers/internal/by-bank-account

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/transfers/internal/by-bank-account" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: int-003" \
  -d '{
    "branch": "0001",
    "accountNumber": "200038274",
    "value": 250.00,
    "description": "Reembolso",
    "identifier": "reembolso-003"
  }'

Campos:

Campo	Tipo	Obrigatório	Descrição
`branch`	string	Sim	Agência da conta destino
`accountNumber`	string	Sim	Número da conta destino
`value`	number	Sim	Valor em reais
`description`	string	Sim	Descrição da transferência
`identifier`	string	Não	Identificador único para rastreamento

Qual método escolher?

Conta destino tem API habilitada?
├── SIM → Você tem o Account ID (UUID)?
│   ├── SIM → Use /transfers/internal (mais rápido)
│   └── NÃO → Use /transfers/internal/by-bank-account
└── NÃO → Use /transfers/internal/by-document

Exemplos práticos:

Movimentação entre filiais da sua empresa → /transfers/internal (por Account ID)
Pagamento a fornecedor do banco → /transfers/internal/by-document (por CPF/CNPJ)
Transferência para conta conhecida por agência → /transfers/internal/by-bank-account

Webhooks

Após uma transferência interna, ambas as partes recebem um webhook:

Quem enviou: transfer.internal.out
Quem recebeu: transfer.internal.in

{
  "id": "evt_abc123",
  "type": "transfer.internal.out",
  "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
  "data": {
    "transactionId": "internal-9d4a5b7c-1234-4abc-9876-abc123456789",
    "coreId": "9d4a5b7c-1234-4abc-9876-abc123456789",
    "amount": 1500.00,
    "currency": "BRL",
    "status": "SUCCESS",
    "completedAt": "2026-03-18T15:30:00Z",
    "identifier": "transf-filial-001",
    "description": "Repasse para filial SP",
    "source": {
      "name": "EMPRESA ORIGEM LTDA",
      "taxId": "12345678000100",
      "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333"
    },
    "destination": {
      "name": "EMPRESA DESTINO LTDA",
      "taxId": "12345678000200",
      "accountId": "773107de-139e-48d1-9462-f4e88f251891"
    }
  }
}

Status em transferência interna

Como a liquidação é atômica e síncrona, o webhook sempre chega com data.status: "SUCCESS" — é o único valor possível para transfer.internal.*. Falhas (saldo insuficiente, conta destino inexistente, conta bloqueada, etc.) são sinalizadas na própria resposta HTTP da chamada POST /transfers/internal* e nunca geram webhook.

Campos garantidos para reconciliação

O webhook enviado ao pagador (transfer.internal.out) carrega identifier e description idênticos aos que você enviou no corpo da requisição (POST /transfers/internal*), junto com o transactionId que também está na resposta síncrona. Isso dispensa consultas adicionais ao extrato para fechar a transferência no seu sistema.

O webhook enviado ao recebedor (transfer.internal.in) só carrega identifier se o próprio recebedor tiver sido quem originou a transferência em uma chamada anterior (raro). Caso contrário o campo vem ausente.

Para receber estes webhooks, inclua transfer.internal.in e/ou transfer.internal.out nos event types da sua subscrição.

Erros Comuns

Código	Mensagem	Causa
400	`destinationAccountId is required`	Campo obrigatório ausente
400	`value must be positive`	Valor inválido
404	`destination account not found`	Conta destino não encontrada (by-bank-account)
422	`insufficient_balance`	Saldo insuficiente na conta de origem
422	`partner_account_disabled`	A conta de origem está desabilitada no parceiro bancário
422	`partner_limit_exceeded`	Limite de transferência excedido
502	`partner_error`	Erro não classificado no parceiro bancário

Visão Geral​

1. Transferência por Account ID​

2. Transferência por Documento (CPF/CNPJ)​

3. Transferência por Agência e Conta​

Qual método escolher?​

Webhooks​

Erros Comuns​

Visão Geral

1. Transferência por Account ID

2. Transferência por Documento (CPF/CNPJ)

3. Transferência por Agência e Conta

Qual método escolher?

Webhooks

Erros Comuns