Cobranças

Uma cobrança (charge) é um pagamento avulso — não precisa estar ligado a um produto. Você envia os itens e a Gravity Play calcula o total, monta o checkout e devolve a checkoutUrl.

Criando uma cobrança

curl https://api.gravitypay.app/v1/charges \
  -H "Authorization: Bearer gp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "usd",
    "items": [
      { "name": "Polishment", "quantity": 1, "unitAmountInCents": 4900 },
      { "name": "Oil Car",    "quantity": 2, "unitAmountInCents": 4000 }
    ],
    "customer": { "email": "client@acme.com", "name": "Acme Inc." },
    "description": "Invoice #1234",
    "metadata": { "invoiceId": "1234" },
    "postbackUrl": "https://acme.com/webhooks/gravitypay",
    "successUrl": "https://acme.com/paid",
    "cancelUrl": "https://acme.com/canceled"
  }'

const res = await fetch("https://api.gravitypay.app/v1/charges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GRAVITYPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    currency: "usd",
    items: [
      { name: "Polishment", quantity: 1, unitAmountInCents: 4900 },
      { name: "Oil Car", quantity: 2, unitAmountInCents: 4000 },
    ],
    customer: { email: "client@acme.com", name: "Acme Inc." },
    description: "Invoice #1234",
    metadata: { invoiceId: "1234" },
    postbackUrl: "https://acme.com/webhooks/gravitypay",
  }),
});
const charge = await res.json();
// → redirecione o cliente para charge.checkoutUrl

Resposta

{
  "id": "chg_2e59538f643480debcbfd7e1543a2297",
  "object": "charge",
  "status": "pending",
  "amountInCents": 12900,
  "currency": "usd",
  "items": [
    { "name": "Polishment", "quantity": 1, "unitAmountInCents": 4900 },
    { "name": "Oil Car", "quantity": 2, "unitAmountInCents": 4000 }
  ],
  "checkoutUrl": "https://gravitypay.app/c/chg_2e59538f...",
  "postbackSecret": "whsec_2f9c...",
  "metadata": { "invoiceId": "1234" }
}

Guarde o postbackSecret. Ele é retornado apenas na criação e serve para validar a assinatura dos webhooks (postbackUrl) desta cobrança. Veja Webhooks.

Os itens

Cada item tem name, quantity e unitAmountInCents. O total é a soma de quantity × unitAmountInCents de todos os itens, e é renderizado no checkout como uma linha de pedido:

1×  Polishment      $ 49,00
2×  Oil Car         $ 80,00
─────────────────────────────
Total               $ 129,00

