生成 PIX 收款（Cash-In）
POST /api/pix/cash-in
POST https://<api-host>/api/pix/cash-in需要在 Authorization 头中提供 Bearer token。请参阅 生成令牌 获取。
生成动态二维码，用于通过 PIX 接收付款。收款创建后状态为 PENDING，付款成功后状态将通过 webhook 变更为 CONFIRMED。
认证
需要在 Authorization 请求头中提供 Bearer 令牌。
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
transaction | object | 是 | 交易数据 |
transaction.value | number | 是 | 金额（巴西雷亚尔，最多 2 位小数）。最小值：0.01 |
transaction.description | string | 是 | 交易描述（最多 100 个字符） |
transaction.externalId | string | 是 | 外部交易 ID（每个账户唯一，最多 50 个字符；不能以 MIRROR: 开头） |
transaction.expirationTime | number | 否 | 过期时间（秒）。最短 30 秒，最长 7 天。默认值：86400（24 小时）。部分提供商要求更高的最小值 — 参见 按提供商的限制 |
transaction.generateQrCode | boolean | 否 | 如果为 true，以 Base64 格式返回二维码。默认值：false |
payer | object | 是 | 付款人数据（仅供参考 -- 不会发送给 PSP） |
payer.fullName | string | 是 | 付款人姓名。仅供参考 -- 可使用固定值（如：账户的公司名称）。最多 100 个字符 |
payer.document | string | 是 | CPF（11 位数字）或 CNPJ（14 位数字），仅数字。仅供参考 — 可使用集成方自身的 CNPJ |
additionalInfo | object | 否 | 附加信息（string:string 键值对，最多 10 个键；mirror 为保留键） |
splits | array | 否 | 分账接收人列表（最多 10 个）。当 PIX-IN 确认后，金额将自动分配。分账金额之和加上手续费不能超过交易金额 |
splits[].pixKey | string | 是 | 分账接收人的 PIX 密钥（最多 255 个字符） |
splits[].pixKeyType | string | 是 | 密钥类型：EMAIL、PHONE、CPF、CNPJ、RANDOM |
splits[].name | string | 是 | 接收人姓名（最多 255 个字符） |
splits[].document | string | 是 | CPF（11 位数字）或 CNPJ（14 位数字），仅数字 |
splits[].type | string | 是 | 分账类型：FIXED（固定金额，单位为雷亚尔）或 PERCENTAGE（占总金额的百分比） |
splits[].value | number | 是 | 分账金额。FIXED：雷亚尔金额，最多 2 位小数（例如：10.50）。PERCENTAGE：直接填写百分比（例如：10 = 10%）。最小值：0.01 |
splits[].immediate | boolean | 否 | 如果为 true，分账在 PIX-IN 确认后立即执行。默认值：false（遵循账户配置的频率） |
请求示例
最简场景：生成收款，不含二维码，不含附加信息。
{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
}请参阅分账付款指南，了解有关类型、计算方式、频率和高级示例的完整详情。
代码示例
curl -X POST "https://<api-host>/api/pix/cash-in" \
-H "Authorization: Bearer $PIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
}'const axios = require('axios');
const response = await axios.post('https://<api-host>/api/pix/cash-in',
{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);响应 (201 Created)
| 字段 | 类型 | 描述 |
|---|---|---|
transactionId | string | 生成的交易唯一标识符 |
correlationId | string | 交易关联 ID（UUID） |
externalId | string | 外部交易 ID（与输入值相同） |
status | string | 交易状态：PENDING（等待付款） |
pixCode | string | 标准 EMV 格式的 PIX 代码（复制粘贴） |
generateTime | string | PIX 生成日期和时间（ISO 8601） |
expirationDate | string | PIX 过期日期和时间（ISO 8601） |
qrCodeImage | string | Base64 格式的二维码（仅当 generateQrCode=true 时返回） |
{
"transactionId": "7845",
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "ORD-8842-20240115",
"status": "PENDING",
"pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
"generateTime": "2024-01-15T10:30:00.000Z",
"expirationDate": "2024-01-15T11:30:00.000Z",
"qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}错误
当请求体未通过验证时返回。嵌套字段（transaction.*、payer.*、splits[]）的错误以列表形式返回在 message 中，每个字段一条消息。顶层字段的错误（例如缺少 transaction 或包含未知字段）返回 code: PUB_REQUEST_BODY_INVALID，出错字段列在 details.violations 中。
{
"statusCode": 400,
"timestamp": "2026-04-10T15:27:36.608Z",
"path": "/api/pix/cash-in",
"method": "POST",
"code": "HTTP_ERROR",
"message": [
"transaction.value deve ser no mínimo 0.01",
"transaction.description deve ter no máximo 100 caracteres"
],
"userMessage": "Requisição inválida. Verifique os dados enviados.",
"errorId": "31b5dc36b86c598e51a2a5389a37060d",
"error": "Bad Request"
}常见原因：
transaction.value小于0.01或超过 2 位小数transaction.description或transaction.externalId为空，description超过 100 个字符或externalId超过 50 个字符- 该账户下
externalId已被使用（PIX_DUPLICATE_EXTERNAL_ID） expirationTime小于 30（秒）或大于 604800（7 天）expirationTime小于账户提供商的最小值（errorCodePROVIDER_EXPIRATION_BELOW_MINIMUM）— 参见 按提供商的限制- 分账金额之和超过交易金额