Cobranças

Crie, consulte, liste e estorne cobranças por Pix e cartão de crédito.

Pix

POST /v1/cobrancas

{
  "metodo": "pix",
  "valorCentavos": 4990,
  "descricao": "Assinatura mensal",
  "expiraEmSegundos": 3600,
  "cliente": { "nome": "Maria", "documento": "12345678909", "email": "maria@exemplo.com" }
}

A resposta traz pix.copiaECola e pix.expiraEm. A cobrança nasce pendente e muda para paga quando o pagamento é confirmado. A expiração padrão é de 1 hora e pode ir de 60 segundos a 7 dias.

Cartão de crédito

POST /v1/cobrancas

{
  "metodo": "cartao",
  "valorCentavos": 12000,
  "descricao": "Curso completo",
  "cartaoToken": "tok_...",
  "parcelas": 3
}

Nunca envie o número do cartão. A API recebe só o cartaoToken, gerado no navegador do comprador pelo SDK de cartão (ou, mais simples, pelo checkout hospedado). Campos desconhecidos são descartados.

O cartão é processado na hora: a resposta já vem paga ou recusada (com motivoRecusa). Aceitamos de 1 a 12 parcelas.

Idempotência

O header Idempotency-Key é obrigatório. Repetir a mesma chave com o mesmo corpo devolve a cobrança já criada (status 200 em vez de 201). A mesma chave com corpo diferente retorna 422 com o código idempotencia_conflito. Use um identificador do seu pedido.

Ciclo de vida

Status	Significado
`pendente`	Aguardando pagamento (Pix).
`autorizada`	Aprovada pelo emissor, ainda não capturada.
`paga`	Confirmada. As partes do split entram no ledger.
`recusada`	Cartão negado. Estado final.
`expirada`	Pix venceu sem pagamento. Estado final.
`estornada`	Devolvida. As partes do split são revertidas.
`contestada`	Em disputa (chargeback).

Estorno

POST /v1/cobrancas/{id}/estornos

curl -X POST https://api.pay.qorvie.com/v1/cobrancas/ch_.../estornos \
  -H "Authorization: Bearer $CHAVE"

Só cobranças paga (ou autorizada) podem ser estornadas, e o estorno é sempre total por enquanto. Estorno parcial está nos planos.

Listar e consultar

GET /v1/cobrancas?limite=50: mais recentes primeiro, de 1 a 200 itens.
GET /v1/cobrancas/{id}: uma cobrança. Outra conta devolve 404.