Cash Out 指南（PIX 转出）

本指南逐步说明如何通过 PIX 进行转账（cash out），包括事先查询收款方密钥的流程。

概述

Cash Out 允许您通过 PIX 向巴西 PIX 系统中注册的任何密钥转账。推荐流程如下：

查询密钥 - 验证并获取收款方信息
确认信息 - 显示给用户进行确认
执行转账 - 发送 PIX

集成流程

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Look Up    │      │   Confirm   │      │   Execute   │
│    Key      │ ───► │    Details  │ ───► │  Transfer   │
└─────────────┘      └─────────────┘      └─────────────┘
      │                     │                    │
      ▼                     ▼                    ▼
  Name, Bank,           User               E2E generated,
  Account, CPF/CNPJ     Confirms           Webhook sent

PIX 密钥类型

类型	格式	示例
`CPF`	11 位数字	`12345678901`
`CNPJ`	14 位数字	`12345678000199`
`EMAIL`	有效电子邮件	`joao@email.com`
`PHONE`	+55 + 区号 + 号码	`+5511999998888`
`EVP`	UUID	`123e4567-e89b-12d3-a456-426614174000`

第一步：查询 PIX 密钥（可选但推荐）

在转账之前，您可以查询密钥以验证并获取收款方信息。转账响应中会返回预览信息，但事先查询可以让您向用户展示详情以供确认。

信息

API 在转账时会自动执行密钥查询。事先查询是可选的，但推荐使用以获得更好的用户体验。

转账中返回的数据

执行转账（下一步）时，响应中包含收款方信息：

{
  "transactionId": "txn_xyz789abc123",
  "status": "APPROVED",
  "endToEndId": "E36741675202601281500001234567",
  "amount": 100.00,
  "currency": "BRL"
}

字段	描述
`transactionId`	内部交易 ID
`status`	状态：`APPROVED`、`PENDING`、`REJECTED`、`PROCESSING`
`endToEndId`	用于在 BACEN 追踪的 E2E ID

第二步：执行转账

通过密钥执行 PIX 转账：

请求

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer-order-12345" \
  -d '{
    "accountId": "{accountId}",
    "amount": 100.00,
    "currency": "BRL",
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345"
  }'

请求体参数

字段	类型	必填	描述
`accountId`	string	是	源账户 UUID
`amount`	number	是	金额（BRL，例如 100.00）
`currency`	string	是	固定为 `BRL`
`keyType`	string	是	密钥类型：`CPF`、`CNPJ`、`EMAIL`、`PHONE`、`EVP`
`key`	string	是	收款方的 PIX 密钥
`description`	string	否	转账描述（最多 140 个字符）
`identifier`	string	否	集成方提供的标识符，用于追踪和对账。对账完成后会显示在账单中。

成功响应 (202 Accepted)

{
  "transactionId": "txn-abc123-def456",
  "status": "APPROVED",
  "endToEndId": "E12345678202301011234abcdefghijkl",
  "amount": 100.00,
  "currency": "BRL"
}

字段	描述
`transactionId`	内部交易 ID
`status`	`APPROVED`、`PENDING`、`REJECTED`、`PROCESSING`
`endToEndId`	用于在 BACEN 追踪的 E2E ID

错误响应

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

同步流程中的超时与限流

合作方超时（207 partner_timeout）：该笔转账可能已发送；重试前请先查询账单/支付状态。
按账户限流（429 rate_limit_exceeded）：同步端点按账户限流（当前默认 100 req/min，可由策略配置），错误中会返回 currentRateLimit 与 scope。
未来几天计划：同步请求的默认限流将调整为 10 req/min。

异步流程（推荐高并发场景）

使用 POST /v1/accounts/{accountId}/pix/out/async 进行调度，立即返回 202：

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/async" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer-order-async-12345" \
  -d '{
    "accountId": "{accountId}",
    "amount": 100.00,
    "currency": "BRL",
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345-async"
  }'

响应：

{
  "paymentId": "2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "status": "SCHEDULED",
  "scheduled": true
}

最终结果（成功/失败）会通过 webhook 返回，也可通过 paymentId 查询。

第三步：查询转账状态

执行转账后，您可以通过 E2E ID 查询其状态：

请求

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/transactions?endToEndId=E12345678202301011234abcdefghijkl" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

查询参数

参数	类型	必填	描述
`accountId`	string	是	账户 UUID
`endToEndId`	string	是*	交易 E2E ID
`identifier`	string	是*	收款或参考标识符

*至少需要提供其中一个（endToEndId 或 identifier）。

成功响应 (200 OK)

{
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202301011234abcdefghijkl",
  "status": "COMPLETED",
  "type": "CASH_OUT",
  "amount": -100.00,
  "currency": "BRL",
  "description": "PIX - MARIA DA SILVA",
  "transactionDate": "2026-01-28T15:00:00Z",
  "counterparty": {
    "name": "MARIA DA SILVA",
    "document": "123***01",
    "bankCode": "001"
  },
  "balance": 9900.00
}

可能的状态

状态	描述
`COMPLETED`	交易成功完成
`REVERSED`	交易已撤销
`PENDING`	等待处理
`FAILED`	交易失败

提示

请始终保存转账的 endToEndId，以便后续查询状态。

完整示例：Cash Out 脚本

#!/bin/bash

# Configuration
API_URL="https://api.corpxapi.com"
TOKEN="your_token_here"
TENANT_ID="tenant-suaempresa"
ACCOUNT_ID="your_account"

