> This page is for BaaS.

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

# Internal Transfers Guide

This guide explains how to perform internal transfers between accounts at the same bank, covering the three available methods and their use cases.

## Overview

Internal transfers move funds between accounts within the same bank, without going through the PIX network. They are processed instantly.

The outbound amount respects the account's `internal_out` ceiling, on the same windows as PIX, TED and boleto. If no ceiling is on file, the transfer proceeds. A retry with the same `Idempotency-Key` does not check the limit again. Read and increase request: [limits guide](/baas/guias/pagar/limites).

There are **three ways** to identify the destination account:

| Method                | Endpoint                              | Destination requirement      | Use case                                |
| --------------------- | ------------------------------------- | ---------------------------- | --------------------------------------- |
| **By Account ID**     | `/transfers/internal`                 | Must have API access enabled | Transfers between your own accounts     |
| **By Document**       | `/transfers/internal/by-document`     | Any account at the bank      | Transfers to any account holder         |
| **By Branch/Account** | `/transfers/internal/by-bank-account` | Any account at the bank      | When you have branch and account number |

## 1. Transfer by Account ID

The most performant method. Use when both source and destination accounts are registered in the 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-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: int-001" \
  -d '{
    "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
    "value": 1500.00,
    "description": "Transfer between branches",
    "identifier": "branch-transfer-001"
  }'
```

**Fields:**

| Field                  | Type          | Required | Description                                                 |
| ---------------------- | ------------- | -------- | ----------------------------------------------------------- |
| `destinationAccountId` | string (UUID) | Yes      | Destination account UUID (API internal ID)                  |
| `value`                | number        | Yes      | Amount in BRL (max 2 decimal places)                        |
| `description`          | string        | No       | Transfer description (max 140 characters)                   |
| `identifier`           | string        | No       | Unique identifier for tracking. Auto-generated when omitted |

**Response (200):**

```json
{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "workflowId": "internal-out-{accountId}-branch-transfer-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 between branches",
  "identifier": "branch-transfer-001",
  "idempotencyKey": "int-001",
  "completedAt": "2026-03-18T15:30:00Z"
}
```

When the transfer is refused, the same body comes back with **422**,
`status: "FAILED"` and the `errorCode`/`errorReason` fields filled in.

## 2. Transfer by Document (CPF/CNPJ)

Use when the destination account is **not registered in the API**. Works for any account in the banking ecosystem.

**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-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: int-002" \
  -d '{
    "document": "12345678000190",
    "value": 500.00,
    "description": "Supplier payment",
    "identifier": "supplier-payment-002"
  }'
```

**Fields:**

| Field         | Type   | Required | Description                                                  |
| ------------- | ------ | -------- | ------------------------------------------------------------ |
| `document`    | string | Yes      | CPF or CNPJ of the destination account holder (numbers only) |
| `value`       | number | Yes      | Amount in BRL                                                |
| `description` | string | No       | Transfer description (max 140 characters)                    |
| `identifier`  | string | No       | Unique identifier for tracking. Auto-generated when omitted  |

> **Document with multiple accounts**
>
> When the destination document has **more than one active account**,
> addressing by document is ambiguous and the request is rejected with
> `409 multiple_destination_accounts`. In that case, use
> `/transfers/internal/by-bank-account` (branch + account number) or
> `/transfers/internal` (`destinationAccountId`).

## 3. Transfer by Branch and Account Number

Use when you have the destination's branch and account number. Works for **any account at the bank**, registered in the API or not: the settlement bank resolves the holder from `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-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: int-003" \
  -d '{
    "branch": "0001",
    "accountNumber": "200038274",
    "holderDocument": "12345678000190",
    "holderName": "DESTINATION COMPANY LTDA",
    "value": 250.00,
    "description": "Refund",
    "identifier": "refund-003"
  }'
```

**Fields:**

| Field            | Type   | Required | Description                                                                              |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `branch`         | string | Yes      | Destination account branch                                                               |
| `accountNumber`  | string | Yes      | Destination account number                                                               |
| `holderDocument` | string | Yes      | CPF/CNPJ of the destination account holder — the settlement bank requires it for routing |
| `holderName`     | string | No       | Destination holder name                                                                  |
| `value`          | number | Yes      | Amount in BRL                                                                            |
| `description`    | string | No       | Transfer description (max 140 characters)                                                |
| `identifier`     | string | No       | Unique identifier for tracking. Auto-generated when omitted                              |

## Which method to choose?

```
Is the destination registered in the API and do you have its Account ID (UUID)?
├── YES → Use /transfers/internal (fastest)
└── NO  → Do you have the branch and account number?
    ├── YES → Use /transfers/internal/by-bank-account
    └── NO  → Use /transfers/internal/by-document (CPF/CNPJ)
