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 密钥（可选但推荐）

在转账之前，请先查询密钥以验证收款方，并向用户展示详情以供确认：

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/key/12345678901" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

信息

API 在转账时会自动执行密钥查询——事先查询是可选的，但能带来更好的用户体验。结果会缓存 24 小时（使用 ?noCache=true 可强制重新查询 DICT），并按 tenant 策略消耗查询配额。

转账返回的内容

转账响应不会重复返回收款方信息：它返回的是操作结果（status、paymentId、endToEndId）。收款方的姓名和证件号会出现在账单和支付查询中。

第二步：执行转账

通过密钥执行 PIX 转账：

请求

curl -X POST "https://tenant.api.corpx.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 '{
    "amount": 100.00,
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345"
  }'

请求体参数

源账户来自路径（{accountId}），币种固定为 BRL —— 两者都不在请求体中传递。

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

成功响应

HTTP 状态反映结果：200（COMPLETED）、422（FAILED）、202 （TIMEOUT/PENDING —— 不确定，请在重试前查询账单）。

清算行的即时拒绝（反欺诈或清算余额不足）会立即返回 422 FAILED，并填充 errorCode（partner_rejected / insufficient_funds）和 errorReason。被风控拦截分析的转账在查询中显示为 PENDING_APPROVAL，最长等待约 30 分钟才会标记为 TIMEOUT；结果通过 pix.out.completed / pix.out.failed / pix.out.timeout Webhook 送达。

{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202301011234abcdefghijkl",
  "status": "COMPLETED",
  "completedAt": "2026-01-28T15:00:02Z",
  "identifier": "order-12345",
  "workflowId": "pix-out-{accountId}-{identifier}"
}

字段	描述
`paymentId`	内部支付意图 ID（追踪/对账）
`transactionId`	交易 ID
`endToEndId`	BACEN E2E ID（结算后出现）
`status`	`COMPLETED`、`FAILED`、`TIMEOUT`、`PENDING`、`PROCESSING`
`errorCode` / `errorReason`	当 `FAILED` 时填充

错误响应

{
  "errorCode": "insufficient_funds",
  "message": "Saldo insuficiente na conta do liquidante para concluir a operação."
}

（API 返回的消息为葡萄牙语；上例的含义是"清算行账户余额不足，无法完成该操作"。）

同步流程中的超时

若清算行在时间窗口内未确认，API 会返回 202，其中 status 为 "TIMEOUT" 并附带 warning 字段——不存在 207。该笔 PIX 可能已经发出：重试前请先查询账单或支付明细。迟到的结果会通过 Webhook （pix.out.completed / pix.out.failed）送达。

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

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

curl -X POST "https://tenant.api.corpx.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 '{
    "amount": 100.00,
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345-async"
  }'

响应：

{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "workflowId": "pix-out-{accountId}-{identifier}",
  "runId": "b7c1f0e2-...",
  "idempotencyKey": "transfer-order-async-12345",
  "identifier": "order-12345-async",
  "status": "ACCEPTED"
}

202 响应包含指向 /v1/accounts/{accountId}/payments/{identifier} 的 Location 头——该路径是为兼容性保留的别名，会返回 Deprecation 头。规范的查询路由是 GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=。最终结果（成功/失败）会通过 webhook 返回，也可通过 identifier/paymentId 查询。

第三步：查询转账状态

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

请求

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

查询参数

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

*至少需要提供其中一个（endToEndId 或 identifier）。accountId 在路径中传递，而不是查询参数。

成功响应 (200 OK)

本路由返回与账单相同的信封（items[]），包含 0 或 1 条记录。时间戳（timestamp）以巴西利亚时间（-03:00）返回。

{
  "accountId": "{accountId}",
  "source": "live",
  "page": 0,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1,
  "hasNext": false,
  "items": [
    {
      "partnerId": "a697b489-681a-451c-a043-d4ae65be8c80",
      "endToEndId": "E12345678202301011234abcdefghijkl",
      "direction": "OUT",
      "transactionType": "D",
      "operation": "PIX",
      "status": "COMPLETED",
      "amount": -100.00,
      "currency": "BRL",
      "description": "PIX - MARIA DA SILVA",
      "identifier": "order-12345",
      "timestamp": "2026-01-28T15:00:00-03:00",
      "counterParty": {
        "name": "MARIA DA SILVA",
        "document": "123***01",
        "bankCode": "001"
      }
    }
  ],
  "fetchedAt": "2026-01-28T18:00:05Z"
}

提示

如需返回单个对象（而非 items[] 信封），请使用 GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...（或 ?endToEnd=...）。

可能的状态

状态	描述
`COMPLETED`	成功结算
`PROCESSING`	在合作方处理中
`PENDING_APPROVAL`	在内部审批队列中
`FAILED`	失败 / 被拒绝
`REVERSED`	已撤销 / 已退回
`UNKNOWN`	合作方状态超出已知映射

状态流转

结果通过 pix.out.completed / pix.out.failed webhook 送达。若为 TIMEOUT，API 还会发出 pix.out.timeout（状态不确定——请先核对账单；之后仍可能收到迟到的 completed/failed）。
使用相同的 Idempotency-Key 重试的行为取决于上一次的结果：若该笔支付以 FAILED 结束，Key 会被释放，新请求将重新执行支付（自 v2.43.3 起）；若以 TIMEOUT 结束，则不会重发——状态不确定，API 会返回已记录的结果。使用新的 Key 可能导致重复转账。详见幂等性。

提示

请始终保存转账的 identifier 并用它查询状态——这是您自定义的 ID，从创建时即可用且保持稳定（endToEndId 仅在结算后才存在）。

完整示例：Cash Out 脚本

