Integração com a iugu
A integração com a iugu conecta o seu sistema ou a sua loja online à API e aos gatilhos (webhooks) da iugu: o sistema cria a fatura, envia o link de pagamento ao cliente e recebe o aviso de cada mudança de status, como pago, cancelado ou expirado. A LHCX monta esse fluxo com conferência do status, logs e reprocessamento.
![Seção Mudança de Status da Fatura da documentação de gatilhos da iugu: tabela com os parâmetros event (invoice.status_changed), data[id], data[status], data[payment_method], data[paid_at], data[paid_cents], data[order_id] e outros, com exemplos.](https://midia.lhcx.tech/site/consultoria/iugu-gatilho-status-changed.webp)
O que dá para integrar com a iugu
A iugu publica uma API REST em https://api.iugu.com/v1 e avisa outros sistemas por gatilhos, os webhooks dela. Com os dois, a cobrança nasce no seu sistema e o status volta para ele sozinho.
Cobrança gerada pelo seu sistema
A fatura é criada com POST /v1/invoices e a resposta traz o secure_url, o endereço da página em que o cliente paga. O link pode ir por e-mail, WhatsApp ou aparecer no fim do checkout. A mesma resposta traz o Pix copia e cola (pix.qrcode_text) e a linha digitável do boleto (bank_slip.digitable_line).
Status acompanhado sem conferência manual
Os gatilhos avisam quando a fatura é criada, muda de status, falha no pagamento ou é reembolsada. O sistema recebe o aviso e atualiza o pedido, sem alguém abrir o painel para conferir.
Loja online com o pedido atualizado na hora
O campo order_id (ou o external_reference) liga a fatura ao pedido. Quando o gatilho invoice.status_changed chega com o status paid, o pedido avança para pago e a separação pode começar.
Segunda via, cancelamento e reembolso
A API gera segunda via de fatura pendente (POST /v1/invoices/{id}/duplicate, que cancela a atual e cria uma nova), cancela faturas pendentes, em análise ou expiradas (PUT /v1/invoices/{id}/cancel) e reembolsa (POST /v1/invoices/{id}/refund).
Assinaturas e split de pagamento
Assinaturas têm gatilhos próprios (subscription.created, subscription.renewed, subscription.suspended e outros). O split divide o valor de uma fatura entre subcontas pelo campo splits, para marketplaces e operações com parceiros.
Link de pagamento: fatura pela API ou Link de Pagamento do painel?
Na iugu, "link de pagamento" pode ser duas coisas. A primeira é a fatura criada pela API: cada fatura tem o seu secure_url, com valor, itens e vencimento definidos pelo seu sistema. É o caminho quando o link precisa nascer de um pedido, de um contrato ou de um atendimento.
A segunda é o produto Link de Pagamento, configurado no Painel de Personalização. Segundo a central de ajuda da iugu, ele faz parte do Checkout Personalizável (é preciso ter ou contratar esse checkout) e gera uma URL com produto e valor pré-definidos: o comprador preenche os dados e isso gera a fatura. Aceita cobrança avulsa ou assinatura, Pix, cartão e boleto, cupom e expiração por data ou por quantidade de vendas.
Gatilhos da iugu: como o status chega ao seu sistema
O gatilho é cadastrado por evento, no painel (Configurações > Integrações > Comunicação via Gatilho) ou pela API (POST /v1/web_hooks, com event, url e authorization). A documentação cita o limite de 20 gatilhos por conta. Teste e produção são ambientes isolados, cada um com as suas URLs.
- A iugu envia um POST com Content-Type application/x-www-form-urlencoded, com o campo event e os dados em data[...]: data[id], data[status], data[order_id], data[paid_at], data[payment_method], entre outros
- Eventos de fatura: invoice.created, invoice.status_changed, invoice.payment_failed, invoice.refund, invoice.due, invoice.dunning_action e invoice.bank_slip_status, além dos eventos de liberação e de split
- O campo authorization guarda uma chave para ser usada como Basic Authentication na validação do recebimento
- Sem resposta de sucesso ou com timeout, o aviso entra em retentativa: da 1ª à 5ª a cada 2 segundos, da 6ª à 25ª a cada 10 segundos e da 26ª à 40ª a cada 2 minutos
- O reenvio também pode ser manual, pelo painel (Configurações > Logs de gatilhos) ou pela API, inclusive por período
- A fatura ainda aceita uma notification_url própria, para mandar as notificações daquela fatura a um endereço diferente do gatilho da conta
Status da fatura na iugu e o status do pedido na loja
| Status na iugu | O que significa (documentação da iugu) | Sugestão da LHCX para o pedido |
|---|---|---|
| pending | Ainda não paga. | Aguardando pagamento |
| paid | Pix realizado, boleto compensado ou cartão capturado. | Pago: liberar separação ou acesso |
| in_analysis | Primeira etapa da cobrança em duas etapas. | Pagamento em análise |
| partially_paid | Só parte do valor do boleto foi paga. | Pendência financeira: tratar com o cliente |
| expired | Passou do limite após o vencimento. | Expirado: oferecer nova cobrança |
| canceled | Cancelada, não pode mais ser paga. | Cancelado |
| refunded | Reembolsada. | Reembolsado: devolver estoque, se for o caso |
| in_protest | Fatura de cartão paga com notificação de não reconhecimento da compra. | Em disputa: segurar o envio |
| chargeback | Contestação perdida, sem recurso. | Estornado |
| externally_paid | Paga fora da iugu. | Pago (conferir o comprovante) |
Plugin pronto ou integração sob medida?
A iugu indica como desenvolvidos e suportados por ela o conector VTEX e o plugin para WooCommerce, ambos com boleto, cartão, Pix, split e recorrência. O site da iugu também cita plug-ins para WordPress, Magento e PrestaShop e um conector Shopify. Se a loja roda numa dessas plataformas e o fluxo é o padrão, comece pelo conector.
A integração sob medida entra quando a cobrança não nasce num checkout pronto: loja ou sistema próprio, cobrança enviada pelo WhatsApp ou pelo comercial, regras de status diferentes do padrão ou necessidade de levar o pagamento para o ERP, como na integração da iugu com o Omie.
Como a LHCX faz a integração
- 01
Diagnóstico do fluxo de cobrança
Onde a cobrança nasce, quem envia o link, por quais meios o cliente paga e quem confere o pagamento hoje.
- 02
Desenho dos status e das regras
Mapeamento entre os status da iugu e os do pedido, com o que fazer em cada caso: pagamento parcial, expiração, reembolso e contestação.
- 03
Criação das cobranças pela API
Fatura com order_id, dados do pagador para boleto e Pix, URLs de retorno e o token guardado no servidor, nunca no navegador.
- 04
Endpoint dos gatilhos
Recebimento com conferência da chave, registro de cada aviso, resposta imediata e processamento em seguida, sem duplicar quando a iugu reenviar.
- 05
Testes no ambiente de teste e virada
Fluxo completo com o test_token e os gatilhos do ambiente de teste; depois, produção com acompanhamento dos primeiros pagamentos.
Páginas e leituras relacionadas
Integração da iugu com o Omie
Fatura da iugu vira conta a receber no Omie, e o pagamento dá baixa sozinho.
Ver a páginaComo gerar link de pagamento na iugu pela API
Passo a passo com autenticação, campos obrigatórios e exemplo em curl.
Ver a páginaWebhook da iugu: status do pedido em tempo real
Cadastro do gatilho, formato do aviso, retentativas e um endpoint mínimo.
Ver a páginaWebhooks avançados
Arquitetura orientada a eventos, filas e reprocessamento.
Ver a páginaAutomações da LHCX
Fluxos entre sistemas com validação, tratamento de exceções, logs e alertas.
Ver a páginaPedir orçamento de integração
Conte onde a cobrança nasce e onde o status precisa chegar. Respondemos em até 24 horas.
Ver a página
Fontes
As informações técnicas desta página vêm da documentação oficial da iugu, consultada em outubro de 2026. A LHCX é uma consultoria independente, sem vínculo de parceria com a iugu.
Integração com a iugu: dúvidas comuns
A iugu tem API para gerar link de pagamento?
Tem para faturas: POST /v1/invoices cria a cobrança e devolve o secure_url, o link da página de pagamento. O produto Link de Pagamento do painel, ligado ao Checkout Personalizável, não tem API de criação na documentação para desenvolvedores que consultamos.
Como saber quando a fatura foi paga?
Pelo gatilho invoice.status_changed, que a iugu envia por POST ao endereço cadastrado com o id e o novo status da fatura. Por segurança, a LHCX ainda consulta a fatura pela API antes de liberar o pedido.
O que acontece se o meu sistema estiver fora do ar quando o aviso chegar?
A iugu tenta de novo: até 40 vezes, em intervalos que vão de 2 segundos a 2 minutos. Depois disso, o aviso pode ser reenviado pelo painel ou pela API, inclusive por período.
Dá para usar Pix e boleto?
Dá. O campo payable_with aceita pix, bank_slip, credit_card ou all. Para boleto e Pix, a fatura precisa dos dados do pagador (payer), e o Pix precisa estar ativado na conta, que precisa estar verificada.
Minha loja é WooCommerce ou VTEX. Preciso de integração sob medida?
Talvez não. A iugu mantém o plugin para WooCommerce e o conector VTEX. A integração sob medida faz sentido quando há regras próprias de status, cobrança fora do checkout ou envio do pagamento para outro sistema, como o ERP.
A LHCX é parceira da iugu?
Não. A LHCX é uma consultoria independente de automação e dados. A integração usa a API pública documentada pela iugu, com o token e os gatilhos da conta da sua empresa.
Quanto custa e quanto tempo leva?
Depende de onde a cobrança nasce, de quantos status e exceções precisam de regra e de quais sistemas recebem o status. Depois do diagnóstico, a proposta traz escopo, etapas, prazo e investimento.
Quer gerar cobranças na iugu e acompanhar o status sem conferir à mão? Conte o seu fluxo.
Respondemos em até 24 horas com as próximas perguntas e uma proposta objetiva.