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

# Gerar QR Code PIX

> Cria uma nova cobrança PIX e retorna o BR Code (copia-e-cola) que o pagador usa.

Quando o pagador efetua o pagamento, enviamos um webhook para `postbackUrl` com status `paid`.


Cria uma nova cobrança PIX e retorna o BR Code (copia-e-cola) que o pagador pode escanear ou colar no app do banco dele.

## Fluxo completo

<Steps>
  <Step title="Você faz POST /v1/pix/qrcode">
    Envie `external_id`, `value_cents`, `postbackUrl` e dados opcionais do pagador.
  </Step>

  <Step title="Recebe HTTP 201 com BR Code">
    Use `qrcode.content` (BR Code copia-e-cola) pra gerar o QR visual no seu frontend.
  </Step>

  <Step title="Cliente paga via app do banco dele">
    Pagador escaneia o QR ou cola o código. Banco processa o PIX.
  </Step>

  <Step title="Paysure envia webhook com status paid">
    Você recebe POST em `postbackUrl` com `cashin.status = "paid"`. Credite o produto/serviço no seu sistema.
  </Step>
</Steps>


## OpenAPI

````yaml POST /v1/pix/qrcode
openapi: 3.0.3
info:
  title: Paysure API
  version: 1.0.0
  description: |
    API REST da Paysure para integração de pagamentos PIX em produção.

    **Capacidades:**
    - Geração de cobranças PIX (cash-in) com QR Code dinâmico
    - Pagamento de chaves PIX e QR Codes (cash-out)
    - Splits configuráveis por transação (até 20 destinatários, % do bruto)
    - Webhooks idempotentes para confirmação de pagamento
    - Consulta de status de transações
    - Chave PIX estática personalizada com identificador embutido

    Todas as transações são em **centavos** (`value_cents`) e em moeda **BRL**.
  contact:
    name: Paysure Suporte
    url: https://paysure.com.br/
servers:
  - url: https://api.paysurebr.com
    description: Produção
security:
  - ClientCredentials: []
paths:
  /v1/pix/qrcode:
    post:
      tags:
        - Cash-in
      summary: Gerar cobrança PIX (QR Code dinâmico)
      description: >
        Cria uma nova cobrança PIX e retorna o BR Code (copia-e-cola) que o
        pagador usa.


        Quando o pagador efetua o pagamento, enviamos um webhook para
        `postbackUrl` com status `paid`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashInRequest'
            example:
              external_id: order-12345
              value_cents: 10000
              postbackUrl: https://seu-site.com/webhooks/paysure
              generator_name: João da Silva
              generator_document: '12345678900'
              description: 'Pedido #12345'
              expiration_seconds: 3600
              splits:
                - clientId: parceiro1
                  value: 5
      responses:
        '201':
          description: Cobrança criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashInResponse'
              example:
                qrcode:
                  reference_code: PSR-9c8f7a1e-4d2b-4e6a-8c9f-1a2b3c4d5e6f
                  external_reference: order-12345
                  content: 00020126580014br.gov.bcb.pix...
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    CashInRequest:
      type: object
      required:
        - external_id
        - value_cents
        - postbackUrl
      properties:
        external_id:
          type: string
          maxLength: 191
          description: Seu identificador único da transação. Use idempotência.
        value_cents:
          type: integer
          minimum: 100
          description: Valor em centavos (R$ 1,00 = 100).
        generator_name:
          type: string
          maxLength: 191
          nullable: true
          description: Nome do pagador (cliente final). Opcional.
        generator_document:
          type: string
          maxLength: 32
          nullable: true
          description: CPF ou CNPJ do pagador. Opcional.
        description:
          type: string
          maxLength: 255
          nullable: true
        postbackUrl:
          type: string
          format: uri
          description: URL HTTPS para receber webhook quando o pagamento for confirmado.
        splits:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Split'
        expiration_seconds:
          type: integer
          minimum: 60
          maximum: 86400
          default: 3600
          nullable: true
          description: >
            Tempo de expiração do QR Code, em segundos (TTL). Opcional — se
            omitido, usa **3600** (1 hora).

            Mínimo 60s, máximo 86400s (24h). Após expirar, o QR não pode mais
            ser pago.
    CashInResponse:
      type: object
      properties:
        qrcode:
          type: object
          properties:
            reference_code:
              type: string
              description: ID interno Paysure (use pra consultar).
            external_reference:
              type: string
              description: Seu external_id ecoado.
            content:
              type: string
              description: BR Code copia-e-cola. Mostre no QR pra pagador.
    Split:
      type: object
      required:
        - clientId
        - value
      properties:
        clientId:
          type: string
          maxLength: 191
          description: Username Paysure do destinatário do split.
          example: parceiro1
        value:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Percentual do valor bruto (1 = 1%, 5 = 5%).
          example: 5
    Error:
      type: object
      properties:
        message:
          type: string
        ms:
          type: number
          description: Tempo de processamento da request em ms.
  responses:
    Unauthorized:
      description: Credenciais inválidas, ausentes ou inativas.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid credentials or inactive
    ValidationError:
      description: Erro de validação (campos faltando ou inválidos).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ClientCredentials:
      type: apiKey
      in: header
      name: ci
      description: >
        Autenticação por par client-credentials. Envie **dois headers** em toda
        requisição:


        - `ci`: client_id (público)

        - `cs`: client_secret (privado — nunca exponha no frontend)


        Gere as credenciais no painel da Paysure em **API Keys**. Você pode ter
        múltiplas chaves ativas.

````