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. 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 -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"
    }
  }'

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