Como gerar link de pagamento na iugu pela API
Para gerar um link de pagamento na iugu pela API, crie uma fatura com POST https://api.iugu.com/v1/invoices, autenticando com o seu API token, e envie pelo menos email, due_date e items. A resposta traz o secure_url, o endereço da página em que o cliente paga por Pix, boleto ou cartão, conforme o campo payable_with.
Atualizado em · Por Luis Henrique Cuba
Antes de começar
- Um API token, criado no painel em Configurações > Integração via API > Novo. Ele precisa da aprovação dos administradores da conta: sem isso, a API responde 401
- Guarde o token assim que ele aparecer: a iugu mostra o valor por apenas 1 hora, depois ele fica mascarado
- Use o test_token para testar e o live_token em produção. A URL da API é a mesma; o ambiente é definido pelo token
- Para cobrar por Pix, ative o Pix na conta (Configurações > Pix ou pela API). A conta precisa estar verificada
- Para boleto e Pix, tenha os dados do pagador: CPF ou CNPJ, nome e endereço
Autenticação
A forma recomendada pela iugu é HTTP Basic: o token seguido de dois-pontos, codificado em Base64, no cabeçalho Authorization. A documentação também aceita Bearer e o token no parâmetro api_token. No curl, a opção -u "TOKEN:" monta o Basic sozinha.
Exemplo: criar a fatura e receber o link
curl --request POST https://api.iugu.com/v1/invoices \
-u "$IUGU_API_TOKEN:" \
--header 'content-type: application/json' \
--data '{
"email": "cliente@exemplo.com.br",
"due_date": "2026-10-25",
"order_id": "PED-1042",
"payable_with": ["pix", "bank_slip", "credit_card"],
"items": [
{ "description": "Pedido 1042", "quantity": 1, "price_cents": 15990 }
],
"payer": {
"cpf_cnpj": "00000000000",
"name": "Nome do Cliente",
"address": {
"zip_code": "01310100", "street": "Rua Exemplo", "number": "100",
"district": "Bairro", "city": "São Paulo", "state": "SP", "country": "Brasil"
}
},
"notification_url": "https://sua-loja.com.br/webhooks/iugu",
"return_url": "https://sua-loja.com.br/pedido/1042/obrigado",
"expired_url": "https://sua-loja.com.br/pedido/1042/nova-cobranca"
}'Os campos que importam
email, due_date e items
Obrigatórios. Cada item tem description, quantity e price_cents.
payable_with
Meios aceitos na página de pagamento: pix, bank_slip, credit_card ou all.
payer
Dados do pagador (cpf_cnpj, name, email, telefone e address). Obrigatórios para emitir boleto e Pix.
order_id
Número único do pedido no seu sistema. Segundo a iugu, ajuda a evitar o pagamento da mesma fatura, e permite achar a fatura depois em GET /v1/resource_search.
notification_url, return_url e expired_url
A primeira recebe as notificações daquela fatura, como os gatilhos. As outras duas são para onde o cliente vai depois de pagar ou se a fatura tiver expirado.
Multa, juros e desconto
fines, late_payment_fine e per_day_interest para atraso; discount_cents e early_payment_discounts para desconto. A iugu também tem ensure_workday_due_date, que evita vencimento em sábado ou domingo.
O que volta na resposta
id e status
O id da fatura (guarde junto do pedido) e o status, que começa como pending.
secure_url
O link da página de pagamento. É ele que vai para o cliente por e-mail, WhatsApp ou no fim do checkout.
pix
pix.qrcode é a URL da imagem do QR code e pix.qrcode_text é o copia e cola.
bank_slip
bank_slip.digitable_line é a linha digitável, bank_slip.barcode_data é o número do código de barras e bank_slip.bank_slip_pdf_url é o PDF do boleto.
E o Link de Pagamento do painel?
É outro produto. Segundo a central de ajuda da iugu, o Link de Pagamento é configurado no Painel de Personalização, faz parte do Checkout Personalizável e gera uma URL com produto e valor pré-definidos, que vale para muitos compradores. Na documentação para desenvolvedores, não encontramos API para criá-lo.
Se cada cliente precisa de um link com o próprio valor e pedido, use a fatura pela API, como neste guia.
Depois de gerar o link
- 01
Guarde a ligação
Salve o id da fatura e o secure_url no pedido. É por esse id que os avisos da iugu vão chegar.
- 02
Receba o status pelos gatilhos
Cadastre o gatilho invoice.status_changed para saber quando a fatura foi paga, cancelada ou expirou. O passo a passo está no guia sobre o webhook da iugu.
- 03
Trate a segunda via
Fatura pendente com vencimento novo: POST /v1/invoices/{id}/duplicate cancela a atual e cria outra, com novo link.
Como gerar link de pagamento na iugu pela API: dúvidas comuns
O link de pagamento da fatura expira?
A fatura tem vencimento (due_date) e pode ter prazo de expiração depois dele (expires_in, de 0 a 120 dias). Quando expira, o status passa a expired, e o expired_url define para onde o cliente vai se abrir o link.
Dá para criar a fatura sem os dados do pagador?
Para cartão, os campos obrigatórios são email, due_date e items. Para boleto e Pix, a iugu exige os dados do pagador no objeto payer.
Qual a diferença entre test_token e live_token?
O test_token cria cobranças no ambiente de teste, sem dinheiro de verdade; o live_token cria cobranças reais. A URL da API é a mesma, e os gatilhos de cada ambiente são separados.
Posso chamar a API da iugu direto do navegador?
Não com o API token: ele dá acesso à conta. A fatura deve ser criada no servidor. No navegador, a iugu oferece o iugu.js para tokenizar dados de cartão.
Dá para fazer isso no n8n?
Dá. Um nó HTTP Request com autenticação Basic (o token como usuário e a senha em branco) faz o mesmo POST deste guia.
Perguntas parecidas
Precisa de ajuda para resolver isso na sua empresa?
Respondemos em até 24 horas com as próximas perguntas e uma proposta objetiva.