内部转账指南

本指南介绍如何在同一银行的账户之间进行内部转账，涵盖三种可用方法及其使用场景。

概述

内部转账在同一银行的账户之间转移资金，无需通过 PIX 网络。转账即时处理。

有三种方式识别目标账户：

方法	端点	目标账户要求	使用场景
按账户 ID	/transfers/internal	必须启用 API 访问	自有账户间转账
按证件号	/transfers/internal/by-document	银行任意账户	向任何账户持有人转账
按支行/账号	/transfers/internal/by-bank-account	必须启用 API 访问	已知支行和账号时使用

1. 按账户 ID 转账

最高效的方法。当源账户和目标账户都已在 API 中注册时使用。

端点： POST /v1/accounts/{accountId}/transfers/internal

curl -X POST "https://api.corpxapi.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": "分支间转账",
    "identifier": "branch-transfer-001"
  }'

字段：

字段	类型	必填	描述
destinationAccountId	string (UUID)	是	目标账户 UUID（API 内部标识符）
value	number	是	金额（巴西雷亚尔，最多2位小数）
description	string	是	转账描述
identifier	string	否	用于追踪的唯一标识符

响应 (200)：

{
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "destinationAccountId": "773107de-139e-48d1-9462-f4e88f251891",
  "value": 1500.00,
  "status": "COMPLETED",
  "description": "分支间转账",
  "identifier": "branch-transfer-001",
  "createdAt": "2026-03-18T15:30:00Z"
}

2. 按证件号（CPF/CNPJ）转账

当目标账户未在 API 中注册时使用。适用于银行生态系统中的任何账户。

端点： POST /v1/accounts/{accountId}/transfers/internal/by-document

curl -X POST "https://api.corpxapi.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": "供应商付款",
    "identifier": "supplier-payment-002"
  }'

字段：

字段	类型	必填	描述
document	string	是	目标账户持有人的 CPF 或 CNPJ（纯数字）
value	number	是	金额（巴西雷亚尔）
description	string	是	转账描述
identifier	string	否	用于追踪的唯一标识符

3. 按支行和账号转账

当您有支行号和账号时使用。两个账户都必须在 API 中注册。

端点： POST /v1/accounts/{accountId}/transfers/internal/by-bank-account

curl -X POST "https://api.corpxapi.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",
    "value": 250.00,
    "description": "退款",
    "identifier": "refund-003"
  }'

字段：

字段	类型	必填	描述
branch	string	是	目标账户支行号
accountNumber	string	是	目标账号
value	number	是	金额（巴西雷亚尔）
description	string	是	转账描述
identifier	string	否	用于追踪的唯一标识符

如何选择方法？

目标账户是否启用了 API？
├── 是 → 您有账户 ID (UUID) 吗？
│   ├── 是 → 使用 /transfers/internal（最快）
│   └── 否 → 使用 /transfers/internal/by-bank-account
└── 否 → 使用 /transfers/internal/by-document

实际示例：

• 公司分支机构间调拨 → /transfers/internal（按账户 ID）
• 向银行供应商付款 → /transfers/internal/by-document（按 CPF/CNPJ）
• 向已知支行账号转账 → /transfers/internal/by-bank-account

Webhooks

内部转账完成后，双方都会收到 webhook：

• 发送方： transfer.internal.out
• 接收方： transfer.internal.in

{
  "id": "evt_abc123",
  "type": "transfer.internal.in",
  "eventType": "transfer.internal.in",
  "accountId": "773107de-139e-48d1-9462-f4e88f251891",
  "data": {
    "amount": 1500.00,
    "currency": "BRL",
    "status": "SUCCESS",
    "completedAt": "2026-03-18T15:30:00Z",
    "source": {
      "name": "来源公司",
      "taxId": "12345678000100"
    },
    "destination": {
      "name": "目标公司",
      "taxId": "12345678000200"
    }
  }
}

要接收这些 webhooks，请在订阅的事件类型中包含 transfer.internal.in 和/或 transfer.internal.out。

常见错误

状态码	消息	原因
400	destinationAccountId is required	缺少必填字段
400	value must be positive	金额无效
404	destination account not found	未找到目标账户 (by-bank-account)
422	insufficient_balance	源账户余额不足
502	unable to create internal transfer	银行合作方错误