# Cobranças

Uma cobrança é uma entrada de dinheiro: Pix, boleto ou cartão. É o mesmo objeto que o painel usa para "Nova cobrança".

## Criar

`POST /charges`

> ✅ Use um `Idempotency-Key` veja [Idempotência](https://stacepay.com.br/docs/idempotencia). KYC aprovado é obrigatório.

| Campo | Tipo |  | Descrição |
| --- | --- | --- | --- |
| `method` | string | obrigatório | "pix", "boleto" ou "credit_card". |
| `amount` | integer | obrigatório | Valor em centavos. Mínimo 100 (R$ 1,00). |
| `installments` | integer | opcional | Parcelas (só cartão). Padrão 1, máximo 12. |
| `description` | string | opcional | Aparece para o pagador. |
| `reference` | string | opcional | Seu identificador interno devolvido em "reference". |
| `metadata` | object | opcional | Pares chave/valor livres, até 30 chaves. |
| `customer.name` | string | obrigatório | Nome completo do pagador. |
| `customer.email` | string | obrigatório | E-mail do pagador. |
| `customer.document` | string | obrigatório | CPF ou CNPJ, só dígitos. |
| `customer.phone` | string | opcional | DDD + número, só dígitos. |

_curl_

```bash
curl -X POST https://stacepay.com.br/api/v1/charges \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Idempotency-Key: pedido-8231" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 5000,
    "description": "Pedido 8231",
    "reference": "pedido-8231",
    "customer": {
      "name": "Ana Lima",
      "email": "ana@exemplo.com",
      "document": "39053344705"
    }
  }'
```

_json_

```json
{
  "object": "charge",
  "id": "sp1_d9c51fe9",
  "status": "pending",
  "amount": 5000,
  "currency": "BRL",
  "payment_method": "pix",
  "description": "Pedido 8231",
  "reference": "pedido-8231",
  "customer": { "name": "Ana Lima", "email": "ana@exemplo.com", "phone": null, "document": "39053344705", "document_type": "cpf" },
  "fee_amount": null,
  "net_amount": null,
  "available_at": null,
  "paid_at": null,
  "created_at": "2026-08-11T21:09:26-03:00",
  "metadata": {},
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "expires_at": "2026-08-11T21:39:26-03:00"
  }
}
```

O campo específico do método `pix`, `boleto` ou `card` só aparece quando é esse o método da cobrança.

## Listar

`GET /charges?status=paid&limit=20&offset=0`

Filtra por `status` (mesmos valores do objeto). Sem filtro, devolve todas.

## Buscar uma

`GET /charges/{id}`

`{id}` é o valor do campo `id` devolvido na criação (ex.: `sp1_d9c51fe9`) não o id interno numérico.

## Estornar

`POST /charges/{id}/refund`

Só funciona em cobrança com status `paid`. Corpo opcional `{"amount": 2000}` para estorno parcial; sem `amount`, estorna o valor total.

## Status possíveis

| Status | Significado |
| --- | --- |
| `pending` | Aguardando o pagador. |
| `processing` | Em confirmação com o parceiro. |
| `authorized` | Cartão autorizado, captura em andamento. |
| `paid` | Confirmado o dinheiro entrou no seu saldo. |
| `refused` | Recusado pelo parceiro ou emissor. |
| `failed` | Falhou antes de chegar ao parceiro. |
| `refunded` | Estornado. |
| `chargeback` | Contestado pelo pagador junto ao emissor. |
| `disputed` | Em disputa. |