O que mudou

Agora dá para montar um checkout transparente — o cliente paga sem sair da sua tela, com a sua marca do começo ao fim.

O novo POST /api/v1/charges cria a cobrança e devolve o que você precisa para exibir o pagamento você mesmo:

• PIX → o código copia-e-cola (EMV) em pix.code. Você renderiza o QR Code como quiser.
• Boleto → a linha digitável em boleto.barcodeLine e o PDF em boleto.pdfUrl, servido pelo domínio da Garu.
• Cartão de crédito → o resultado da autorização, com bandeira, últimos 4 dígitos e código de autorização.

Antes disso, a única forma documentada de receber era mandar o cliente para uma página hospedada pela Garu (link de pagamento ou Checkout Session). Essas continuam funcionando exatamente como antes e seguem sendo a opção mais simples — o checkout transparente é para quem precisa de controle total da experiência.

O recurso vem completo: GET /api/v1/charges/{uuid} para consultar, GET /api/v1/charges para listar com filtros (status, método, produto, período e busca por cliente), POST /api/v1/charges/{uuid}/refund para estornar e DELETE /api/v1/charges/{uuid} para cancelar uma cobrança ainda não paga.

Toda cobrança agora tem um uuid próprio, que é como você a identifica na API. E o POST aceita X-Idempotency-Key, então um retry não vira cobrança duplicada.

Valores: amount e chargedTotal

A resposta separa dois números de propósito:

• amount — o preço base do produto.
• chargedTotal — o que o cliente foi efetivamente cobrado.

Nas vendas parceladas no cartão os dois são diferentes: um produto de R$ 349 em 2× tem amount: 349.00 e chargedTotal: 358.52, porque o parcelamento tem acréscimo. Guardar os dois separados é o que permite reconciliar o que você vendeu com o que foi cobrado.

Cartão exige atenção

O endpoint aceita o número do cartão e o CVV em texto claro, então ele é exclusivamente servidor-para-servidor. Nunca chame /api/v1/charges a partir do navegador ou de um app: sua chave de API ficaria exposta, e os dados do cartão também.

Processar dados de cartão no seu servidor coloca a sua operação no escopo do PCI DSS. Se você não quer lidar com isso, use PIX e boleto no checkout transparente e deixe o cartão para a página hospedada da Garu — ela já é PCI-compliant.

Precisa fazer algo?

Nada. Nenhuma integração existente muda: links de pagamento, Checkout Sessions e webhooks continuam idênticos. O /api/v1/charges é adição pura, para quem quiser.