#!/bin/bash

# Configuration
API_URL="https://tenant.api.corpx.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 "{
    \"amount\": $AMOUNT,
    \"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" = "COMPLETED" ]; then
  echo ""
  echo "=== TRANSFER COMPLETED ==="
  echo "Status: $STATUS"
  echo "E2E: $E2E"
  echo "$transfer_response" | jq
else
  echo ""
  echo "=== RESULT ==="
  echo "$transfer_response" | jq
fi

解码二维码

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

curl -X POST "https://tenant.api.corpx.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..."
  }'

响应（动态即付 QR）：

{
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 150.00,
  "originalAmount": 150.00,
  "identifier": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
  "decodeId": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
  "qrCodeType": "dynamic-immediate",
  "qrCodeTypeId": 1,
  "allowChange": false,
  "description": "在线购物",
  "payeeName": "EMPRESA EXEMPLO LTDA",
  "payeeDocument": "12345678000190",
  "bankIspb": "50871921",
  "bankBranch": "0001",
  "bankAccount": "123456-7",
  "accountType": "CHECKING"
}

对于带到期日的账单 QR（dynamic-due-date），响应还会包含金额组成（discount、deduction、interest、penalty）、originalAmount （调整前的面值）、dueDate、paymentDeadline 以及 payeeTradeName （法人实体的商业名）。详见 OpenAPI 中对应示例。

可以在 POST /pix/out/qr-code/async 的请求体中复用 decodeId，以避免在支付时再次执行 decode。

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

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

如果您有 EMV 代码（QR Code 复制粘贴），请使用异步端点（规范路径）：

异步流程（推荐）

POST /v1/accounts/{accountId}/pix/out/qr-code/async — 立即返回 202：

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

响应：

{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "workflowId": "pix-out-{accountId}-{identifier}",
  "runId": "b7c1f0e2-...",
  "idempotencyKey": "pay-qr-async-12345",
  "identifier": "pay-qr-async-12345",
  "status": "ACCEPTED"
}

202 响应包含指向付款查询的 Location 头。最终结果（成功/失败/超时）通过 Webhook（pix.out.completed、pix.out.failed、pix.out.timeout）送达，也可按 identifier/paymentId 查询。

同步端点（已弃用）

已弃用

POST /v1/accounts/{accountId}/pix/out/qr-code（同步）已弃用。为兼容性仍可使用，并返回 Deprecation、Sunset 和 Link 头（计划 sunset：2026-11-21）。请迁移到 /pix/out/qr-code/async。

转账 Webhook

转账完成后，您会收到一个采用规范信封（id、type、occurredAt、 schemaVersion、data）的 webhook：

{
  "id": "evt_out_123",
  "type": "pix.out.completed",
  "occurredAt": "2026-01-28T15:00:02.900Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "{accountId}",
  "data": {
    "endToEnd": "E36741675202601281500001234567",
    "key": {
      "type": "CPF",
      "key": "12345678901"
    },
    "identifier": "order-12345",
    "amount": 100.00,
    "payee": {
      "name": "MARIA DA SILVA",
      "document": "12345678901",
      "bankCode": "001"
    },
    "completedAt": "2026-01-28T15:00:02.900Z"
  }
}

对应的失败事件是 pix.out.failed（data 中包含 error），状态不确定时为 pix.out.timeout。完整字段说明见 Webhooks。

BigPix（已弃用）

已弃用

单笔 R$ 15,000 的交易限额已被移除 — POST /v1/accounts/{accountId}/pix/out 现在单笔交易可接受任意金额。BigPix（将大额拆分为多笔 PIX 转账）已不再需要，现已弃用。

/pix/out/bigpix 和 /pix/out/bank-account/bigpix 端点为保持向后兼容仍然可用，但响应中会返回 Deprecation: true 头。请迁移到 POST /pix/out （或 /pix/out/bank-account）。最终移除日期将提前在更新日志中公布。

常见错误

错误	HTTP	原因	解决方案
`key_not_found`	404	DICT 中不存在该 PIX 密钥	检查密钥及其类型
`invalid_pix_key`	422	密钥格式错误或与所填类型不符	使用：CPF、CNPJ、EMAIL、PHONE、EVP
`insufficient_funds`	422	清算行判定余额不足	检查账户余额
`limit_exceeded_daily` / `limit_exceeded_nightly` / `limit_exceeded_monthly` / `limit_exceeded_transaction`	422	超出对应时间窗口的账户限额	等待窗口重置或申请提额
`partner_rejected`	422	清算行因风控/反欺诈拒绝	查看 `partner` 区块中说明的原因
`policy_denied`	422	tenant/账户的策略规则拒绝了该转账	查看响应体中的 `violations`，并在面板中调整规则 —— 策略与规则

完整的错误码、消息与语义见错误。

备注

在 PIX 转出中重复使用同一个 Idempotency-Key 不会返回 409：API 会返回已记录的结果（若上一次结果为 FAILED，则重新执行）。

最佳实践

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

限额

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

单笔交易不再有固定限额 — 金额仅受账户运营限额约束（请参阅 GET /v1/accounts/{accountId}/pix/limits）。

信息

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

后续步骤

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

概述​

集成流程​

PIX 密钥类型​

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

转账返回的内容​

第二步：执行转账​

请求​

请求体参数​

成功响应​

错误响应​

同步流程中的超时​

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

第三步：查询转账状态​

请求​

查询参数​

成功响应 (200 OK)​

可能的状态​

状态流转​

完整示例：Cash Out 脚本​

解码二维码​

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

异步流程（推荐）​

同步端点（已弃用）​

转账 Webhook​

BigPix（已弃用）​

常见错误​

最佳实践​

限额​

后续步骤​

概述