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

# Consultar cobrança

> Busca uma cobrança pelo código público ch_….

<Note>
  O `404` não distingue "não existe" de "existe, mas é de outra conta". Responder a diferença
  confirmaria a existência de cobranças alheias a quem tentasse adivinhar códigos.
</Note>


## OpenAPI

````yaml api-reference/openapi.yaml GET /v1/charges/{code}
openapi: 3.1.0
info:
  title: Vext - API de pagamentos PIX com split
  version: 1.0.0
  summary: Cobranças PIX, estornos e saldo do vendedor.
  description: |
    API pública do gateway. Todo endpoint desta versão vive sob `/v1`.

    Quatro regras valem para toda chamada. Cada uma tem uma página própria
    nos guias, com exemplos nas quatro linguagens.

    - **Dinheiro é sempre centavos inteiros.** R$ 100,00 se envia como
      `10000`; um decimal devolve `422`. Ver
      [Valores em centavos](/essenciais/valores-em-centavos).
    - **A chave secreta vai no header e fica no servidor.** Cada chave
      carrega escopos; fora do escopo devolve `403`, e não `401`. Ver
      [Autenticação](/essenciais/autenticacao).
    - **Envie `Idempotency-Key` em todo `POST`.** Repetir com a mesma chave
      devolve a resposta gravada em vez de criar um segundo recurso. Ver
      [Idempotência](/essenciais/idempotencia).
    - **Trate os erros pelo `code`**, nunca pela `message` - o código é
      contrato, o texto pode ser reescrito a qualquer momento. Ver
      [Erros](/essenciais/erros).
  contact:
    name: Suporte Vext
    email: suporte@usevext.com
servers:
  - url: https://api.usevext.com
    description: Produção
security:
  - apiKey: []
tags:
  - name: Cobranças
    description: Criação, consulta e estorno de cobranças PIX.
  - name: Saldo
    description: Quanto o vendedor tem e quanto pode sacar.
paths:
  /v1/charges/{code}:
    get:
      tags:
        - Cobranças
      summary: Consultar cobrança
      operationId: getCharge
      parameters:
        - $ref: '#/components/parameters/ChargeCode'
      responses:
        '200':
          description: A cobrança.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
              examples:
                paga:
                  $ref: '#/components/examples/ChargePaga'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey:
            - charges:read
