发起 PIX 付款（Cash-Out）
POST /api/pix/cash-out
POST https://<api-host>/api/pix/cash-out需要在 Authorization 头中提供 Bearer token。请参阅 生成令牌 获取。
向目标 PIX 密钥发送 PIX 付款。交易创建后状态为 PENDING，最终结果将通过 webhook 通知，或可通过轮询查询。
认证
需要在 Authorization 请求头中提供 Bearer 令牌。
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
value | number | 是 | 金额（巴西雷亚尔，最多 2 位小数）。最小值：0.01 |
externalId | string | 是 | 每个账户唯一的外部标识符（最多 50 个字符） |
description | string | 否 | 交易描述（最多 140 个字符） |
details | object | 是 | 目标 PIX 密钥信息 |
details.key | string | 是 | 目标 PIX 密钥（格式见下表） |
details.keyType | string | 是 | 密钥类型：DOCUMENT、EMAIL、PHONE、RANDOM。必填，因为 API 不会查询 DICT |
details.name | string | 否 | 密钥持有人姓名（最多 100 个字符）。部分清算机构要求提供：建议始终发送 |
details.document | string | 否 | 密钥持有人的有效 CPF（11 位数字）或 CNPJ（14 位数字），仅数字。部分清算机构要求提供：建议始终发送。API 仅校验格式；参见按清算机构划分的持有人核验 |
details.checkPixKeyWithDocument | boolean | 否 | 为 true 时，要求核验密钥是否属于 details.document 中的 CPF/CNPJ，不一致则拒绝付款。必须同时提供 details.document（否则 API 返回 400）。仅在支持该核验的清算机构上生效。默认：false |
details.key 的格式要求
keyType | 格式 | 示例 |
|---|---|---|
DOCUMENT | CPF：11 位数字 / CNPJ：14 位数字（仅数字） | 12345678909、12345678000195 |
EMAIL | 有效的电子邮件地址 | usuario@exemplo.com |
PHONE | 区号 + 号码（10-11 位数字，不含国际区号 +55） | 11999999999 |
RANDOM | UUID（可带或不带连字符） | a1b2c3d4-e5f6-4890-abcd-ef1234567890 |
付款始终按 PIX 密钥（details.key）寻址。 Gateways API 会校验 details.document 的格式，但在发送前不会将其与 details.key 比对，也不会查询 DICT。与密钥真实持有人的比对取决于您账户的清算机构（部分清算机构还取决于 details.checkPixKeyWithDocument）。未进行该核验时，不一致的 details.document 不会拦截付款：资金将进入密钥持有人账户。参见按清算机构划分的持有人核验。
请求示例
通过 CPF 付款 -- 最常见的场景。details.key 和 details.document 必须相同（都是 CPF）。API 不会核验二者是否相同：请在发送前在您这一侧确保一致。
{
"value": 150.00,
"externalId": "PAG-2024-0001",
"description": "Pagamento freelancer - Janeiro/2024",
"details": {
"key": "12345678909",
"keyType": "DOCUMENT",
"name": "Ana Costa",
"document": "12345678909"
}
}按清算机构划分的持有人核验
Gateways API 仅校验 details.document 的格式（11 或 14 位数字及校验位），并按 keyType 校验 details.key 的格式。API 不会将 details.document 与 details.key 比对，不会查询 DICT，两者不一致时也不会拦截操作。 付款始终按 PIX 密钥寻址。
如需将证件号与密钥真实持有人比对，该核验由您账户配置的清算机构执行：
- 部分清算机构只要收到该字段就会核验
details.document。不一致时，交易以ERROR结束，不扣款，webhook 会携带清算机构的消息。 - 部分清算机构仅在您发送
details.checkPixKeyWithDocument: true时才核验。 - 其余清算机构接受该字段但不核验：付款将进入密钥持有人账户。
如何了解我的账户的行为？ 清算机构按账户配置。如有疑问，请咨询您的集成经理。如果您的业务要求证件号不一致时必须拦截付款，请在发送前自行核验持有人：对于 keyType: DOCUMENT，确保 details.document 与 details.key 相同。
代码示例
curl -X POST "https://<api-host>/api/pix/cash-out" \
-H "Authorization: Bearer $PIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"value": 150.00,
"externalId": "PAG-2024-0001",
"description": "Pagamento freelancer - Janeiro/2024",
"details": {
"key": "12345678909",
"keyType": "DOCUMENT",
"name": "Ana Costa",
"document": "12345678909"
}
}'const axios = require('axios');
const response = await axios.post('https://<api-host>/api/pix/cash-out',
{
"value": 150.00,
"externalId": "PAG-2024-0001",
"description": "Pagamento freelancer - Janeiro/2024",
"details": {
"key": "12345678909",
"keyType": "DOCUMENT",
"name": "Ana Costa",
"document": "12345678909"
}
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);响应 (201 Created)
| 字段 | 类型 | 描述 |
|---|---|---|
transactionId | string | 生成的交易内部标识符（数字字符串） |
externalId | string | 请求中提供的外部标识符 |
status | string | 初始状态：PENDING。通过 webhook 确认：CONFIRMED 或 ERROR |
generateTime | string | 交易生成日期/时间（ISO 8601 UTC） |
{
"transactionId": "466208",
"externalId": "PAG-2024-0001",
"status": "PENDING",
"generateTime": "2024-01-15T10:30:00.000Z"
}错误
当请求体未通过验证时返回。顶层字段（value、externalId、description、details 或未知字段）的错误返回 code: PUB_REQUEST_BODY_INVALID，出错字段列在 details.violations 中，如示例所示。details.* 字段的错误以列表形式返回在 message 中，每个字段一条消息。
{
"statusCode": 400,
"timestamp": "2026-04-10T15:30:34.560Z",
"path": "/api/pix/cash-out",
"method": "POST",
"code": "PUB_REQUEST_BODY_INVALID",
"message": "Request body validation failed: value: value must not be less than 0.01",
"userMessage": "Request body is invalid.",
"errorId": "a1b2c3d4e5f6789012345678abcdef01",
"details": {
"violations": {
"value": "value must not be less than 0.01"
}
}
}常见原因：
value小于0.01或超过 2 位小数details.keyType值无效details.key与keyType的格式不匹配details.document的 CPF/CNPJ 无效externalId超过 50 个字符或description超过 140 个字符details.checkPixKeyWithDocument: true但未提供details.document
请参阅 PIX Cash-Out 集成指南，获取代码示例、密钥本地验证和最佳实践。