> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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](/baas/guias/pagar/limites).

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` | Qualquer conta do banco    | 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`

```bash
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:**

| 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        | Não         | Descrição da transferência (máx. 140 caracteres)                         |
| `identifier`           | string        | Não         | Identificador único para rastreamento. Gerado automaticamente se omitido |

**Resposta (200):**

```json
{
  "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`

```bash
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:**

| 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 | Não         | Descrição da transferência (máx. 140 caracteres)                         |
| `identifier`  | string | Não         | Identificador único para rastreamento. Gerado automaticamente se omitido |

> **Documento com múltiplas contas**
>
> 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`

```bash
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:**

| Campo            | Tipo   | Obrigatório | Descrição                                                                         |
| ---------------- | ------ | ----------- | --------------------------------------------------------------------------------- |
| `branch`         | string | Sim         | Agência da conta destino                                                          |
| `accountNumber`  | string | Sim         | Número da conta destino                                                           |
| `holderDocument` | string | Sim         | CPF/CNPJ do titular da conta destino — o liquidante exige o documento para rotear |
| `holderName`     | string | Não         | Nome do titular destino                                                           |
| `value`          | number | Sim         | Valor em reais                                                                    |
| `description`    | string | Não         | Descrição da transferência (máx. 140 caracteres)                                  |
| `identifier`     | string | Não         | Identificador único para rastreamento. Gerado automaticamente se omitido          |

## 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`

```json
{
  "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"`.

> **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 `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](/baas/guias/p2p/visao-geral)) 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](/baas/guias/p2p/extrato-e-saldo).

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

## Erros Comuns

| HTTP | `errorCode`                             | Causa                                                                                                                          |
| ---- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 400  | `missing_fields`                        | Campo obrigatório ausente (`value`, `description`, destino)                                                                    |
| 400  | `invalid_field`                         | Valor com mais de 2 casas decimais, agência inválida, descrição fora do formato                                                |
| 400  | `invalid_identifier`                    | `identifier` fora do charset `[A-Za-z0-9._-]`, acima de 38 caracteres ou começando com um prefixo reservado (`fee-` ou `p2p-`) |
| 404  | `beneficiary_not_found`                 | Conta destino não existe (`destinationAccountId` desconhecido na CorpX ou documento sem conta no liquidante)                   |
| 422  | `beneficiary_not_active_at_partner`     | Conta existe na CorpX, mas o liquidante ainda não tem o titular (credenciamento pendente)                                      |
| 422  | `beneficiary_incomplete`                | Liquidante devolveu o titular sem agência/conta                                                                                |
| 422  | `recipient_account_not_found`           | Liquidante não encontrou a conta destino informada                                                                             |
| 409  | `multiple_destination_accounts`         | Documento com mais de uma conta ativa (use `by-bank-account`)                                                                  |
| 409  | `identifier_conflict`                   | Já existe transferência com esse `identifier` nesta conta de origem                                                            |
| 422  | `insufficient_funds`                    | Saldo disponível não cobre o valor                                                                                             |
| 422  | `balance_reservation_failed`            | Saldo existe mas não pôde ser reservado (bloqueio, concorrência)                                                               |
| 422  | `partner_account_disabled`              | Conta de origem desabilitada no banco                                                                                          |
| 422  | `limit_exceeded_transaction`            | Valor acima do teto por transação (`PIX` / `TRANSACAO`)                                                                        |
| 422  | `limit_exceeded_daily`                  | Restante do dia insuficiente (teto `TRANSFERENCIA_INTERNA` / `DIARIO`). A mensagem traz disponível, teto e usado               |
| 503  | `limits_unavailable`                    | Cadastro de limite temporariamente indisponível                                                                                |
| 422  | `partner_rejected`                      | Recusa por política interna do banco. O bloco `partner` traz o motivo informado                                                |
| 502  | `partner_error` / `partner_unavailable` | Erro ou indisponibilidade no banco                                                                                             |

> **\`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.