生成 PIX 收款（Cash-In）

POST /api/pix/cash-in

生成动态二维码，用于通过 PIX 接收付款。收款创建后状态为 PENDING，付款成功后状态将通过 webhook 变更为 CONFIRMED。

认证

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

请求体

字段	类型	必填	描述
`transaction`	object	是	交易数据
`transaction.value`	number	是	金额（巴西雷亚尔，最多 2 位小数）。最小值：`0.01`
`transaction.description`	string	是	交易描述（最多 140 个字符）
`transaction.externalId`	string	是	外部交易 ID（每个账户的唯一标识符）
`transaction.expirationTime`	number	否	过期时间（秒）。最短 5 分钟，最长 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 个键）
`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": "12345678901"
  }
}

最常见场景：生成二维码供付款人扫描，附带订单元数据，过期时间为 1 小时。

{
  "transaction": {
    "value": 189.90,
    "description": "Pedido #8842 - Loja Virtual",
    "externalId": "ORD-8842-20240115",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "98765432000188"
  },
  "additionalInfo": {
    "orderId": "8842",
    "storeName": "Tech Solutions",
    "customerEmail": "carlos@email.com"
  }
}

大额收款（B2B），过期时间为 7 天，付款方为 CNPJ。

{
  "transaction": {
    "value": 15750.00,
    "description": "NF 2024/0042 - Consultoria em TI",
    "externalId": "NF-2024-0042",
    "expirationTime": 604800,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa ABC Ltda",
    "document": "11222333000144"
  },
  "additionalInfo": {
    "nfNumber": "2024/0042",
    "contractId": "CTR-789"
  }
}

Marketplace 场景：R$ 200 的付款分配给卖家（70%）、平台（20%）和配送员（固定 R$ 10）。分账将按照账户配置的频率执行。

{
  "transaction": {
    "value": 200.00,
    "description": "Pedido #12345 - Marketplace",
    "externalId": "MKT-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João Pereira",
    "document": "12345678901"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000188",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000144",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000144",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "pixKey": "11999887766",
      "pixKeyType": "PHONE",
      "name": "Entregador Silva",
      "document": "98765432100",
      "type": "FIXED",
      "value": 10.00
    }
  ]
}

付款确认后的结果：

接收方	类型	计算方式	金额
Loja do João	70%	R$ 200 × 70%	R$ 140,00
Marketplace Ltda	20%	R$ 200 × 20%	R$ 40,00
Entregador Silva	固定	—	R$ 10,00
剩余余额	—	R$ 200 - R$ 190	R$ 10,00

单笔即时分账：付款确认后，立即自动将款项转给服务提供方（无需等待账户配置的频率）。

{
  "transaction": {
    "value": 350.00,
    "description": "Serviço de consultoria - Projeto Alpha",
    "externalId": "SVC-ALPHA-001",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa XYZ S.A.",
    "document": "55666777000199"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678901",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

请参阅分账付款指南，了解有关类型、计算方式、频率和高级示例的完整详情。

响应 (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..."
}

错误

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

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_VALIDATION_ERROR",
  "message": "Validation failed",
  "userMessage": "Dados da requisição inválidos",
  "details": {
    "errors": [
      "transaction.value must not be less than 0.01",
      "transaction.description should not be empty"
    ]
  }
}

常见原因：

transaction.value 小于 0.01 或超过 2 位小数
transaction.description 或 transaction.externalId 为空
expirationTime 小于 300（5 分钟）或大于 604800（7 天）
分账金额之和超过交易金额

令牌缺失、已过期或无效。

{
  "statusCode": 401,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_UNAUTHORIZED",
  "message": "Unauthorized",
  "userMessage": "Token de autenticação inválido ou expirado"
}

与 PIX 提供商通信失败。请重试。

{
  "statusCode": 500,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_INTERNAL_ERROR",
  "message": "Failed to generate PIX charge",
  "userMessage": "Erro ao gerar cobrança PIX. Tente novamente em alguns instantes.",
  "errorId": "err_a1b2c3d4"
}

生成 PIX 收款（Cash-In）

POST /api/pix/cash-in

认证

请求体

请求示例

响应 (201 Created)

错误

本页目录