> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pague.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create PIX Charge

> Creates an instant PIX charge.

**Required permission:** `PIX:WRITE` or `FULL_ACCESS`

<Note>
  **Split across sub-accounts.** The optional `split` field shares part of the amount with other wallets of yours — sub-accounts, or the main account through the reserved word `principal`. At most 10 items, fixed amounts in BRL.

  Whoever creates the charge is the **originator**: it receives the gross amount, pays the full fee and only then splits, so the cap is the **net** amount (charge amount minus the fee), not the gross. The split happens at settlement, not at creation. Refunds and MED debit **the originator only** — whoever received a share is never debited.

  See [Payment Split](/en#payment-split) for the full rules, the examples and the error table.
</Note>

<Note>
  **Choosing the institution.** If your account has this option enabled, the optional `pspCredentialId` field pins the institution that issues this charge, bypassing the configured routing. Copy the ID under **Settings → Routing** in the dashboard.

  Pinning is **not preferring**: if the institution is down or out of capacity, the charge fails instead of going out through another one. The response echoes `pspCredentialId` as a receipt.

  See [Choosing the Institution](/en#choosing-the-institution) for the full rules and the error table.
</Note>


## OpenAPI

````yaml openapi.en.json POST /pix
openapi: 3.0.0
info:
  title: pague.dev API
  description: pague.dev Payment API documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api-gateway.pague.dev/v2
security: []
paths:
  /pix:
    post:
      tags:
        - External API - PIX
      summary: Create a PIX charge
      description: |-
        Creates an instant PIX charge.

        **Required permission:** `PIX:WRITE` or `FULL_ACCESS`
      operationId: ExternalPixController_createCharge
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Unique client-provided key (8-255 chars) that makes the request
            idempotent. Retries with the same key return the cached response
            (24h TTL). The same key with a different body returns 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 charge created successfully
          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 of the sub-account the operation runs against. When omitted,
        the operation happens on the main account; the reserved value
        `principal` also resolves to the main account and is equivalent to
        omitting the header. Accepted on every endpoint except `POST /auth` and
        the `/sub-accounts` endpoints themselves, which always operate on the
        main account.


        Possible errors: `404 SUB_ACCOUNT_NOT_FOUND`, `403
        SUB_ACCOUNT_FORBIDDEN`, `403 SUB_ACCOUNT_SUSPENDED`.


        Requires the credential to have **sub-account access** enabled (Settings
        → Integration → API Credentials). It starts turned off and is not
        replaced by any permission, not even `FULL_ACCESS`: without it the
        response is `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: Amount in BRL (e.g. 100.50 for R$ 100,50)
          minimum: 1
          example: 150.75
        description:
          type: string
          description: Charge description
          maxLength: 255
          example: 'Pagamento do pedido #12345'
        customer:
          description: Payer details (all optional).
          allOf:
            - $ref: '#/components/schemas/CustomerDto'
        projectId:
          type: string
          description: >-
            Project ID to associate the transaction with. If omitted, the charge
            inherits the account's project when there is a single one; with
            multiple projects the charge is created without a project.
          format: uuid
        pspCredentialId:
          type: string
          description: >-
            Pins the institution that issues this charge, bypassing the
            configured routing. Use the ID shown under Settings → Routing in the
            dashboard. It must be an enabled, active institution of your
            account. If it is down or out of capacity, the charge FAILS — it
            does not fall back to another one: you asked for this one. Available
            to accounts with institution choice enabled.
          format: uuid
          example: 6e307aa4-4772-4230-a648-d88cee308f54
        expiresIn:
          type: integer
          description: 'Seconds until expiration (default: 86400 = 24h)'
          minimum: 300
          maximum: 604800
          example: 3600
        externalReference:
          type: string
          description: Your external reference ID
          maxLength: 255
          example: pedido-12345
        metadata:
          type: object
          description: Custom metadata (key-value pairs)
          additionalProperties: true
          example:
            orderId: '12345'
            source: website
        split:
          type: array
          description: >-
            Shares part of the amount with other sub-accounts of the same
            account, at settlement. Whoever creates the charge is the
            originator: it receives the gross amount, pays the full fee and only
            then splits — the fee is not shared with the recipients. The split
            sum cannot exceed the net amount (charge amount minus the fee).
            Refunds and MED debit the originator only; whoever received a share
            is never debited.
          maxItems: 10
          items:
            $ref: '#/components/schemas/PixSplitAllocationInput'
      required:
        - amount
        - description
    CreatePixChargeOutput:
      type: object
      properties:
        id:
          type: string
          description: Charge ID (transaction ID)
          format: uuid
        status:
          type: string
          description: Charge status
          enum:
            - pending
            - completed
            - failed
            - cancelled
        amount:
          type: number
          description: Amount in BRL
          example: 150.75
        currency:
          type: string
          description: Currency code
          example: BRL
        pixCopyPaste:
          type: string
          description: PIX copy-and-paste code
          example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
        qrCodeBase64:
          type: string
          description: PIX QR Code as a data URI (data:image/png;base64,...)
        pspPaymentId:
          type: string
          description: >-
            Transaction ID at the payment service provider (PSP). Use it for
            reconciliation; absent if the PSP did not return the ID at creation.
          example: de3516a2-c63a-4c02-b132-a239bf42e183
        expiresAt:
          type: string
          description: Expiration date
          format: date-time
        pspCredentialId:
          type: string
          description: >-
            Institution that issued this charge. Only present when you pinned
            the institution in the request (`pspCredentialId`), as a receipt
            that it was honored.
          format: uuid
          example: 6e307aa4-4772-4230-a648-d88cee308f54
        externalReference:
          type: string
          description: Your external reference ID
          example: pedido-12345
        createdAt:
          type: string
          description: Creation date
          format: date-time
        split:
          type: array
          description: >-
            Accepted split, in BRL. Present only when the charge was created
            with a split — if it came back in the response, the sub-accounts
            existed and the sum fit in the net amount. What was actually
            distributed arrives in the payment_completed webhook.
          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: Payer's name
          maxLength: 255
          example: João da Silva
        document:
          type: string
          description: Payer's CPF or CNPJ, digits only (optional)
          maxLength: 20
          example: '12345678909'
        email:
          type: string
          description: Payer's email
          format: email
          maxLength: 255
        phone:
          type: string
          description: Payer's phone number (free format)
          maxLength: 20
          example: '+5511999998888'
    PixSplitAllocationInput:
      type: object
      properties:
        subAccount:
          type: string
          description: >-
            Reference of an active sub-account of the same account that receives
            the share. The reserved word `principal` addresses the main account
            — use it when the charge is originated by a sub-account
            (`X-Sub-Account` header); a charge created by the main account
            itself cannot split to `principal`.
          pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
          example: loja-centro
        amount:
          type: number
          description: >-
            Amount in BRL allocated to this wallet. Fixed amount — percentages
            are not accepted. At most 2 decimal places.
          minimum: 0.01
          example: 30
      required:
        - subAccount
        - amount
    PixSplitAllocationOutput:
      type: object
      properties:
        subAccount:
          type: string
          description: >-
            Reference of the sub-account that receives the share, or `principal`
            when the destination is the main account
          example: loja-centro
        amount:
          type: number
          description: Amount in BRL allocated to this wallet
          example: 30
      required:
        - subAccount
        - amount
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtained from POST /auth (client_id + client_secret). Valid
        for 300 seconds.

````