Skip to main content

Visão Geral

No checkout transparente o cliente paga sem sair da sua tela. Você chama a API, recebe o código PIX (ou a linha do boleto, ou o resultado da autorização do cartão) e exibe tudo com a sua marca, no seu layout. É o caminho para quem constrói produto whitelabel, marketplace, ou simplesmente não quer que o cliente veja uma página de terceiro no meio da compra.

Qual caminho usar?

As três opções coexistem. Nada do que você já integrou deixa de funcionar.

Como funciona

1

Crie o produto uma vez

A cobrança sempre aponta para um produto — é dele que saem preço, métodos aceitos e parcelamento. Crie com POST /api/v1/products e guarde o uuid.
2

Colete os dados do cliente na sua interface

Nome, e-mail, CPF/CNPJ e telefone são obrigatórios. Endereço é opcional.
3

Crie a cobrança

POST /api/v1/charges com o productId, o paymentMethod e o customer. A resposta traz os dados de pagamento.
4

Exiba o pagamento

Renderize o QR Code a partir do pix.code, ou mostre a linha digitável e o link do PDF do boleto.
5

Confirme o pagamento

Receba o webhook de pagamento confirmado, ou consulte GET /api/v1/charges/{uuid}.

PIX na prática

Renderizando o QR Code

A Garu devolve o código EMV (copia-e-cola), não uma imagem. Isso é de propósito: uma imagem viria hospedada num domínio de terceiro, e num checkout whitelabel isso apareceria para o seu cliente. Gere o QR no seu próprio front, com a biblioteca que já usa:
Ofereça também o botão de copiar código — boa parte das pessoas paga colando no app do banco, sem escanear nada.

Boleto

O pdfUrl é uma URL pública, que não exige chave de API — pode ser entregue direto ao seu cliente, por e-mail ou como botão de download. Ela aponta para garu.com.br, nunca para o domínio do adquirente.

Cartão de crédito

Servidor-para-servidor, sempre. Este endpoint recebe o número do cartão e o CVV em texto claro. Chame-o exclusivamente do seu backend — nunca do navegador nem de um app, onde a sua chave de API e os dados do cartão ficariam expostos.Processar dados de cartão no seu servidor coloca a sua operação no escopo do PCI DSS (provavelmente SAQ D). Isso é uma decisão de negócio, não um detalhe técnico. Se você prefere não assumir esse escopo, use PIX e boleto no checkout transparente e mande o cartão para a página hospedada da Garu, que já é PCI-compliant.
A Garu nunca armazena o número do cartão nem o CVV. A resposta devolve só bandeira, últimos 4 dígitos e código de autorização.

Parcelamento: amount não é chargedTotal

Em venda parcelada os dois valores divergem, e isso é esperado: amount é o preço do produto, chargedTotal é o que foi efetivamente cobrado, já com o acréscimo.Um produto de R349,00vendidoem2×temchargedTotal:358.52cercadeR 349,00 vendido em 2× tem `chargedTotal: 358.52` — cerca de R 179,26 por parcela. Se você exibir R$ 179,26 como o total da compra, vai mostrar um número errado ao seu cliente e não vai conseguir reconciliar o recebimento depois.

Idempotência

Mande sempre um X-Idempotency-Key único por cobrança. Se a requisição sofrer timeout e você reenviar, a chave garante que volta a mesma cobrança em vez de nascer uma segunda. Vale por 24 horas.

Juntando com Checkout Sessions

Dá para combinar os dois: crie a Checkout Session para levar metadata, client_reference_id e atribuição de afiliado, e depois passe o token dela na criação da cobrança. O cliente nunca sai da sua interface e você mantém o rastreamento.
A session é marcada como concluída e fica amarrada à cobrança.

Confirmando o pagamento

PIX e boleto são assíncronos: a cobrança nasce pendente e só depois vira paga. Duas formas de saber:

Webhooks (recomendado)

A Garu chama o seu endpoint no instante em que o pagamento é confirmado. É a opção mais rápida e a que menos consome recurso dos dois lados.

Consulta pontual

GET /api/v1/charges/{uuid} devolve o status atual. Útil para reconciliação, ou para atualizar a tela enquanto o cliente ainda está nela.

Referência completa

Criar cobrança

Consultar cobrança

Listar cobranças

Estornar cobrança