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:Boleto
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
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 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 umX-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 levarmetadata, 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.
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.