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

# Grade de parcelas

> A tabela de parcelamento para um valor, calculada pelo mesmo código que roda no checkout.

<Note>
  A grade vem bandeira por bandeira porque a bandeira só é conhecida quando o comprador digita os
  seis primeiros dígitos. Mostre a chave `default` antes disso — ela é o pior caso, então o preço
  nunca sobe depois. Ver [Cobrança no cartão](/essenciais/cartao).
</Note>


## OpenAPI

````yaml api-reference/openapi.yaml GET /v1/installments
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`.

    ## Dinheiro é sempre CENTAVOS INTEIROS

    Não há exceção. `amount`, `platform_fee`, `net_amount`, `refunded_amount`,
    `fee_returned`, `seller_debit`, `balance`, `available`, `reserved`, `debt`
    e `withdrawable` são inteiros em centavos de real.

    | Valor       | Envie / receba |
    |-------------|----------------|
    | R$ 1,00     | `100`          |
    | R$ 10,50    | `1050`         |
    | R$ 1.234,56 | `123456`       |

    Enviar `10.50` devolve `422`. A recusa é deliberada: `10.50` chega ao
    servidor como ponto flutuante, `10.50 * 100` não é exatamente `1050` em
    binário, e o centavo perdido só aparece na conciliação do mês. Diante de
    um decimal preferimos recusar a adivinhar a intenção - com dinheiro,
    adivinhar sai caro.

    ## Autenticação

    Toda chamada leva a chave no header:

    ```
    Authorization: Bearer sk_live_SUA_CHAVE_SECRETA
    ```

    A chave é criada em **Desenvolvedores** no painel e o valor em claro
    aparece **uma única vez**, na criação - guardamos apenas um hash
    SHA-256. Perdeu, gere outra.

    Cada chave carrega escopos (`charges:read`, `charges:write`,
    `refunds:write`, `balance:read`, `cards:manage`). Chamar um endpoint
    fora do escopo devolve `403`, e não `401`: a chave está certa, faltou
    permissão.

    Chaves de teste usam o prefixo `sk_test_`. A diferença é visível a olho
    nu de propósito - uma chave de teste colada em produção precisa ser
    reconhecível antes de alguém passar a tarde investigando.

    ## Idempotência

    Envie `Idempotency-Key` em todo `POST`. A conexão que cai depois da
    requisição e antes da resposta deixa você sem saber se cobrou; repetir
    com a mesma chave resolve isso sem risco de cobrar duas vezes.

    - **mesma chave, mesmo corpo** → a resposta gravada, com
      `Idempotent-Replayed: true`. A cobrança não é recriada.
    - **mesma chave, corpo diferente** → `409 idempotency_key_reused`.
      Devolver a cobrança antiga faria você acreditar que cobrou o valor
      novo.
    - **mesma chave, primeira ainda em voo** → `409
      idempotency_key_in_progress`. Repita em instantes.

    A ordem dos campos no JSON não invalida o retry. A chave vale por 24
    horas e é sua: dois clientes diferentes podem usar `pedido-1` sem
    colidir.

    ## Erros

    Todo erro - inclusive os que não previmos - tem a mesma forma:

    ```json
    {
      "error": {
        "type": "invalid_request_error",
        "code": "amount_below_minimum",
        "message": "…",
        "details": {}
      }
    }
    ```

    Trate pelo `code`, nunca pela `message`: o código é contrato, o texto
    pode ser reescrito a qualquer momento.
  contact:
    name: Suporte Vext
    url: https://wa.me/5511936185272
servers:
  - url: https://api.usevext.com
    description: Produção
security:
  - apiKey: []
tags:
  - name: Cobranças
    description: Criação, consulta e estorno de cobranças, no PIX e no cartão.
  - name: Saldo
    description: Quanto o vendedor tem e quanto pode sacar.
  - name: Cartões
    description: |
      Os cartões que os compradores deixaram guardados, para cobrar de novo
      sem pedir nada a eles.
paths:
  /v1/installments:
    get:
      tags:
        - Cobranças
      summary: Grade de parcelas
      description: |
        A tabela de parcelamento para um valor, do lado do **seu servidor**.

        O cálculo é nosso e é o mesmo que roda no nosso checkout.
        Reimplementá-lo do seu lado para poupar esta chamada criaria duas
        contas capazes de divergir - e divergir aqui é anunciar um preço e
        nós cobrarmos outro.

        A grade vem inteira, bandeira por bandeira, porque a bandeira só é
        conhecida quando o comprador digita os seis primeiros dígitos. A
        chave `default` é o pior caso, e é o que se mostra antes disso.

        Esta **diz por que** o cartão está indisponível: quem apresenta a
        chave secreta é o seu servidor, e o motivo é acionável para você.
      operationId: listInstallments
      parameters:
        - name: amount
          in: query
          required: true
          description: O valor a parcelar, em **centavos inteiros**.
          schema:
            type: integer
            minimum: 1
          example: 10000
        - name: max_installments
          in: query
          description: |
            O teto que você quer impor. O limite real é o **menor** entre
            ele, a escada por valor e a taxa da sua conta - um número maior
            aqui não amplia nada.
          schema:
            type: integer
            minimum: 1
            maximum: 12
      responses:
        '200':
          description: A grade, ou o motivo de não haver uma.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Installments'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey:
            - charges:read
components:
  schemas:
    Installments:
      type: object
      description: |
        A grade de parcelamento para um valor, como o SEU SERVIDOR a
        recebe. **Todo campo está sempre presente** - `message` e
        `unavailable_reason` vêm `null` quando há grade, e `matrix` vem
        `{}` quando não há.
      required:
        - object
        - amount
        - available
        - unavailable_reason
        - message
        - matrix
      properties:
        object:
          type: string
          const: installments
        amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: O valor consultado, de volta, em centavos inteiros.
        available:
          type: boolean
        unavailable_reason:
          type:
            - string
            - 'null'
          description: |
            Por que não há grade. Trate por ele, nunca pela `message`.

            As seis primeiras são chaves de configuração, e cada uma tem
            dono diferente: a plataforma, a conta Pagar.me que atende a sua
            loja, o interruptor da sua conta, o status do seu cadastro, a
            credencial do provedor e o seu contrato de taxa.
            `amount_below_minimum` é outra coisa - o cartão está de pé, o
            que não cabe é este valor.
          enum:
            - platform_disabled
            - gateway_account_disabled
            - seller_disabled
            - seller_cannot_transact
            - no_credential
            - fee_disabled
            - amount_below_minimum
            - null
        message:
          type:
            - string
            - 'null'
          description: A frase em português, para o seu log. Não é contrato.
        matrix:
          type: object
          description: |
            Mapa de bandeira para lista de opções. **Objeto vazio**, nunca
            lista vazia, quando não há grade.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/InstallmentOption'
    Cents:
      type: integer
      format: int64
      description: |
        Valor monetário em **centavos inteiros** de real. R$ 10,00 = `1000`.
        Nunca decimal, nunca string.
    InstallmentOption:
      type: object
      required:
        - installments
        - total_cents
        - installment_cents
        - interest_cents
        - label
      properties:
        installments:
          type: integer
          minimum: 1
          maximum: 12
        total_cents:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: O que o comprador paga no total, já com juros.
        installment_cents:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: O valor de cada parcela.
        interest_cents:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Os juros embutidos, em centavos inteiros. `0` nas parcelas sem
            juros. Eles viajam até a Pagar.me como um ITEM à parte, e é por
            isso que o comprador vê a conta separada na tela.
        label:
          type: string
          description: A opção já escrita para a tela, em português.
          example: 12x de R$ 10,65
    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
                - card_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
  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
            umClique:
              summary: one_click_requires_three_ds
              value:
                error:
                  type: permission_error
                  code: one_click_requires_three_ds
                  message: >-
                    Esta loja exige autenticação do portador, e o pagamento de
                    um clique não a suporta.
                  details: {}
    ValidationFailed:
      description: Campos inválidos.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            validacao:
              value:
                error:
                  type: invalid_request_error
                  code: validation_failed
                  message: Alguns campos não passaram na validação.
                  details:
                    amount:
                      - >-
                        O valor deve ser um inteiro em centavos (R$ 10,00 =
                        1000).
    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.

````