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

# Process a PIX payment

> Creates a PIX order and returns a QR code for the customer to complete payment.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/payments/pix
openapi: 3.0.0
info:
  title: PlugToPay API
  description: API to make payments easy in multiple gateways.
  version: 1.0.0
servers:
  - url: http://localhost:7701
    description: Test Server
security: []
paths:
  /api/v1/payments/pix:
    post:
      tags:
        - Payments
      summary: Process a PIX payment
      description: >-
        Creates a PIX order and returns a QR code for the customer to complete
        payment.
      operationId: 3630769f5b116e1c473e56460c2cd5b6
      parameters:
        - $ref: '#/components/parameters/XClientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - merchant_order_id
                - amount
                - currency
                - customer
              properties:
                merchant_order_id:
                  type: string
                  example: ORD-2026-12345
                amount:
                  description: Amount in cents
                  type: integer
                  example: 15000
                currency:
                  type: string
                  example: BRL
                gateway_first_try:
                  description: >-
                    Gateway slug to attempt first. Falls back to routing rules
                    if not set.
                  type: string
                  example: pagarme
                  nullable: true
                expires_in:
                  description: Seconds until PIX expires (min 60)
                  type: integer
                  example: 3600
                  nullable: true
                customer:
                  required:
                    - name
                    - email
                    - document
                  properties:
                    name:
                      type: string
                      example: John Doe
                    email:
                      type: string
                      example: john@example.com
                    document:
                      description: CPF (11 digits) or CNPJ (14 digits).
                      type: string
                      example: '12345678909'
                  type: object
                splits:
                  description: >-
                    Optional split rules. Each entry directs a portion of the
                    amount to a sub-account.
                  type: array
                  items:
                    required:
                      - subaccount_id
                      - amount
                    properties:
                      subaccount_id:
                        type: string
                        example: sub_abc123
                      amount:
                        description: Amount in cents to split to this sub-account.
                        type: integer
                        example: 5000
                    type: object
                  nullable: true
              type: object
      responses:
        '201':
          description: PIX order created
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                    example: pending
                  transaction_id:
                    type: string
                    example: 01hvxyz...
                  amount:
                    type: integer
                    example: 15000
                  message:
                    type: string
                    example: PIX generated successfully.
                  payment_method:
                    type: string
                    example: pix
                  merchant_order_id:
                    type: string
                    example: ORD-2026-12345
                    nullable: true
                  idempotency_key:
                    type: string
                    nullable: true
                  plugtopay_request_time:
                    type: string
                    example: 0.05s
                    nullable: true
                  total_request_time:
                    type: string
                    example: 0.8s
                    nullable: true
                  gateways_request_time:
                    type: string
                    example: 0.75s
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
                    nullable: true
                  updated_at:
                    type: string
                    format: date-time
                    nullable: true
                  transactions:
                    type: array
                    items:
                      type: object
                  customer:
                    type: object
                    nullable: true
                  webhook:
                    type: object
                    nullable: true
                  pix:
                    properties:
                      qr_code:
                        type: string
                        nullable: true
                      qr_code_url:
                        type: string
                        nullable: true
                      expiration_at:
                        type: string
                        format: date-time
                        nullable: true
                    type: object
                    nullable: true
                type: object
        '202':
          description: >-
            Accepted — gateway did not respond within the configured timeout,
            processing continues in background
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                    example: processing
                  transaction_id:
                    type: string
                    example: 01hvxyz...
                    nullable: true
                  amount:
                    type: integer
                    example: 15000
                    nullable: true
                  message:
                    type: string
                    example: >-
                      The PIX payment is being processed, a webhook will be sent
                      when ready.
                type: object
        '401':
          description: Unauthorized — Invalid API Key
        '422':
          description: Validation Error
      security:
        - ApiKeyAuth: []
components:
  parameters:
    XClientId:
      name: x-client-id
      in: header
      description: Client identifier for the company in the request.
      required: true
      schema:
        type: string
        example: client_abc123
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Company API key. Send in the X-API-Key header.
      name: X-API-Key
      in: header

````