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 same daily ceiling as the mobile app (São Paulo calendar day, 00:00–23:59) and the per-operation PIX cap. If no ceiling is on file, the transfer proceeds, same as the app. A retry with the same Idempotency-Key does not check the limit again.

There are three ways to identify the destination account:

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

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:

Response (200):

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

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:

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

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:

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

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

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

Common Errors