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

# Cobranças

> Crie uma cobrança avulsa com itens e receba uma URL de checkout.

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```js Node.js theme={null}
  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
  ```
</CodeGroup>

### Resposta

```json theme={null}
{
  "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" }
}
```

<Note>
  **Guarde o `postbackSecret`.** Ele é retornado **apenas na criação** e serve
  para validar a assinatura dos webhooks (`postbackUrl`) **desta** cobrança.
  Veja [Webhooks](/webhooks#postbackurl).
</Note>

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

```bash theme={null}
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](/webhooks). Para listar todas as vendas, use `GET /v1/payments` — veja a aba
**Referência da API**.