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

# Pagar cobrança (pagamento transparente)

> Cria o pagamento de uma cobrança da loja da chave sem tirar o comprador do seu site: PIX (copia-e-cola e QR), boleto (linha digitável e PDF) ou cartão.

O gateway é decidido pela Gravity Play, pela mesma regra do checkout hospedado (veja `GET /v1/payment-methods`); taxa da plataforma, split, parcelamento, e-mails e webhooks são os mesmos. O cartão vai **aberto** só quando o gateway de cartão da loja é Asaas (`card.input = raw`); Pagar.me e Efí recebem `card.token`, gerado no navegador; Stripe só pelo checkout hospedado.

Já existindo um PIX (com mais de 5 minutos de validade) ou boleto (dentro do vencimento) pendente do mesmo método nesta cobrança, ele é devolvido de novo com **200**, sem gerar outro. Duas chamadas simultâneas para a mesma cobrança: uma é atendida e a outra recebe 409 `payment_in_progress`.

O IP do comprador vem de `buyer.ip` (obrigatório no cartão Asaas), nunca do IP da requisição.

Escopo exigido: `charges:write`.



## OpenAPI

````yaml /openapi.json post /v1/charges/{id}/payments
openapi: 3.1.0
info:
  title: Gravity Play API
  version: 1.0.0
  description: >-
    API para criar cobranças, receber pagamentos e ler cursos, turmas, alunos e
    progresso da área de membros. Cada chave de API tem escopos; cada operação
    indica o escopo que exige.
servers:
  - url: https://api.sandbox.gravitypay.app
    description: Sandbox (testes) — alvo do try-it
  - url: https://api.gravitypay.app
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Cobranças
    description: >-
      Cobranças avulsas: link de pagamento (checkout hospedado) ou pagamento
      transparente (PIX, boleto e cartão pela API).
  - name: Pagamentos
    description: Vendas da loja e vendedores.
  - name: Assinaturas
    description: Assinaturas da loja, com dados do cliente. Exige `subscriptions:read`.
  - name: Cursos
    description: Cursos da área de membros, com módulos e aulas.
  - name: Turmas
    description: Turmas dos cursos.
  - name: Alunos
    description: 'Alunos, matrículas e progresso. Dado pessoal: exige `students:read`.'
