> ## 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 提现。

**所需权限：** `WITHDRAWAL:WRITE` 或 `FULL_ACCESS`

**IP 限制：** 如果凭证配置了允许的 IP 列表，来自列表之外的请求将以 `403` 被拒绝。建议为拥有此权限的凭证配置。

> [!NOTE]
>
> **异步处理。** 创建提现时返回的是非终态状态（`pending` 或 `processing`）——最终结果始终通过 webhook 送达（`withdrawal.completed` 或 `withdrawal.failed`）。请以 webhook 为准；不要把创建接口的响应当作最终结果。
>
> 校验错误（余额不足、超出限额、数据无效）会在调用本身直接返回错误。

## 发送队列

提现被受理后，会进入向支付机构发送的队列。大多数情况下会立即发送；在交易高峰期可能需要几秒到几分钟，等待期间提现保持 `processing` 状态。

* **按到达顺序。** 提现按创建顺序依次发送。
* **不存在的密钥代价高昂。** 每笔提现都会在 DICT 中查询目标 PIX 密钥，而巴西中央银行对这类查询设有限额——查询一个不存在的密钥所消耗的额度远高于一次成功的查询。当某个账户因密钥不存在或无效而累积多次拒绝时，其后续提现在队列中的优先级会降低，等待时间更长。请在发送前校验密钥，不要用提现来测试密钥是否存在。
* **密钥查询被暂停。** 如果机构提示查询限额已用尽，尚未发送的提现将在队列中等待，直到恢复为止。已经发送的提现可能以 `withdrawal_failed` 返回，金额退回余额。
* **最长期限。** 6 小时内仍无法发送的提现将失败（`withdrawal_failed`），预留金额退回余额。

无论哪种情况，最终结果都通过 webhook 送达。


## OpenAPI

````yaml openapi.cn.json POST /withdrawals
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:
  /withdrawals:
    post:
      tags:
        - External API - Withdrawals (Saques)
      summary: 创建 PIX 提现
      description: |-
        提供 PIX 密钥和收款账户持有人信息，创建一笔新的 PIX 提现。

        **所需权限：** `WITHDRAWAL:WRITE` 或 `FULL_ACCESS`

        **IP 限制：** 如果凭证配置了允许的 IP 列表，来自列表之外的请求将以 `403` 被拒绝。建议为拥有此权限的凭证配置。
      operationId: ExternalWithdrawalsController_create
      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/CreateExternalWithdrawalInput'
      responses:
        '201':
          description: 提现创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExternalWithdrawalOutput'
        '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'
        '403':
          description: Forbidden - Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
        '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:
    CreateExternalWithdrawalInput:
      type: object
      description: >-
        创建 PIX 提现所需的数据。`amount`（从余额中扣除的总额）**或**
        `netAmount`（收款人应收到的净额）**只能提供其中一个**。
      properties:
        projectId:
          type: string
          format: uuid
          description: >-
            提现所属的项目 ID。如未提供且账户只有一个项目，提现将继承该项目；如有多个项目，提现将不关联任何项目——与创建 PIX
            收款时的行为一致。
          example: 3c90c3cc-0d44-4b50-8888-8dd25736052a
        amount:
          type: number
          minimum: 1
          description: >-
            从余额中扣除的**总额**（BRL）。收款人收到 `amount - feeAmount`。最低 R$ 1,00。提供 `amount`
            或 `netAmount`——不可同时提供。
          example: 150.75
        netAmount:
          type: number
          minimum: 1
          description: >-
            收款人应收到的**净额**（BRL）。API 会计算所需的总额（`gross = netAmount +
            feeAmount`）并从余额中扣除该总额。最低 R$ 1,00。提供 `amount` 或 `netAmount`——不可同时提供。
          example: 150
        pixKey:
          type: string
          description: 收款人的 PIX 密钥。
          example: '12345678901'
        pixKeyType:
          type: string
          enum:
            - cpf
            - cnpj
            - email
            - phone
            - random
          description: PIX 密钥类型。
          example: cpf
        holderName:
          type: string
          description: PIX 账户持有人姓名。
          example: João da Silva
        holderDocument:
          type: string
          description: 持有人的 CPF 或 CNPJ。
          example: '12345678901'
        holderDocumentType:
          type: string
          enum:
            - cpf
            - cnpj
          description: 持有人证件类型。
          example: cpf
        externalReference:
          type: string
          maxLength: 255
          description: >-
            您的外部参考 ID（可选）。会在响应以及 webhook `withdrawal_completed` 和
            `withdrawal_failed` 中返回，便于与您的内部系统对账。
          example: saque-empresa-001
      required:
        - pixKey
        - pixKeyType
        - holderName
        - holderDocument
        - holderDocumentType
    GetExternalWithdrawalOutput:
      type: object
      description: 已创建的提现数据。
      properties:
        id:
          type: string
          format: uuid
          description: 提现 ID
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        projectId:
          type: string
          format: uuid
          nullable: true
          description: 提现所属的项目 ID（创建时未提供且账户有 2 个及以上项目时为 null）
          example: 3c90c3cc-0d44-4b50-8888-8dd25736052a
        amount:
          type: number
          description: 提现金额（BRL）
          example: 150.75
        feeAmount:
          type: number
          description: 手续费金额（BRL）
          example: 2.5
        netAmount:
          type: number
          description: 净额（BRL）
          example: 148.25
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: 提现状态
          example: completed
        snapshotPixKey:
          type: string
          nullable: true
          description: 提现时使用的 PIX 密钥
          example: '12345678901'
        snapshotPixKeyType:
          type: string
          enum:
            - cpf
            - cnpj
            - email
            - phone
            - random
          nullable: true
          description: 提现时使用的 PIX 密钥类型
          example: cpf
        snapshotHolderName:
          type: string
          description: 提现时的持有人姓名
          example: João da Silva
        snapshotHolderDocument:
          type: string
          description: 提现时的持有人证件号
          example: '12345678901'
        failureReason:
          type: string
          nullable: true
          description: 失败原因（当 status = failed 时）
          example: null
        pspReference:
          type: string
          nullable: true
          description: PSP（支付服务提供商）参考号
          example: null
        createdAt:
          type: string
          format: date-time
          description: 创建时间
          example: '2026-02-10T14:30:00.000Z'
        processedAt:
          type: string
          format: date-time
          nullable: true
          description: 处理时间
          example: '2026-02-10T14:30:01.000Z'
        externalReference:
          type: string
          nullable: true
          description: 创建提现时发送的外部参考（可选）
          example: saque-empresa-001
      required:
        - id
        - amount
        - feeAmount
        - netAmount
        - status
        - snapshotHolderName
        - snapshotHolderDocument
        - 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
    ForbiddenErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          example: 403
        error:
          type: string
          example: Forbidden
        message:
          type: string
          example: You do not have permission to access this resource
        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
  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.