Skip to main content
POST
Criar Cobrança

Visão Geral

Cria uma cobrança e devolve tudo que você precisa para exibir o pagamento dentro da sua própria interface — sem redirecionar o cliente. É a base do checkout transparente. Se você não precisa desse controle, o caminho mais simples continua sendo o link de pagamento ou a Checkout Session, onde a Garu hospeda a página de pagamento.
A cobrança é sempre feita em cima de um produto. Crie o produto uma vez com POST /api/v1/products e use o uuid dele aqui.

Headers

string
required
Sua chave de API (Bearer sk_live_...)
string
required
application/json
string
Chave única por cobrança. Reenviar a mesma requisição com a mesma chave devolve a cobrança já criada em vez de duplicar. Válida por 24h.

Request Body

string
required
UUID do produto a ser cobrado
string
required
Método de pagamento: pix, boleto ou creditCard
object
required
Dados de quem está pagando
object
Dados do cartão. Obrigatório apenas quando paymentMethod = creditCard.
string
Token de uma Checkout Session criada previamente. Use quando quiser aproveitar metadata e client_reference_id da session mantendo o checkout na sua interface.
string
Texto livre anexado à cobrança
Cartão: servidor-para-servidor apenas. 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 aplicativo, 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. Se você prefere não assumir isso, use pix e boleto aqui e deixe o cartão para a página hospedada da Garu.

Exemplo de Requisição

Resposta de Sucesso (201 Created)

Blocos por método de pagamento

Exatamente um dos três vem preenchido, conforme o paymentMethod:
O pix.code é o copia-e-cola (padrão EMV). Renderize-o como QR Code com qualquer biblioteca do seu stack — não devolvemos imagem justamente para que nada no seu checkout venha de um domínio de terceiros. O boleto.pdfUrl aponta para o domínio da Garu e pode ser entregue direto ao seu cliente: é uma URL pública, que não exige chave de API.

Sobre o expiresAt

O expiresAt só vem preenchido para boleto, com o vencimento (8 dias após a criação). Para PIX e cartão ele vem null.Motivo: hoje a Garu não define uma janela de expiração própria para o código PIX. Em vez de devolver um valor que não corresponde a nada, devolvemos null. Se o seu fluxo precisa de um prazo para o PIX, controle-o do seu lado.

Valores: amount e chargedTotal

amount é o preço base do produto. chargedTotal é o que o cliente foi efetivamente cobrado.Eles são iguais em PIX, boleto e cartão em 1×. Em parcelamento no cartão o chargedTotal é maior, porque inclui o acréscimo do parcelamento: um produto de R$ 349,00 em 2× resulta em amount: 349.00 e chargedTotal: 358.52.Use chargedTotal para reconciliar o que foi cobrado e amount para casar com o seu catálogo.

Erros

Próximos passos

Depois de criar a cobrança, acompanhe o pagamento por webhook ou consultando GET /api/v1/charges/{uuid}.