> ## 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.

# Pagar PIX via chave

> Envia um pagamento PIX para a chave especificada. Wallet do user é debitada imediatamente.

Status final via webhook em `postbackUrl`. Em caso de falha do provedor, o valor é estornado automaticamente.


Envia um pagamento PIX para uma chave DICT cadastrada (CPF, CNPJ, email, phone, EVP).

## Fluxo

1. Você envia a requisição → recebe `HTTP 201` com `status: "processing"` e um `reference_code`.
2. Mais tarde, enviamos um webhook em `postbackUrl` com o status final:
   * `status: "paid"` → pagamento concluído.
   * `status: "refunded"` → não foi possível concluir; nenhum ajuste é necessário do seu lado.

<Note>
  Cada `external_id` deve ser único por transação. Use-o como sua chave de idempotência.
</Note>

## Validação de chave PIX

Antes de processar, validamos o formato da `pix_key`:

* **CPF / CNPJ**: dígitos verificadores (módulo 11)
* **Email**: formato válido
* **Phone**: padrão E.164 (`+55...`)
* **EVP**: UUID v4

Se a chave estiver malformada, respondemos com `HTTP 422` imediatamente.


## OpenAPI

````yaml POST /v1/pix/payment
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/payment:
    post:
      tags:
        - Cash-out
      summary: Pagar PIX via chave (CPF/CNPJ/email/phone/EVP)
      description: >
        Envia um pagamento PIX para a chave especificada. Wallet do user é
        debitada imediatamente.


        Status final via webhook em `postbackUrl`. Em caso de falha do provedor,
        o valor é estornado automaticamente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PixPaymentRequest'
            example:
              external_id: withdraw-001
              value_cents: 5000
              pix_key_type: cpf
              pix_key: '12345678900'
              receiver_name: Maria Souza
              receiver_document: '12345678900'
              postbackUrl: https://seu-site.com/webhooks/paysure
      responses:
        '201':
          description: Pagamento aceito (processando)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PixPaymentResponse'
              example:
                cashout:
                  reference_code: PSR-1234abcd-...
                  external_reference: withdraw-001
                  status: processing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    PixPaymentRequest:
      type: object
      required:
        - external_id
        - value_cents
        - pix_key_type
        - pix_key
        - receiver_name
        - receiver_document
        - postbackUrl
      properties:
        external_id:
          type: string
          maxLength: 191
        value_cents:
          type: integer
          minimum: 100
        pix_key_type:
          type: string
          enum:
            - cpf
            - cnpj
            - email
            - phone
            - evp
        pix_key:
          type: string
          maxLength: 255
        receiver_name:
          type: string
          maxLength: 191
        receiver_document:
          type: string
          maxLength: 32
        description:
          type: string
          maxLength: 255
          nullable: true
        postbackUrl:
          type: string
          format: uri
        splits:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/Split'
    PixPaymentResponse:
      type: object
      properties:
        cashout:
          type: object
          properties:
            reference_code:
              type: string
            external_reference:
              type: string
            status:
              type: string
              enum:
                - processing
    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.

````