components:
  parameters:
    ChargeCode:
      name: code
      in: path
      required: true
      description: Código público da cobrança, no formato `ch_…`.
      schema:
        type: string
        pattern: ^ch_[0-9a-z]{26}$
      example: ch_01k1y6r6m6q2x0p3d9v4t7c8n2
  schemas:
    Charge:
      type: object
      required:
        - object
        - id
        - status
        - payment_method
        - amount
        - currency
      properties:
        object:
          type: string
          const: charge
        id:
          type: string
          description: |
            Código público da cobrança. Nunca é a chave primária: expor o
            autoincremento diria a qualquer cliente quantas vendas a
            plataforma inteira processou.
          example: ch_01k1y6r6m6q2x0p3d9v4t7c8n2
        status:
          $ref: '#/components/schemas/ChargeStatus'
        payment_method:
          type: string
          enum:
            - pix
        amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: Valor cobrado, em centavos inteiros.
        currency:
          type: string
          const: BRL
        platform_fee:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Nossa taxa, em centavos inteiros. Congelada na criação: reflete
            o contrato que valia quando a venda aconteceu, não o de hoje.
        net_amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            O que fica com o vendedor, em centavos inteiros
            (`amount - platform_fee`).
        refunded_amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Total já devolvido ao comprador, em centavos inteiros. Acumulado
            entre estornos parciais.
        description:
          type:
            - string
            - 'null'
        reference:
          type:
            - string
            - 'null'
        customer:
          $ref: '#/components/schemas/CustomerSummary'
        pix:
          type: object
          properties:
            qr_code:
              type:
                - string
                - 'null'
              description: |
                Payload copia-e-cola do PIX. Gere a imagem do QR a partir
                dele - não devolvemos PNG.
            expires_at:
              type:
                - string
                - 'null'
              format: date-time
            end_2_end_id:
              type:
                - string
                - 'null'
              description: |
                Identificador da transação no Sistema de Pagamentos
                Brasileiro. Aparece depois do pagamento e é o que o banco do
                comprador reconhece.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        expired_at:
          type:
            - string
            - 'null'
          format: date-time
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
    ChargeStatus:
      type: string
      description: |
        Situação da cobrança. Todos os estados exceto `pending` são
        terminais - exceto os que ainda admitem estorno.

        `partially_refunded` é estado próprio, e não um `refunded` com
        asterisco: tratar uma venda devolvida pela metade como estornada
        faria seu relatório descontar o valor inteiro.
      enum:
        - pending
        - paid
        - expired
        - canceled
        - partially_refunded
        - refunded
        - failed
      x-labels:
        pending: Aguardando pagamento
        paid: Pago
        expired: Expirado
        canceled: Cancelado
        partially_refunded: Estornado em parte
        refunded: Estornado
        failed: Falhou
    Cents:
      type: integer
      format: int64
      description: |
        Valor monetário em **centavos inteiros** de real. R$ 10,00 = `1000`.
        Nunca decimal, nunca string.
    CustomerSummary:
      type: object
      description: O comprador, como devolvemos.
      properties:
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        document:
          type:
            - string
            - 'null'
          description: |
            Mascarado. Você já enviou o documento; devolvê-lo inteiro em
            toda consulta espalharia o dado sem nenhum ganho.
          example: 111.***.***-35
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - details
          properties:
            type:
              type: string
              description: |
                Família do erro. Responde "de quem é o problema e o que
                fazer": `invalid_request_error` se corrige mudando a
                chamada, `authentication_error` trocando a chave, e
                `api_error` é nosso - repita, não reescreva.
              enum:
                - authentication_error
                - permission_error
                - invalid_request_error
                - idempotency_error
                - not_found_error
                - rate_limit_error
                - api_error
            code:
              type: string
              description: |
                Código estável do erro. **Trate por ele.** A `message` pode
                ser reescrita a qualquer momento; o código, não.
            message:
              type: string
              description: Explicação em português, para leitura humana.
            details:
              type: object
              description: |
                Sempre objeto, mesmo vazio. Em `validation_failed`, traz os
                campos recusados e suas mensagens.
              additionalProperties: true
  examples:
    ChargePaga:
      summary: Cobrança já paga
      value:
        object: charge
        id: ch_01k1y6r6m6q2x0p3d9v4t7c8n2
        status: paid
        payment_method: pix
        amount: 10000
        currency: BRL
        platform_fee: 798
        net_amount: 9202
        refunded_amount: 0
        description: Curso de Vue 3
        reference: pedido-1042
        customer:
          name: João Comprador
          email: joao@exemplo.com.br
          document: 111.***.***-35
        pix:
          qr_code: >-
            00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234
          expires_at: '2026-08-04T15:00:00+00:00'
          end_2_end_id: E12345678202608041200
        created_at: '2026-08-04T14:00:00+00:00'
        paid_at: '2026-08-04T14:03:11+00:00'
        expired_at: null
        refunded_at: null
  responses:
    Unauthorized:
      description: |
        Chave ausente, desconhecida, revogada ou expirada. A revogada é
        distinguida da inexistente na MENSAGEM, nunca no status: quem
        integra precisa saber que a chave existiu e foi desligada, e quem
        está adivinhando tokens não aprende nada com isso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ausente:
              summary: missing_api_key
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: 'Envie a chave em Authorization: Bearer sk_live_...'
                  details: {}
            invalida:
              summary: invalid_api_key
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: Chave de API inválida.
                  details: {}
            revogada:
              summary: revoked_api_key
              value:
                error:
                  type: authentication_error
                  code: revoked_api_key
                  message: >-
                    Esta chave de API foi revogada. Gere uma nova em
                    Desenvolvedores.
                  details: {}
            expirada:
              summary: expired_api_key
              value:
                error:
                  type: authentication_error
                  code: expired_api_key
                  message: Esta chave de API expirou. Gere uma nova em Desenvolvedores.
                  details: {}
    Forbidden:
      description: |
        A chave é válida, mas não tem o escopo do endpoint. `403` e não
        `401` de propósito: `401` diria "sua chave está errada" a quem tem
        a chave certa.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            escopo:
              summary: insufficient_scope
              value:
                error:
                  type: permission_error
                  code: insufficient_scope
                  message: Esta chave não tem o escopo [refunds:write].
                  details:
                    required_ability: refunds:write
                    abilities:
                      - charges:read
                      - charges:write
    NotFound:
      description: |
        O recurso não existe - ou é de outra conta, o que daqui dá no
        mesmo. Não distinguimos os dois casos: responder "existe, mas não é
        seu" confirmaria a existência de cobranças alheias a quem tentasse
        adivinhar códigos.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            naoEncontrado:
              value:
                error:
                  type: not_found_error
                  code: resource_not_found
                  message: Recurso não encontrado.
                  details: {}
    RateLimited:
      description: |
        Requisições demais.

        Há três limites, por minuto: um por IP antes da autenticação, e
        depois um de leitura e um de escrita, ambos por CHAVE - o excesso
        de uma integração não consome a cota das outras do mesmo
        vendedor. A escrita é bem mais apertada porque cada cobrança
        criada vira uma chamada ao provedor.

        `Retry-After` diz em quantos segundos voltar. Os cabeçalhos
        `X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que
        permitem desacelerar antes de bater no limite.
      headers:
        Retry-After:
          description: Segundos até a cota ser reposta.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requisições permitidas por minuto neste balde.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Quantas ainda cabem no minuto corrente.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            cota:
              summary: too_many_requests
              value:
                error:
                  type: rate_limit_error
                  code: too_many_requests
                  message: Muitas requisições. Tente novamente em 42 segundos.
                  details:
                    retry_after: 42
            provedor:
              summary: provider_rate_limited
              value:
                error:
                  type: rate_limit_error
                  code: provider_rate_limited
                  message: >-
                    Limite de requisições do provedor atingido. Tente novamente
                    em instantes.
                  details: {}
    InternalError:
      description: |
        Erro inesperado do nosso lado. Repita com a mesma
        `Idempotency-Key` - ela é o que torna repetir seguro.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            interno:
              value:
                error:
                  type: api_error
                  code: internal_error
                  message: >-
                    Erro interno. Se persistir, informe o horário da chamada ao
                    suporte.
                  details: {}
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_… | sk_test_…
      description: |
        Chave secreta do vendedor, criada no painel em **Desenvolvedores**.

        O valor em claro existe uma única vez, na criação. Guardamos só o
        hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto:
        um dump do nosso banco não permite cobrar em nome de ninguém.

        A chave vai no **servidor**. Colocá-la no navegador do comprador a
        entrega a qualquer pessoa que abra a página.

````