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 mesmo teto diário do aplicativo (janela calendário em São Paulo, 00:00–23:59) e o teto por operação do PIX. Sem teto cadastrado a transferência segue, igual ao app. Retry com a mesma Idempotency-Key não consulta o limite de novo.

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

curl -X POST "https://tenant.api.corpx.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:

Resposta (200):

{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "workflowId": "internal-out-{accountId}-transf-filial-001-int-001",
  "runId": "b7c1f0e2-...",
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "endToEndId": "E50871921202603181530000000001",
  "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
  "status": "COMPLETED",
  "value": 1500.00,
  "description": "Transferência entre filiais",
  "identifier": "transf-filial-001",
  "idempotencyKey": "int-001",
  "completedAt": "2026-03-18T15:30:00Z"
}

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

curl -X POST "https://tenant.api.corpx.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:

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

curl -X POST "https://tenant.api.corpx.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",
    "holderDocument": "12345678000190",
    "holderName": "EMPRESA DESTINO LTDA",
    "value": 250.00,
    "description": "Reembolso",
    "identifier": "reembolso-003"
  }'

Campos:

Qual método escolher?

Conta destino está registrada na API e você tem o Account ID (UUID)?
├── SIM → Use /transfers/internal (mais rápido)
└── NÃO → Você tem agência e número da conta?
    ├── SIM → Use /transfers/internal/by-bank-account
    └── NÃO → Use /transfers/internal/by-document (CPF/CNPJ)

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": "transfer-internal-out-pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "type": "transfer.internal.out",
  "occurredAt": "2026-03-18T15:30:00.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
  "data": {
    "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
    "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "endToEnd": "E50871921202603181530000000001",
    "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
    "direction": "OUT",
    "sourceAccountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
    "sourceTenantId": "tenant-suaempresa",
    "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
    "destinationTenantId": "tenant-suaempresa",
    "amount": 1500.00,
    "description": "Repasse para filial SP",
    "identifier": "transf-filial-001",
    "status": "SUCCESS",
    "source": {
      "providerAccountId": "a1b2c3d4-...",
      "tenantId": "tenant-suaempresa",
      "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
      "name": "SUA EMPRESA LTDA",
      "taxId": "12345678000199"
    },
    "destination": {
      "providerAccountId": "b2c3d4e5-...",
      "tenantId": "tenant-suaempresa",
      "accountId": "773107de-139e-48d1-9462-f4e88f251891",
      "name": "FILIAL SP LTDA",
      "taxId": "98765432000155"
    }
  }
}

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

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

Erros Comuns