paths:
  /v1/charges/{id}/payments:
    post:
      tags:
        - Cobranças
      summary: Pagar cobrança (pagamento transparente)
      description: >-
        Cria o pagamento de uma cobrança da loja da chave sem tirar o comprador
        do seu site: PIX (copia-e-cola e QR), boleto (linha digitável e PDF) ou
        cartão.


        O gateway é decidido pela Gravity Play, pela mesma regra do checkout
        hospedado (veja `GET /v1/payment-methods`); taxa da plataforma, split,
        parcelamento, e-mails e webhooks são os mesmos. O cartão vai **aberto**
        só quando o gateway de cartão da loja é Asaas (`card.input = raw`);
        Pagar.me e Efí recebem `card.token`, gerado no navegador; Stripe só pelo
        checkout hospedado.


        Já existindo um PIX (com mais de 5 minutos de validade) ou boleto
        (dentro do vencimento) pendente do mesmo método nesta cobrança, ele é
        devolvido de novo com **200**, sem gerar outro. Duas chamadas
        simultâneas para a mesma cobrança: uma é atendida e a outra recebe 409
        `payment_in_progress`.


        O IP do comprador vem de `buyer.ip` (obrigatório no cartão Asaas), nunca
        do IP da requisição.


        Escopo exigido: `charges:write`.
      operationId: createChargePayment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargePaymentRequest'
            examples:
              pix:
                summary: PIX
                value:
                  method: pix
                  buyer:
                    name: Maria da Silva
                    email: maria@exemplo.com
                    document: 529.982.247-25
                    phone: (11) 99999-9999
                  metadata:
                    pedido: A-1
              cartaoAsaas:
                summary: Cartão aberto (loja Asaas)
                value:
                  method: credit_card
                  installments: 3
                  buyer:
                    name: Maria da Silva
                    email: maria@exemplo.com
                    document: 529.982.247-25
                    phone: (11) 99999-9999
                    ip: 203.0.113.10
                    address:
                      zipCode: 01001-000
                      number: '100'
                  card:
                    number: 4111 1111 1111 1111
                    holderName: MARIA DA SILVA
                    expiryMonth: '12'
                    expiryYear: '33'
                    cvv: '123'
              cartaoPagarme:
                summary: Cartão tokenizado (loja Pagar.me)
                value:
                  method: credit_card
                  buyer:
                    name: Maria da Silva
                    email: maria@exemplo.com
                    document: 529.982.247-25
                    phone: (11) 99999-9999
                    address:
                      zipCode: 01001-000
                      street: Praça da Sé
                      number: '100'
                      neighborhood: Sé
                      city: São Paulo
                      state: SP
                  card:
                    token: token_abc123
      responses:
        '200':
          description: PIX ou boleto pendente reaproveitado (nenhum gateway chamado).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargePayment'
        '201':
          description: Pagamento criado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargePayment'
              examples:
                pix:
                  summary: PIX
                  value:
                    object: payment
                    id: cmusg5quw000mypfs3g9daah2
                    chargeId: chg_c7fb440eb3112525e35718d4488d66c8
                    status: pending
                    method: pix
                    provider: ASAAS
                    amountInCents: 15900
                    totalInCents: 15900
                    installments: 1
                    pix:
                      copyPaste: 00020126580014br.gov.bcb.pix0136...6304ABCD
                      qrCodeBase64: iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAACAvzbMAAA...
                      qrCodeUrl: null
                      expiresAt: '2026-10-05T02:59:59.000Z'
                    boleto: null
                    createdAt: '2026-10-03T13:47:55.064Z'
                cartao:
                  summary: Cartão aprovado em 3x (juro repassado)
                  value:
                    object: payment
                    id: cmusg5qw0000oypfsr457yf31
                    chargeId: chg_94fb8e2c5f985ff1b1d1a92366c4ca3b
                    status: paid
                    method: credit_card
                    provider: ASAAS
                    amountInCents: 15900
                    totalInCents: 17467
                    installments: 3
                    pix: null
                    boleto: null
                    createdAt: '2026-10-03T13:47:55.104Z'
                boleto:
                  summary: Boleto
                  value:
                    object: payment
                    id: cmusg5qww000sypfs2nlgpnbm
                    chargeId: chg_172a6fba06d85b9dd531b10e1361e660
                    status: pending
                    method: boleto
                    provider: ASAAS
                    amountInCents: 15900
                    totalInCents: 15900
                    installments: 1
                    pix: null
                    boleto:
                      line: '00190000090275928800021932978170187890000005000'
                      barcode: '00191878900000050000000002759288002193297817'
                      url: https://www.asaas.com/b/pdf/...
                      pdfUrl: https://www.asaas.com/b/pdf/...
                      expiresAt: '2026-10-05T02:59:59.000Z'
                    createdAt: '2026-10-03T13:47:55.136Z'
        '400':
          description: >-
            Corpo inválido ou dado obrigatório do gateway da loja faltando
            (`invalid_request`, com `param`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: invalid_request
                  message: A Pagar.me exige o endereço completo do comprador.
                  param: buyer.address.street
        '401':
          $ref: '#/components/responses/Error'
        '402':
          description: >-
            Cartão recusado (`payment_declined`). A mensagem do gateway só vem
            quando ele a marca como segura para o comprador; senão, mensagem
            genérica.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: payment_declined
                  code: payment_declined
                  message: >-
                    Não foi possível processar o pagamento. Confira os dados e
                    tente novamente.
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          description: >-
            Cobrança de outra loja, inexistente ou de link de pagamento
            (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: not_found
                  message: Cobrança não encontrada.
        '409':
          description: >-
            Cobrança fora de `pending` (`charge_not_pending`) ou outro pagamento
            dela em andamento (`payment_in_progress`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: conflict
                  code: payment_in_progress
                  message: >-
                    Já existe um pagamento desta cobrança em andamento. Tente de
                    novo em instantes.
        '422':
          description: >-
            Loja sem gateway para o método (`method_unavailable`) ou formato de
            cartão errado para o gateway (`card_input_not_supported`: cartão
            aberto no Pagar.me/Efí, token no Asaas, qualquer cartão no Stripe).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: unprocessable
                  code: method_unavailable
                  message: A loja não tem gateway pronto para este método de pagamento.
        '502':
          description: Gateway fora do ar ou erro não mapeado (`gateway_error`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: gateway_error
                  code: gateway_error
                  message: >-
                    Não foi possível processar o pagamento. Confira os dados e
                    tente novamente.
components:
  schemas:
    ChargePaymentRequest:
      type: object
      required:
        - method
        - buyer
      description: >-
        Pagamento da API transparente. Além do schema, cada gateway exige:
        **Asaas** — PIX/boleto: nome, e-mail, documento e telefone; cartão:
        também `buyer.ip`, `buyer.address.zipCode`/`number` e o cartão aberto.
        **Pagar.me** — PIX: nome, e-mail, documento e telefone; boleto e cartão:
        também o endereço completo (CEP, rua, número, cidade, UF); cartão:
        `card.token`. **Efí** — só cartão, com `card.token`. Faltando, 400 com
        `param`.
      properties:
        method:
          type: string
          enum:
            - pix
            - boleto
            - credit_card
        buyer:
          type: object
          required:
            - name
            - email
            - document
            - phone
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 200
              description: Vai ao gateway cortado em 64 caracteres.
            email:
              type: string
              format: email
            document:
              type: string
              description: >-
                CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem máscara, com
                dígito verificador válido.
            phone:
              type: string
              description: 'Com DDD: pelo menos 10 dígitos.'
            ip:
              type: string
              description: >-
                IP (v4 ou v6) do COMPRADOR. Obrigatório no cartão Asaas. Nunca é
                lido do IP da requisição.
            address:
              type: object
              required:
                - zipCode
                - number
              properties:
                zipCode:
                  type: string
                  description: CEP (8 dígitos, com ou sem máscara).
                street:
                  type: string
                number:
                  type: string
                complement:
                  type: string
                neighborhood:
                  type: string
                city:
                  type: string
                state:
                  type: string
                  minLength: 2
                  maxLength: 2
                  description: UF.
        installments:
          type: integer
          minimum: 1
          maximum: 12
          description: Só no cartão; até o `maxInstallments` da cobrança.
        boletoDueInDays:
          type: integer
          minimum: 1
          maximum: 60
          description: >-
            Vencimento deste boleto, em dias. Vence o `boletoDueInDays` da
            cobrança e o padrão da loja.
        card:
          type: object
          description: >-
            Cartão aberto (`number`, `holderName`, `expiryMonth`, `expiryYear`,
            `cvv`) só em loja Asaas; `token` (e `threedsTransactionId`, Pagar.me
            3DS, opcional) em Pagar.me e Efí.
          properties:
            number:
              type: string
            holderName:
              type: string
            expiryMonth:
              type: string
              description: 1 a 12.
            expiryYear:
              type: string
              description: 2 ou 4 dígitos ("33" vira "2033").
            cvv:
              type: string
            token:
              type: string
              description: '`card_token` da Pagar.me ou `payment_token` da Efí.'
            threedsTransactionId:
              type: string
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Vai para o pagamento (`metadata` dos webhooks `payment.*` dos
            endpoints do painel).
    ChargePayment:
      type: object
      required:
        - object
        - id
        - chargeId
        - status
        - method
        - provider
        - amountInCents
        - totalInCents
        - installments
        - pix
        - boleto
        - createdAt
      properties:
        object:
          type: string
          example: payment
        id:
          type: string
          description: >-
            Id do pagamento na Gravity Play: o mesmo `data.id` dos webhooks
            `payment.*`.
        chargeId:
          type: string
        status:
          type: string
          enum:
            - pending
            - paid
            - failed
            - refunded
          description: '`failed` cobre recusa e PIX vencido.'
        method:
          type: string
          enum:
            - pix
            - boleto
            - credit_card
        provider:
          type: string
          enum:
            - ASAAS
            - PAGARME
            - EFI
        amountInCents:
          type: integer
          description: Valor da cobrança.
        totalInCents:
          type: integer
          description: Valor cobrado, com o juro do parcelamento quando o comprador paga.
        installments:
          type: integer
        pix:
          type: object
          nullable: true
          properties:
            copyPaste:
              type: string
              description: PIX copia-e-cola (EMV).
            qrCodeBase64:
              type: string
              description: >-
                QR Code em PNG (base64, sem o prefixo `data:`), gerado a partir
                do copia-e-cola, igual para todo gateway.
            qrCodeUrl:
              type: string
              nullable: true
              description: URL do QR hospedado pela Pagar.me (só na criação).
            expiresAt:
              type: string
              format: date-time
              nullable: true
        boleto:
          type: object
          nullable: true
          properties:
            line:
              type: string
              nullable: true
              description: Linha digitável. `null` só quando o gateway não devolve.
            barcode:
              type: string
              nullable: true
            url:
              type: string
              nullable: true
            pdfUrl:
              type: string
              nullable: true
            expiresAt:
              type: string
              format: date-time
              nullable: true
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              description: >-
                `authentication` (401), `insufficient_scope` (403), `forbidden`
                (403, rota de parceiro chamada por outra loja),
                `invalid_request` (400), `not_found` (404) e, no pagamento
                transparente, `payment_declined` (402), `conflict` (409),
                `unprocessable` (422) e `gateway_error` (502).
            code:
              type: string
              description: >-
                Detalhe do `type` no pagamento transparente:
                `charge_not_pending`, `payment_in_progress`,
                `method_unavailable`, `card_input_not_supported`,
                `payment_declined` ou `gateway_error`.
            message:
              type: string
            param:
              type: string
              description: Parâmetro que falhou, em `invalid_request`.
            requiredScope:
              type: string
              description: Escopo que falta, em `insufficient_scope`.
  responses:
    Error:
      description: Erro
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientScope:
      description: A chave é válida, mas não tem o escopo exigido pela operação.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: insufficient_scope
              message: Esta chave de API não tem o escopo students:read.
              requiredScope: students:read
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.