Se preferir, você pode omitir items e enviar apenas amountInCents (cobrança sem detalhamento).

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`currency`	string	sim	Código ISO de 3 letras (ex.: `usd`, `brl`).
`items`	array	—	Itens `{ name, quantity, unitAmountInCents }`. Definem o total.
`amountInCents`	integer	—	Total em centavos (use quando não enviar `items`).
`customer`	object	—	`{ email, name }` do pagador.
`description`	string	—	Aparece no topo do checkout (ex.: “Invoice #1234”).
`metadata`	object	—	Pares chave/valor seus. Voltam nos webhooks.
`postbackUrl`	string	—	URL que recebe os webhooks desta cobrança.
`successUrl`	string	—	Redireciona o cliente após o pagamento.
`cancelUrl`	string	—	Redireciona o cliente se ele cancelar.
`boletoDueInDays`	integer	—	Vencimento do boleto desta cobrança, em dias (1 a 60).
`maxInstallments`	integer	—	Máximo de parcelas no cartão (1 a 12; padrão 1).
`passInstallmentInterest`	boolean	—	`true` (padrão): o comprador paga o juro; `false`: a loja absorve.
`payment`	object	—	Pagamento junto com a cobrança. Veja Pagamento transparente.

Vencimento do boleto

Quando o cliente paga a cobrança com boleto, o prazo de vencimento é resolvido nesta ordem:

O campo dueInDays enviado na chamada que gera o boleto (só existe para quem monta o próprio checkout).
O campo boletoDueInDays da cobrança, enviado no POST /v1/charges.
O prazo configurado no produto (não se aplica à cobrança avulsa, que não tem produto).
O padrão da loja, em Configurações da loja → Vencimento padrão dos boletos.
1 dia, quando nada foi configurado.

Use boletoDueInDays se o seu cliente paga no checkout hospedado. O checkout roda no navegador do comprador e não conhece o prazo que o seu sistema prometeu — gravá-lo na cobrança é o que garante o vencimento certo. Uma vez enviado, mudar a configuração da loja ou do produto no painel não reescreve o que você pediu. O valor aceito vai de 1 a 60 dias.

Boletos já emitidos não mudam: o vencimento é impresso no documento. Uma alteração de configuração vale da próxima emissão em diante.

Pagamento transparente

Com o pagamento transparente, o comprador paga sem sair do seu site: você recebe o PIX (copia-e-cola e QR Code), o boleto (linha digitável e PDF) ou o resultado do cartão direto na resposta da API, em vez de redirecionar para a checkoutUrl. O gateway de cada método é decidido pela Gravity Play, pela mesma regra do checkout hospedado. Taxa da plataforma, split, parcelamento, e-mails e webhooks são exatamente os mesmos.

1. Consulte o que a loja aceita

curl "https://api.gravitypay.app/v1/payment-methods?amountInCents=15900&maxInstallments=3" \
  -H "Authorization: Bearer gp_live_..."

{
  "object": "payment_methods",
  "pix":    { "available": true, "provider": "ASAAS" },
  "boleto": { "available": true, "provider": "ASAAS" },
  "card": {
    "available": true,
    "provider": "ASAAS",
    "input": "raw",
    "pagarmePublicKey": null,
    "efiPayeeCode": null,
    "efiSandbox": false
  },
  "installments": [
    { "count": 1, "installmentInCents": 15900, "totalInCents": 15900, "hasInterest": false },
    { "count": 2, "installmentInCents": 8501,  "totalInCents": 17002, "hasInterest": true },
    { "count": 3, "installmentInCents": 5822,  "totalInCents": 17467, "hasInterest": true }
  ]
}

card.input diz como o cartão deve chegar:

`card.input`	Gateway	Como enviar o cartão
`raw`	Asaas	Aberto: `number`, `holderName`, `expiryMonth`, `expiryYear`, `cvv`.
`pagarme_token`	Pagar.me	`card.token`, gerado no navegador com a `pagarmePublicKey`.
`efi_token`	Efí	`card.token`, gerado no navegador com o `efiPayeeCode`.
`hosted_only`	Stripe	Só pelo checkout hospedado (`checkoutUrl`).

A tabela de parcelas só vem quando você manda amountInCents (sem ele, installments é null). Esta rota também serve para validar a chave ao salvá-la no seu sistema: 200 é chave boa, 401 é chave inválida e 403 é chave sem o escopo charges:read.

2. Crie a cobrança e o pagamento numa chamada

Mande o campo payment no POST /v1/charges:

curl https://api.gravitypay.app/v1/charges \
  -H "Authorization: Bearer gp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "currency": "brl",
    "amountInCents": 15900,
    "description": "Curso NR-35",
    "postbackUrl": "https://acme.com/webhooks/gravitypay",
    "payment": {
      "method": "pix",
      "buyer": {
        "name": "Maria da Silva",
        "email": "maria@exemplo.com",
        "document": "529.982.247-25",
        "phone": "(11) 99999-9999"
      },
      "metadata": { "pedido": "1234" }
    }
  }'

A resposta é a cobrança de sempre (com o postbackSecret) e o pagamento:

{
  "id": "chg_c7fb440eb3112525e35718d4488d66c8",
  "object": "charge",
  "status": "pending",
  "amountInCents": 15900,
  "checkoutUrl": "https://gravitypay.app/c/chg_c7fb440eb3112525e35718d4488d66c8",
  "postbackSecret": "whsec_6dec1cf6...",
  "payment": {
    "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": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAACA...",
      "qrCodeUrl": null,
      "expiresAt": "2026-10-05T02:59:59.000Z"
    },
    "boleto": null,
    "createdAt": "2026-10-03T13:47:55.064Z"
  }
}

pix.qrCodeBase64 é um PNG em base64 (sem o prefixo data:), gerado a partir do copia-e-cola: renderize com <img src="data:image/png;base64,...">. Ele sai igual em qualquer gateway.
payment.id é o mesmo data.id dos webhooks payment.*.
totalInCents inclui o juro do parcelamento quando o comprador paga.
status do pagamento: pending, paid ou failed.

O corpo inteiro é validado antes de criar qualquer coisa. Se faltar um dado, inclusive um que só o gateway da loja exige, a resposta é 400 com o param e nenhuma cobrança nasce. Criada a cobrança, a resposta é sempre 201: se o pagamento falhar (cartão recusado, método indisponível, gateway fora), ela vem com paymentError no lugar de payment, e a cobrança segue pending para uma nova tentativa.

{
  "id": "chg_...",
  "status": "pending",
  "postbackSecret": "whsec_...",
  "paymentError": {
    "type": "payment_declined",
    "code": "payment_declined",
    "message": "Não foi possível processar o pagamento. Confira os dados e tente novamente."
  }
}

