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

# Criar Cobrança PIX

> Cria uma cobrança PIX instantânea.

**Permissão requerida:** `PIX:WRITE` ou `FULL_ACCESS`

<Note>
  **Split entre subcontas.** O campo opcional `split` reparte parte do valor com outras carteiras suas — subcontas ou a conta principal, pela palavra reservada `principal`. No máximo 10 itens, valores fixos em reais.

  Quem cria a cobrança é o **originador**: recebe o bruto, paga a taxa cheia e só então reparte, então o teto do rateio é o **líquido** (valor da cobrança menos a taxa), não o bruto. O rateio acontece na liquidação, não na criação. Estorno e MED debitam **só o originador** — quem recebeu rateio nunca é debitado.

  Veja [Split de Pagamento](/#split-de-pagamento) para as regras completas, os exemplos e a tabela de erros.
</Note>

<Note>
  **Escolha da instituição.** Se a sua conta tem essa opção habilitada, o campo opcional `pspCredentialId` fixa a instituição que emite esta cobrança, ignorando o roteamento configurado. Copie o ID em **Configurações → Roteamento** no painel.

  Fixar **não é preferir**: se a instituição estiver fora do ar ou sem capacidade, a cobrança falha em vez de sair por outra. A resposta ecoa `pspCredentialId` como recibo.

  Veja [Escolha da Instituição](/#escolha-da-instituição) para as regras completas e a tabela de erros.
</Note>


## OpenAPI

````yaml openapi.json POST /pix
openapi: 3.0.0
info:
  title: Jetpag API
  description: Jetpag Payment API documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.jetpag.com/v2
security: []
paths:
  /pix:
    post:
      tags:
        - External API - PIX
      summary: Criar uma cobrança PIX
      description: |-
        Cria uma cobrança PIX instantânea.

        **Permissão requerida:** `PIX:WRITE` ou `FULL_ACCESS`
      operationId: ExternalPixController_createCharge
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Chave única do cliente (8-255 chars) que torna a requisição
            idempotente. Retentativas com a mesma chave retornam a resposta
            cacheada (TTL 24h). Mesma chave com body diferente retorna 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: Cobrança PIX criada com sucesso
          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 da subconta em que a operação deve ser executada. Quando
        omitido, a operação acontece na conta principal; o valor reservado
        `principal` também resolve para a conta principal e é equivalente a
        omitir o header. Aceito em todos os endpoints, exceto `POST /auth` e os
        próprios endpoints de `/sub-accounts`, que sempre operam na conta
        principal.


        Erros possíveis: `404 SUB_ACCOUNT_NOT_FOUND`, `403
        SUB_ACCOUNT_FORBIDDEN`, `403 SUB_ACCOUNT_SUSPENDED`.


        Exige que a credencial tenha o **acesso a subcontas** habilitado
        (Configurações → Integração → Credenciais de API). Ele nasce desligado e
        não é substituído por nenhuma permissão, nem por `FULL_ACCESS`: sem ele
        a resposta é `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: 'Valor em BRL (ex: 100.50 para R$ 100,50)'
          minimum: 1
          example: 150.75
        description:
          type: string
          description: Descrição da cobrança
          maxLength: 255
          example: 'Pagamento do pedido #12345'
        customer:
          description: Dados do pagador (todos opcionais).
          allOf:
            - $ref: '#/components/schemas/CustomerDto'
        projectId:
          type: string
          description: >-
            ID do projeto para associar a transação. Se não informado e a conta
            tiver um único projeto, a cobrança herda esse projeto; com mais de
            um, a cobrança fica sem projeto.
          format: uuid
        pspCredentialId:
          type: string
          description: >-
            Fixa a instituição que emite esta cobrança, ignorando o roteamento
            configurado. Use o ID que aparece em Configurações → Roteamento no
            painel. Precisa ser uma instituição habilitada e ativa da sua conta.
            Se ela estiver fora do ar ou sem capacidade, a cobrança FALHA — não
            cai para outra: você pediu esta. Disponível para contas com a
            escolha de instituição habilitada.
          format: uuid
          example: 6e307aa4-4772-4230-a648-d88cee308f54
        expiresIn:
          type: integer
          description: 'Segundos até expiração (padrão: 86400 = 24h)'
          minimum: 300
          maximum: 604800
          example: 3600
        externalReference:
          type: string
          description: Seu ID de referência externa
          maxLength: 255
          example: pedido-12345
        metadata:
          type: object
          description: Metadados customizados (pares chave-valor)
          additionalProperties: true
          example:
            orderId: '12345'
            source: website
        split:
          type: array
          description: >-
            Reparte parte do valor com outras subcontas da mesma conta, na
            liquidação. Quem cria a cobrança é o originador: recebe o valor
            bruto, paga a taxa cheia e só então reparte — a taxa não é rateada
            entre os destinatários. A soma do split não pode exceder o líquido
            (valor da cobrança menos a taxa). Estorno e MED debitam apenas o
            originador; quem recebeu rateio nunca é debitado.
          maxItems: 10
          items:
            $ref: '#/components/schemas/PixSplitAllocationInput'
      required:
        - amount
        - description
    CreatePixChargeOutput:
      type: object
      properties:
        id:
          type: string
          description: ID da cobrança (ID da transação)
          format: uuid
        status:
          type: string
          description: Status da cobrança
          enum:
            - pending
            - completed
            - failed
            - cancelled
        amount:
          type: number
          description: Valor em BRL
          example: 150.75
        currency:
          type: string
          description: Código da moeda
          example: BRL
        pixCopyPaste:
          type: string
          description: Código PIX copia e cola
          example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
        qrCodeBase64:
          type: string
          description: QR Code do PIX em formato data URI (data:image/png;base64,...)
        pspPaymentId:
          type: string
          description: >-
            ID da transação no provedor de pagamento (PSP). Use para
            conciliação; ausente se o PSP não retornou o ID na criação.
          example: de3516a2-c63a-4c02-b132-a239bf42e183
        expiresAt:
          type: string
          description: Data de expiração
          format: date-time
        pspCredentialId:
          type: string
          description: >-
            Instituição que emitiu esta cobrança. Só vem quando você fixou a
            instituição no request (`pspCredentialId`), como recibo de que ela
            foi respeitada.
          format: uuid
          example: 6e307aa4-4772-4230-a648-d88cee308f54
        externalReference:
          type: string
          description: Seu ID de referência externa
          example: pedido-12345
        createdAt:
          type: string
          description: Data de criação
          format: date-time
        split:
          type: array
          description: >-
            Rateio aceito, em reais. Presente apenas quando a cobrança foi
            criada com split — se veio na resposta, as subcontas existiam e a
            soma cabia no líquido. O que foi efetivamente distribuído chega no
            webhook payment_completed.
          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: Nome do pagador
          maxLength: 255
          example: João da Silva
        document:
          type: string
          description: CPF ou CNPJ do pagador, apenas números (opcional)
          maxLength: 20
          example: '12345678909'
        email:
          type: string
          description: E-mail do pagador
          format: email
          maxLength: 255
        phone:
          type: string
          description: Telefone do pagador (formato livre)
          maxLength: 20
          example: '+5511999998888'
    PixSplitAllocationInput:
      type: object
      properties:
        subAccount:
          type: string
          description: >-
            Reference de uma subconta ativa da mesma conta que recebe o rateio.
            A palavra reservada `principal` endereça a conta principal — use
            quando a cobrança for originada por uma subconta (header
            `X-Sub-Account`); uma cobrança criada pela própria conta principal
            não pode ratear para `principal`.
          pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
          example: loja-centro
        amount:
          type: number
          description: >-
            Valor em BRL destinado a essa carteira. Valor fixo — percentual não
            é aceito. No máximo 2 casas decimais.
          minimum: 0.01
          example: 30
      required:
        - subAccount
        - amount
    PixSplitAllocationOutput:
      type: object
      properties:
        subAccount:
          type: string
          description: >-
            Reference da subconta que recebe o rateio, ou `principal` quando o
            destino é a conta principal
          example: loja-centro
        amount:
          type: number
          description: Valor em BRL destinado a essa carteira
          example: 30
      required:
        - subAccount
        - amount
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtido no POST /auth (client_id + client_secret). Válido
        por 300 segundos.

````