# Transfer details
PIX_KEY="12345678901"
PIX_KEY_TYPE="CPF"
AMOUNT=100.00

echo "=== PIX CASH OUT ==="
echo ""
echo "PIX Key: $PIX_KEY ($PIX_KEY_TYPE)"
echo "Amount: R$ $AMOUNT"
echo ""

# 1. Confirm (in production, wait for user confirmation)
read -p "Confirm transfer? (y/n): " confirm
if [ "$confirm" != "y" ]; then
  echo "Transfer cancelled"
  exit 0
fi

# 2. Execute transfer
echo ""
echo "Executing transfer..."
IDEMPOTENCY_KEY="cashout-$(date +%s)-$RANDOM"

transfer_response=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/pix/out" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{
    \"accountId\": \"$ACCOUNT_ID\",
    \"amount\": $AMOUNT,
    \"currency\": \"BRL\",
    \"keyType\": \"$PIX_KEY_TYPE\",
    \"key\": \"$PIX_KEY\",
    \"description\": \"Transfer via script\"
  }")

# Check result
STATUS=$(echo "$transfer_response" | jq -r '.status')
E2E=$(echo "$transfer_response" | jq -r '.endToEndId')

if [ "$STATUS" = "APPROVED" ]; then
  echo ""
  echo "=== TRANSFER APPROVED ==="
  echo "Status: $STATUS"
  echo "E2E: $E2E"
  echo "$transfer_response" | jq
else
  echo ""
  echo "=== RESULT ==="
  echo "$transfer_response" | jq
fi

解码二维码

在付款前，您可以解码二维码以向用户显示收款方详细信息：

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/qr-code/decode" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{
    "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
  }'

响应：

{
  "amount": 150.00,
  "allowChange": false,
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "beneficiaryName": "EMPRESA EXEMPLO LTDA",
  "beneficiaryType": "LEGAL_PERSON",
  "document": "12345678000190",
  "bankIspb": "12345678",
  "bankAccount": "123456",
  "bankBranch": "0001",
  "accountType": "CHECKING",
  "discount": 0
}

确认后，使用下方的付款端点执行。

扫码支付（通过 EMV 的 PIX 转出）

如果您有 EMV 代码（QR Code 复制粘贴），请使用专用端点：

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/qr-code" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-qr-12345" \
  -d '{
    "accountId": "{accountId}",
    "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000...",
    "description": "QR Code payment"
  }'

对于没有预设金额的静态 QR Code，需要包含 amount 字段：

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/qr-code" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-qr-static-12345" \
  -d '{
    "accountId": "{accountId}",
    "emv": "00020126580014br.gov.bcb.pix...",
    "amount": 150.00,
    "description": "Service payment"
  }'

转账 Webhook

转账完成后，您会收到一个 webhook：

{
  "event": "pix.out.completed",
  "timestamp": "2026-01-28T15:00:02Z",
  "data": {
    "transactionId": "txn_xyz789abc123",
    "status": "COMPLETED",
    "value": 100.00,
    "endToEndId": "E36741675202601281500001234567",
    "recipient": {
      "name": "MARIA DA SILVA",
      "document": "12345678901"
    }
  }
}

BigPix（大额转账）

对于超过单笔限额（默认 R$15,000）的转账，请使用 BigPix 端点。

重要： BigPix 现在始终为异步。
POST /v1/accounts/{accountId}/pix/out/bigpix 仅负责调度处理（与 /pix/out/async 行为一致），并返回 202 与 paymentId。

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/bigpix" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "recipient@email.com",
    "keyType": "EMAIL",
    "amount": 47500.00,
    "description": "Supplier payment",
    "identifier": "PAY-001"
  }'

常见错误

错误	原因	解决方案
`key_not_found`	PIX 密钥不存在	检查密钥及其类型
`insufficient_balance`	余额不足	检查账户余额
`invalid_key_type`	无效的密钥类型	使用：CPF、CNPJ、EMAIL、PHONE、EVP
`transfer_limit_exceeded`	超过每日限额	等待或申请提高限额
`409 Conflict`	重复的 Idempotency Key	使用不同的 key

最佳实践

转账前始终查询密钥 以验证收款方信息
在执行前与用户确认 详细信息
每笔转账使用唯一的 Idempotency Key
保存 E2E 用于追踪和技术支持
配置 webhooks 以接收异步确认
实施重试机制 对临时故障使用指数退避

限额

类型	默认限额
单笔交易	R$ 50,000.00
每日	R$ 100,000.00
每月	无限制

信息

限额可以自定义。如需更多信息，请联系技术支持。

后续步骤

退款指南 - 撤销已收到的转账
Webhooks - 配置通知
错误码 - 完整的错误码列表

概述​

集成流程​

PIX 密钥类型​

第一步：查询 PIX 密钥（可选但推荐）​

转账中返回的数据​

第二步：执行转账​

请求​

请求体参数​

成功响应 (202 Accepted)​

错误响应​

同步流程中的超时与限流​

异步流程（推荐高并发场景）​

第三步：查询转账状态​

请求​

查询参数​

成功响应 (200 OK)​

可能的状态​

完整示例：Cash Out 脚本​

解码二维码​

扫码支付（通过 EMV 的 PIX 转出）​

转账 Webhook​

BigPix（大额转账）​

常见错误​

最佳实践​

限额​

后续步骤​

概述