Cobranças

Cobrança com cliente, vencimento, itens, avisos e página de pagamento, para o cliente escolher como pagar.

A cobrança é o jeito de mandar o cliente pagar: você cria, a Confido avisa o cliente (e-mail, SMS, WhatsApp) com o link, e ele escolhe Pix, boleto ou cartão numa página da Confido. É a mesma "Nova cobrança" do painel.

Use a cobrança quando você não quer escolher o meio pelo cliente nem tocar em dados de cartão. Quando você já sabe o meio e quer o QR ou o boleto na hora, use a venda direta (que também vira cobrança).

Criar

curl -X POST https://api.confidoscm.com/api/v1/charges \
  -H "X-API-Key: $CONFIDO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-43" \
  -d '{
    "customer": { "name": "Joana Souza", "email": "joana@exemplo.com", "phone": "+5511987650002" },
    "amountCents": 25000,
    "method": "undefined",
    "allowedMethods": ["pix", "boleto", "credit_card"],
    "dueDate": "2026-12-01",
    "description": "Pedido 43",
    "items": [
      { "name": "Camiseta", "quantity": 2, "unitPriceCents": 10000 },
      { "name": "Frete", "unitPriceCents": 5000 }
    ],
    "channels": ["email", "whatsapp"],
    "externalReference": "pedido-43"
  }'

Campo	O que é
`amountCents`, `dueDate`	Valor total em centavos e vencimento (AAAA-MM-DD). Obrigatórios.
`method`	`pix`, `boleto`, `credit_card` ou `undefined` (o cliente escolhe na página). Obrigatório.
`allowedMethods`	Com `undefined`, os meios que a página oferece.
`customerId` ou `customer`	Um cliente já cadastrado, ou os dados dele (`name` obrigatório; `email`, `document`, `phone`). O cliente é achado pelo documento ou e-mail, ou criado.
`items`	O que está sendo cobrado: aparece na página, no e-mail e no painel.
`installmentCount`	Acima de 1 cria o carnê (cartão até 12): a resposta é a 1ª parcela, com todas em `installments`.
`interestPct`, `finePct`, `discountPct` (ou os valores em centavos)	Juros ao mês, multa e desconto até a data.
`channels`, `notify`	Por onde o cliente é avisado; `notify: false` desliga os avisos (você manda o link).
`externalReference`	Seu identificador, para filtrar depois.

A resposta é a cobrança, com object: "charge", o id (e o chr_…), o status e o checkoutUrl: a página onde o cliente paga e, depois, vê o comprovante.

Consultar e listar

curl https://api.confidoscm.com/api/v1/charges/chr_8YtR2kLm0pQs4vWx6zAb -H "X-API-Key: $CONFIDO_API_KEY"
curl "https://api.confidoscm.com/api/v1/charges?externalReference=pedido-43" -H "X-API-Key: $CONFIDO_API_KEY"
curl "https://api.confidoscm.com/api/v1/charges?paymentId=pay_9f2c4e1a7b3d" -H "X-API-Key: $CONFIDO_API_KEY"

GET /api/v1/charges/{id} aceita o uuid ou o chr_….
GET /api/v1/charges filtra por status, customerId, externalReference e paymentId (a cobrança de uma venda feita pela API). A lista é paginada: veja Paginação.

Status da cobrança	Quer dizer
`pending`	Em aberto, dentro do vencimento
`overdue`	Vencida, ainda em aberto
`confirmed`, `received`	Paga (cartão confirmado ou valor recebido)
`received_in_cash`	Marcada como recebida fora da Confido
`canceled`, `refunded`	Cancelada ou estornada

Escopos e regras

Escopos payments:create (criar) e payments:read (consultar e listar), os mesmos da venda.
As regras são as do painel: valor que cubra as taxas, conta que pode vender, moeda liberada.
A chave de teste cria cobranças só na sandbox dela, e a de produção só fora dela.
Os eventos chegam como payment.* nos webhooks, quando a cobrança é paga.