> ## Documentation Index > Fetch the complete documentation index at: https://docs.brazilpix.com/llms.txt > Use this file to discover all available pages before exploring further. # 创建 PIX 收款 > 创建一笔即时 PIX 收款。 **所需权限：** `PIX:WRITE` 或 `FULL_ACCESS` > [!NOTE] > > **子账户之间的分账。** 可选字段 `split` 将部分金额分给您的其他钱包——子账户，或通过保留字 `principal` 指定的主账户。最多 10 项，金额为固定值，以雷亚尔计。 > > 创建收款的一方是**发起方**：收取总额、支付全部手续费，然后才进行分账，因此分账上限是**净额**（收款金额减去手续费），而非总额。分账在结算时执行，而不是在创建时。退款和 MED **只从发起方**扣款——收到分账的一方永远不会被扣款。 > > 完整规则、示例和错误表参见[支付分账](https://docs.brazilpix.com/cn.md#支付分账)。 > [!NOTE] > > **机构选择。** 如果您的账户已启用此选项，可选字段 `pspCredentialId` 可指定签发本笔收款的机构，忽略已配置的路由。请在控制台的 **设置 → 路由** 中复制该 ID。 > > 指定**不等于优先**：如果该机构不可用或容量不足，收款将失败，而不会改由其他机构签发。响应会回显 `pspCredentialId` 作为回执。 > > 完整规则和错误表参见[机构选择](https://docs.brazilpix.com/cn.md#机构选择)。 ## OpenAPI ````yaml openapi.cn.json POST /pix openapi: 3.0.0 info: title: Brazil Pix API description: Brazil Pix Payment API documentation version: '1.0' contact: {} servers: - url: https://api.brazilpix.com/v2 security: [] paths: /pix: post: tags: - External API - PIX summary: 创建 PIX 收款 description: |- 创建一笔即时 PIX 收款。 **所需权限：** `PIX:WRITE` 或 `FULL_ACCESS` operationId: ExternalPixController_createCharge parameters: - name: Idempotency-Key in: header required: false description: >- 由客户端生成的唯一键（8-255 个字符），使请求具备幂等性。使用相同键重试时返回缓存的响应（TTL 24 小时）。相同键但请求体不同时返回 422。 schema: type: string minLength: 8 maxLength: 255 - $ref: '#/components/parameters/SubAccount' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixChargeInput' responses: '201': description: PIX 收款创建成功 content: application/json: schema: $ref: '#/components/schemas/CreatePixChargeOutput' '400': description: Bad Request - Validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '404': description: Not Found - Resource not found content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - bearerAuth: [] components: parameters: SubAccount: name: X-Sub-Account in: header required: false description: >- 执行操作的子账户的 reference。省略时，操作在主账户上执行；保留值 `principal` 同样解析为主账户，等同于省略该请求头。除 `POST /auth` 和 `/sub-accounts` 自身的端点（始终在主账户上操作）外，所有端点均接受该请求头。 可能的错误：`404 SUB_ACCOUNT_NOT_FOUND`、`403 SUB_ACCOUNT_FORBIDDEN`、`403 SUB_ACCOUNT_SUSPENDED`。 要求凭证已启用**子账户访问**（设置 → 集成 → API 凭证）。该项默认关闭，任何权限都无法替代，`FULL_ACCESS` 也不例外：未启用时响应为 `403 SUB_ACCOUNT_FORBIDDEN`。 schema: type: string pattern: ^[a-z0-9][a-z0-9_-]{1,31}$ example: loja-centro schemas: CreatePixChargeInput: type: object properties: amount: type: number description: 金额（BRL）（例如：100.50 表示 R$ 100,50） minimum: 1 example: 150.75 description: type: string description: 收款描述 maxLength: 255 example: 'Pagamento do pedido #12345' customer: description: 付款人信息（均为可选）。 allOf: - $ref: '#/components/schemas/CustomerDto' projectId: type: string description: 交易关联的项目 ID。如未提供且账户只有一个项目，收款将继承该项目；如有多个项目，收款将不关联任何项目。 format: uuid pspCredentialId: type: string description: >- 指定签发本笔收款的机构，忽略已配置的路由。请使用控制台中 设置 → 路由 显示的 ID。该机构必须是您账户中已启用且处于活动状态的机构。如果该机构不可用或容量不足，收款将失败——不会回退到其他机构：您指定的就是这一家。仅适用于已启用机构选择的账户。 format: uuid example: 6e307aa4-4772-4230-a648-d88cee308f54 expiresIn: type: integer description: 距离过期的秒数（默认：86400 = 24 小时） minimum: 300 maximum: 604800 example: 3600 externalReference: type: string description: 您的外部参考 ID maxLength: 255 example: pedido-12345 metadata: type: object description: 自定义元数据（键值对） additionalProperties: true example: orderId: '12345' source: website split: type: array description: >- 在结算时将部分金额分给同一账户下的其他子账户。创建收款的一方为发起方：收取总额、承担全部手续费，然后才进行分账——手续费不在各接收方之间分摊。分账总和不得超过净额（收款金额减去手续费）。退款和 MED 仅从发起方扣款；已收到分账的一方不会被扣款。 maxItems: 10 items: $ref: '#/components/schemas/PixSplitAllocationInput' required: - amount - description CreatePixChargeOutput: type: object properties: id: type: string description: 收款 ID（交易 ID） format: uuid status: type: string description: 收款状态 enum: - pending - completed - failed - cancelled amount: type: number description: 金额（BRL） example: 150.75 currency: type: string description: 货币代码 example: BRL pixCopyPaste: type: string description: PIX 复制粘贴码 example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890 qrCodeBase64: type: string description: PIX 二维码，data URI 格式（data:image/png;base64,...） pspPaymentId: type: string description: 支付服务提供商（PSP）侧的交易 ID。用于对账；如果 PSP 在创建时未返回该 ID，则不存在。 example: de3516a2-c63a-4c02-b132-a239bf42e183 expiresAt: type: string description: 过期时间 format: date-time pspCredentialId: type: string description: 签发本笔收款的机构。仅当您在请求中指定了机构（`pspCredentialId`）时返回，作为该指定已被遵循的回执。 format: uuid example: 6e307aa4-4772-4230-a648-d88cee308f54 externalReference: type: string description: 您的外部参考 ID example: pedido-12345 createdAt: type: string description: 创建时间 format: date-time split: type: array description: >- 已接受的分账，单位为雷亚尔。仅当收款创建时带有 split 才存在——如果出现在响应中，说明子账户存在且总和未超过净额。实际分配的金额通过 webhook payment_completed 送达。 items: $ref: '#/components/schemas/PixSplitAllocationOutput' required: - id - status - amount - currency - pixCopyPaste - expiresAt - createdAt BadRequestErrorResponse: type: object properties: statusCode: type: number example: 400 error: type: string example: BadRequest message: type: string example: name must be longer than or equal to 2 characters details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp UnauthorizedErrorResponse: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication token is required details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp NotFoundErrorResponse: type: object properties: statusCode: type: number example: 404 error: type: string example: NotFound message: type: string example: Resource with id 550e8400-e29b-41d4-a716-446655440000 not found details: type: object example: resource: Example id: 550e8400-e29b-41d4-a716-446655440000 timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string required: - statusCode - error - message - timestamp InternalServerErrorResponse: type: object properties: statusCode: type: number example: 500 error: type: string example: InternalError message: type: string example: An unexpected error occurred details: type: object timestamp: type: string example: '2025-12-15T22:00:00.000Z' traceId: type: string example: 2771463d58840c8e116dc6dda1e1e5d0 required: - statusCode - error - message - timestamp CustomerDto: type: object properties: name: type: string description: 付款人姓名 maxLength: 255 example: João da Silva document: type: string description: 付款人的 CPF 或 CNPJ，仅数字（可选） maxLength: 20 example: '12345678909' email: type: string description: 付款人电子邮箱 format: email maxLength: 255 phone: type: string description: 付款人电话（格式不限） maxLength: 20 example: '+5511999998888' PixSplitAllocationInput: type: object properties: subAccount: type: string description: >- 接收分账的子账户的 reference，须为同一账户下的活动子账户。保留字 `principal` 指向主账户——当收款由子账户发起（请求头 `X-Sub-Account`）时使用；由主账户自身创建的收款不能分账给 `principal`。 pattern: ^[a-z0-9][a-z0-9_-]{1,31}$ example: loja-centro amount: type: number description: 分给该钱包的金额（BRL）。固定金额——不接受百分比。最多 2 位小数。 minimum: 0.01 example: 30 required: - subAccount - amount PixSplitAllocationOutput: type: object properties: subAccount: type: string description: 接收分账的子账户的 reference；目标为主账户时为 `principal` example: loja-centro amount: type: number description: 分给该钱包的金额（BRL） example: 30 required: - subAccount - amount securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 通过 POST /auth（client_id + client_secret）获取的访问令牌。有效期 300 秒。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.