Repetir a chamada com o mesmo Idempotency-Key devolve a cobrança e o último pagamento dela, sem postbackSecret e sem criar outro pagamento.

3. Nova tentativa numa cobrança que já existe

curl https://api.gravitypay.app/v1/charges/chg_c7fb.../payments \
  -H "Authorization: Bearer gp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "method": "boleto", "buyer": { ... }, "boletoDueInDays": 3 }'

O corpo é o mesmo do campo payment. A resposta é 201 com o pagamento novo, ou 200 quando já existe um PIX (com mais de 5 minutos de validade) ou um boleto (dentro do vencimento) pendente do mesmo método nesta cobrança: ele é devolvido de novo, e a cobrança nunca fica com dois PIX ou dois boletos pendentes. Outro método cria um pagamento novo.

Cartão

Na loja com cartão Asaas (card.input = raw), mande o cartão aberto, o IP do comprador e o CEP e número do endereço:

{
  "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"
  }
}

Aprovado na hora, o pagamento volta paid, a cobrança vira paid e o postbackUrl recebe payment.paid. Na loja Pagar.me ou Efí, gere o token no navegador e mande card.token (no Pagar.me, threedsTransactionId opcional para o 3DS). Mandar o formato errado para o gateway (cartão aberto no Pagar.me ou na Efí, token no Asaas, qualquer cartão no Stripe) dá 422 card_input_not_supported.

buyer.ip é o IP do comprador, que o seu site recebe. Nunca mande o IP do seu servidor: o gateway usa esse dado no antifraude. Dados de cartão nunca são gravados nem aparecem em log, banco ou mensagem de erro na Gravity Play, e o seu sistema também não deve guardá-los.

O que cada gateway exige

Método	Asaas	Pagar.me	Efí
`pix`	nome, e-mail, documento, telefone	idem	não tem
`boleto`	idem	idem + endereço completo (CEP, rua, número, cidade, UF)	não tem
`credit_card`	idem + `buyer.ip` + CEP e número + cartão aberto	idem + endereço completo + `card.token`	idem + `card.token`

O documento é CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem máscara, e precisa ter o dígito verificador certo. O telefone precisa do DDD. O nome vai ao gateway com até 64 caracteres.

Erros

Situação	HTTP	`type` / `code`
Corpo inválido ou dado obrigatório do gateway faltando	400	`invalid_request`, com `param`
Cobrança de outra loja, inexistente ou de link de pagamento	404	`not_found`
Cobrança não está `pending`	409	`conflict` / `charge_not_pending`
Outro pagamento desta cobrança em andamento	409	`conflict` / `payment_in_progress`
Loja sem gateway para o método	422	`unprocessable` / `method_unavailable`
Formato de cartão errado para o gateway	422	`unprocessable` / `card_input_not_supported`
Cartão recusado	402	`payment_declined`
Gateway fora ou erro não mapeado	502	`gateway_error`

A mensagem de recusa do gateway só chega quando ele a marca como segura para o comprador; nos outros casos, a mensagem é genérica.

Consultando uma cobrança

curl https://api.gravitypay.app/v1/charges/chg_2e59538f... \
  -H "Authorization: Bearer gp_live_..."

O campo status evolui assim:

status	significado
`pending`	aguardando pagamento
`paid`	pago
`failed`	pagamento recusado
`refunded`	reembolsado
`canceled`	cancelado

Você não precisa ficar consultando: assim que o pagamento confirma, enviamos um webhook. Para listar todas as vendas, use GET /v1/payments — veja a aba Referência da API.

Introdução

Guias

Criando uma cobrança

Resposta

Os itens

Campos da requisição

Vencimento do boleto

Pagamento transparente

1. Consulte o que a loja aceita

2. Crie a cobrança e o pagamento numa chamada

3. Nova tentativa numa cobrança que já existe

Cartão

O que cada gateway exige

Erros

Consultando uma cobrança

​Criando uma cobrança

​Resposta

​Os itens

​Campos da requisição

​Vencimento do boleto

​Pagamento transparente

​1. Consulte o que a loja aceita

​2. Crie a cobrança e o pagamento numa chamada

​3. Nova tentativa numa cobrança que já existe

​Cartão

​O que cada gateway exige

​Erros

​Consultando uma cobrança

Criando uma cobrança

Resposta

Os itens

Campos da requisição

Vencimento do boleto

Pagamento transparente

1. Consulte o que a loja aceita

2. Crie a cobrança e o pagamento numa chamada

3. Nova tentativa numa cobrança que já existe

Cartão

O que cada gateway exige

Erros

Consultando uma cobrança