发起 PIX 付款（Cash-Out）

POST /api/pix/cash-out

向目标 PIX 密钥发送 PIX 付款。交易创建后状态为 PENDING，最终结果将通过 webhook 通知，或可通过轮询查询。

认证

需要在 Authorization 请求头中提供 Bearer 令牌。

请求体

字段	类型	必填	描述
`value`	number	是	金额（巴西雷亚尔，最多 2 位小数）。最小值：`0.01`
`externalId`	string	是	每个账户的唯一外部标识符
`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 位数字）。所有 keyType 均为必填

`details.key` 的格式要求

`keyType`	格式	示例
`DOCUMENT`	CPF：11 位数字 / CNPJ：14 位数字（仅数字）	`12345678901`、`12345678000195`
`EMAIL`	有效的电子邮件地址	`usuario@exemplo.com`
`PHONE`	区号 + 号码（10-11 位数字，不含国际区号 +55）	`11999999999`
`RANDOM`	UUID（可带或不带连字符）	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

details.document 字段对于所有密钥类型均为必填，包括 EMAIL、PHONE 和 RANDOM。该字段会被发送至清算银行用于 DICT 验证。如果证件号码与 PIX 密钥持有人不匹配，银行将返回 TAX_ID_MISMATCH 错误。

请求示例

通过 CPF 付款 -- 最常见的场景。details.key 和 details.document 相同（都是 CPF）。

{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}

通过 CNPJ 付款 -- 常见于 B2B 支付（供应商、发票）。

{
  "value": 4500.00,
  "externalId": "NF-2024-0089",
  "description": "NF 0089/2024 - Serviços de hospedagem",
  "details": {
    "key": "11222333000144",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000144"
  }
}

通过电子邮件密钥付款。请注意，details.document 必须是密钥持有人的 CPF/CNPJ（无法通过电子邮件推断）。

{
  "value": 89.90,
  "externalId": "COMM-2024-0456",
  "description": "Comissão venda #456",
  "details": {
    "key": "vendedor@loja.com.br",
    "keyType": "EMAIL",
    "name": "Roberto Vendas",
    "document": "98765432100"
  }
}

通过手机号码密钥付款。格式为区号 + 号码（10 或 11 位数字），不含国际区号 +55。

{
  "value": 25.00,
  "externalId": "REEMB-2024-0012",
  "description": "Reembolso uber colaborador",
  "details": {
    "key": "11987654321",
    "keyType": "PHONE",
    "name": "Pedro Almeida",
    "document": "11122233344"
  }
}

通过随机密钥（EVP/UUID）付款。由巴西中央银行生成，不包含个人信息。

{
  "value": 1250.00,
  "externalId": "RENT-2024-JAN",
  "description": "Aluguel janeiro/2024",
  "details": {
    "key": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "keyType": "RANDOM",
    "name": "Imobiliária Central",
    "document": "55666777000199"
  }
}

响应 (201 Created)

字段	类型	描述
`transactionId`	string	生成的交易内部标识符（UUID）
`externalId`	string	请求中提供的外部标识符
`status`	string	初始状态：`PENDING`。通过 webhook 确认：`CONFIRMED` 或 `ERROR`
`generateTime`	string	交易生成日期/时间（ISO 8601 UTC）

{
  "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

错误

当请求体未通过验证时返回。

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PUB_VALIDATION_ERROR",
  "message": "Validation failed",
  "userMessage": "Dados da requisição inválidos",
  "details": {
    "errors": [
      "value must not be less than 0.01",
      "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
    ]
  }
}

常见原因：

value 小于 0.01 或超过 2 位小数
details.keyType 值无效
details.key 与 keyType 的格式不匹配
details.document 为空或格式错误

可用余额小于交易金额 + 手续费。

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Insufficient balance",
  "userMessage": "Saldo insuficiente para realizar esta operação"
}

同类别的其他业务错误：

错误码	描述
`PIX_INSUFFICIENT_BALANCE`	余额不足（金额 + 手续费）
`PIX_TRANSACTION_LIMIT_EXCEEDED`	金额超过单笔交易限额
`PIX_DAILY_LIMIT_EXCEEDED`	当日累计金额超过每日限额
`PIX_NIGHT_LIMIT_EXCEEDED`	夜间交易超过降低后的限额（20:00-06:00）
`PIX_INVALID_AMOUNT`	金额小于 0.01 或超过 2 位小数
`PIX_INVALID_PIX_KEY`	密钥格式与所提供的 `keyType` 不匹配

该 externalId 已在此账户中使用过。请使用新的标识符。

{
  "statusCode": 409,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "External ID already exists",
  "userMessage": "Esta transação já existe no sistema"
}

externalId 用作幂等键。如果您使用相同的 externalId 发送两次相同的请求，第二次调用将返回 409 -- 确保付款不会重复。

当清算银行在交易创建之后拒绝了操作时，状态会变为 ERROR，并且 errorCode/errorMessage 字段将通过 Cash-Out webhook 发送：

`errorCode`	描述	可重试？
`TAX_ID_MISMATCH`	`details.document` 与 PIX 密钥持有人不匹配	否 -- 请修正 CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ 算法校验无效	否 -- 请修正证件号码
`BLOCKED_ACCOUNT`	目标账户被司法冻结	否
`ACCOUNT_CLOSED`	目标账户已注销	否
`ORDER_REJECTED`	目标银行拒绝了该操作	否
`PAYMENT_EXPIRED`	交易在处理前已过期	是 -- 请重新发送
`SETTLEMENT_TIMEOUT`	目标银行未及时响应	是 -- 请重新发送

包含错误的 webhook 载荷示例：

{
  "type": "CASH_OUT",
  "data": {
    "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
    "externalId": "PAG-2024-0001",
    "status": "ERROR",
    "errorCode": "TAX_ID_MISMATCH",
    "errorMessage": "O documento informado não corresponde ao titular da chave PIX"
  }
}

请参阅 PIX Cash-Out 集成指南，获取代码示例、密钥本地验证和最佳实践。

发起 PIX 付款（Cash-Out）

POST /api/pix/cash-out

认证

请求体

details.key 的格式要求

请求示例

响应 (201 Created)

错误

本页目录

`details.key` 的格式要求