```

**Practical examples:**

* **Moving funds between your company's branches** → `/transfers/internal` (by Account ID)
* **Paying a supplier at the bank** → `/transfers/internal/by-document` (by CPF/CNPJ)
* **Transferring to a known account by branch number** → `/transfers/internal/by-bank-account`

## Webhooks

After an internal transfer, both parties receive a webhook:

* **Sender:** `transfer.internal.out`
* **Receiver:** `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-yourcompany",
  "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-yourcompany",
    "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
    "destinationTenantId": "tenant-yourcompany",
    "amount": 1500.00,
    "description": "Transfer to SP branch",
    "identifier": "branch-transfer-001",
    "status": "SUCCESS",
    "source": {
      "providerAccountId": "a1b2c3d4-...",
      "tenantId": "tenant-yourcompany",
      "accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
      "name": "YOUR COMPANY LTDA",
      "taxId": "12345678000199"
    },
    "destination": {
      "providerAccountId": "b2c3d4e5-...",
      "tenantId": "tenant-yourcompany",
      "accountId": "773107de-139e-48d1-9462-f4e88f251891",
      "name": "SP BRANCH LTDA",
      "taxId": "98765432000155"
    }
  }
}
```

Since **v2.61.0**, `data.source` and `data.destination` identify both parties
with name and tax ID — before that the `data` block was flat and carried only
`sourceAccountId` / `destinationAccountId`, which left the receiving side
unable to tell who sent the money. The flat fields are still there.

When the destination is an account at another bank, `destination` carries
`name` and `taxId` (the ones you supplied in the request), without
`accountId`/`tenantId`. The `transfer.internal.in` leg carries the same payload
with the destination `accountId` and `direction: "IN"`.

> **Status on internal transfers**
>
> Because settlement is **atomic and synchronous**, the webhook always arrives with `data.status: "SUCCESS"` — it is the only possible value for `transfer.internal.*`. Failures (insufficient funds, non-existent destination account, blocked account, etc.) are signalled in the HTTP response of the `POST /transfers/internal*` call itself and **never** produce a webhook.

> **Guaranteed reconciliation fields**
>
> The webhook sent **to the payer** (`transfer.internal.out`) carries the same `identifier` and `description` you sent in the request body (`POST /transfers/internal*`), together with the `paymentId` and `transactionId` that are also in the synchronous response. That removes the need for extra statement lookups to close the transfer on your side.
>
> The `transfer.internal.in` leg is only emitted when the destination account is also managed at CorpX; it repeats the same fields (including the `identifier` set by the payer), changing only `accountId` and `direction`.
>
> ### Reserved prefixes
>
> The prefixes `fee-` (CorpX fees) and `p2p-` ([P2P Crypto](/baas/guias/p2p/visao-geral) orders) are reserved, case-insensitive: an `identifier` that starts with them is refused with `400 invalid_identifier`. Transfers with these prefixes are created only by CorpX and show up in the statement and webhooks with their own presentation. P2P order transfers use `p2p-{orderId}` (payment), `fee-p2p-{orderId}` (fee) and `fee-p2p-{orderId}-r` (fee refund); see [P2P statement and balance](/baas/guias/p2p/extrato-e-saldo).

To receive these webhooks, include `transfer.internal.in` and/or `transfer.internal.out` in your subscription event types.

## Common Errors

| HTTP | `errorCode`                             | Cause                                                                                                                               |
| ---- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `missing_fields`                        | Missing required field (`value`, `description`, destination)                                                                        |
| 400  | `invalid_field`                         | More than 2 decimal places, invalid branch, malformed description                                                                   |
| 400  | `invalid_identifier`                    | `identifier` outside the `[A-Za-z0-9._-]` charset, longer than 38 characters, or starting with a reserved prefix (`fee-` or `p2p-`) |
| 404  | `beneficiary_not_found`                 | Destination account does not exist (unknown `destinationAccountId` at CorpX, or a document with no account at the settlement bank)  |
| 422  | `beneficiary_not_active_at_partner`     | Account exists at CorpX, but the settlement bank has no holder yet (accreditation pending)                                          |
| 422  | `beneficiary_incomplete`                | Settlement bank returned a holder without branch/account                                                                            |
| 422  | `recipient_account_not_found`           | Settlement bank could not find the destination account provided                                                                     |
| 409  | `multiple_destination_accounts`         | Document has more than one active account (use `by-bank-account`)                                                                   |
| 409  | `identifier_conflict`                   | A transfer with this `identifier` already exists for this source account                                                            |
| 422  | `insufficient_funds`                    | Available balance does not cover the amount                                                                                         |
| 422  | `balance_reservation_failed`            | Balance exists but could not be reserved (hold, concurrency)                                                                        |
| 422  | `partner_account_disabled`              | Source account disabled at the bank                                                                                                 |
| 422  | `limit_exceeded_transaction`            | Amount above the per-transaction cap (`PIX` / `TRANSACAO`)                                                                          |
| 422  | `limit_exceeded_daily`                  | Remaining daily allowance is not enough (`TRANSFERENCIA_INTERNA` / `DIARIO`). The message carries available, ceiling, and used      |
| 503  | `limits_unavailable`                    | Limit ledger temporarily unavailable                                                                                                |
| 422  | `partner_rejected`                      | Refused by the bank's internal policy. The `partner` block carries the stated reason                                                |
| 502  | `partner_error` / `partner_unavailable` | Error or outage at the bank                                                                                                         |

> **\`422\` is an outcome, \`202\` is a doubt**
>
> A refused transfer answers **`422`** with `status: "FAILED"`, `errorCode` and
> `errorReason` — the money did **not** move and no webhook is coming. Repeating
> with the same `Idempotency-Key` returns the same rejection without running
> again; to try once more, use a new `Idempotency-Key` and a new `identifier`. A **`202`**
> with `status: "PENDING"` means something else: the call went out and
> confirmation did not arrive within the synchronous window. In that case check the
> statement before re-issuing — repeating the POST with the same
> `Idempotency-Key` reuses the in-flight operation, but a fresh key may transfer
> twice.