Cobranças

Uma cobrança (charge) é um pagamento avulso — não precisa estar ligado a um produto. Você envia os itens e a Gravity Pay 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

O postbackSecret é 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.

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.

Criando uma cobrança

Resposta

Os itens

Campos da requisição

Consultando uma cobrança

On this page