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.
O valor de saída respeita o teto de internal_out da conta, nas mesmas janelas do PIX, TED e boleto. Sem teto cadastrado a transferência segue. Retry com a mesma Idempotency-Key não consulta o limite de novo. Leitura e pedido de aumento: guia de limites.
Existem três formas de identificar a conta de destino:
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
Campos:
Resposta (200):
Quando a transferência é recusada, o mesmo corpo volta com 422,
status: "FAILED" e os campos errorCode/errorReason preenchidos.
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
Campos:
Quando o documento de destino possui mais de uma conta ativa, endereçar
por documento é ambíguo e a requisição é rejeitada com
409 multiple_destination_accounts. Nesse caso, use
/transfers/internal/by-bank-account (agência + conta) ou
/transfers/internal (destinationAccountId).
3. Transferência por Agência e Conta
Use quando você tem agência e número da conta de destino. Serve para qualquer conta do banco, registrada na API ou não: o liquidante resolve o titular pelo holderDocument.
Endpoint: POST /v1/accounts/{accountId}/transfers/internal/by-bank-account
Campos:
Qual método escolher?
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
Desde a v2.61.0, data.source e data.destination identificam as duas
pontas com nome e CPF/CNPJ — antes o data era plano e só trazia
sourceAccountId / destinationAccountId, o que deixava o recebedor sem saber
de quem era o crédito. Os campos planos continuam no payload.
Quando o destino é conta de outro banco, destination traz name e taxId
(os que você informou na requisição), sem accountId/tenantId. A perna
transfer.internal.in traz o mesmo payload com accountId do destino e
direction: "IN".
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.
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 paymentId e transactionId, que também estão na resposta síncrona. Isso dispensa consultas adicionais ao extrato para fechar a transferência no seu sistema.
A perna transfer.internal.in só é emitida quando a conta de destino também é gerenciada na CorpX; ela repete os mesmos campos (inclusive o identifier definido pelo pagador), mudando apenas accountId e direction.
Prefixos reservados
Os prefixos fee- (tarifas da CorpX) e p2p- (ordens P2P Cripto) são reservados, sem diferenciar maiúsculas: um identifier que comece com eles é recusado com 400 invalid_identifier. Transferências com esses prefixos são criadas só pela CorpX e chegam no extrato e nos webhooks com apresentação própria. As de ordem P2P usam p2p-{orderId} (pagamento), fee-p2p-{orderId} (taxa) e fee-p2p-{orderId}-r (estorno da taxa); veja Extrato e saldo do P2P.
Para receber estes webhooks, inclua transfer.internal.in e/ou transfer.internal.out nos event types da sua subscrição.
Erros Comuns
422 é desfecho, 202 é dúvida
Uma transferência recusada responde 422 com status: "FAILED",
errorCode e errorReason — o dinheiro não saiu e não virá webhook algum.
Repetir com a mesma Idempotency-Key devolve a mesma recusa, sem executar de
novo; para tentar outra vez, use Idempotency-Key e identifier novos.
O 202 com status: "PENDING" significa outra coisa: a chamada foi enviada
e a confirmação não chegou dentro da janela síncrona. Nesse caso consulte o
extrato antes de reemitir — repetir o POST com a mesma Idempotency-Key
reaproveita a operação em curso, mas com chave nova você pode transferir duas
vezes.