Conectando a Iugu

A IuzyPay orquestra o checkout, mas os pagamentos passam pelo seu gateway. Se a sua conta é na Iugu, conecte-a para cobrar por lá — inclusive junto com a Pagar.me e a Stripe, com a ordem de cobrança definida em Configurações → Gateways.

O que você vai precisar

No painel da Iugu, em Configurações → API, copie:

• O token de API — usado para criar as cobranças.
• O ID da conta (account_id) — obrigatório para tokenizar cartões com segurança no navegador.

A Iugu tem um token para produção e outro para teste, e os dois têm a mesma cara. Confira qual você copiou antes de colar.

Conectando

1. No painel, vá em Configurações → Gateways.
2. Clique em Conectar e escolha a Iugu.
3. Escolha o ambiente: produção ou teste. Diferente da Pagar.me e da Stripe, aqui o ambiente não é detectado — o token da Iugu não diz a qual ambiente pertence, então quem informa é você. Um token de produção conectado como “teste” faria vendas reais entrarem como vendas de teste (fora do faturamento, das métricas e dos avisos).
4. Cole o token de API e o ID da conta.
5. Cadastre os gatilhos (abaixo) e salve — a IuzyPay valida as credenciais na hora.

O ambiente fica preso à conexão: para trocar, desconecte e conecte de novo. Trocar o ambiente de uma conexão em uso re-etiquetaria todas as vendas já feitas por ela.

Configurando os gatilhos (webhook)

O gatilho avisa a IuzyPay assim que um Pix é pago ou um cartão é aprovado, atualizando o pedido automaticamente. Na Iugu, cada evento é um gatilho separado, todos apontando para a mesma URL:

1. No painel da Iugu, vá em Configurações → Gatilhos e adicione um gatilho para cada evento abaixo, com a URL:

   https://api.iuzypay.com/v1/webhooks/iugu

2. Os eventos:

   • invoice.status_changed
   • invoice.payment_failed
   • invoice.refund
   • invoice.released

3. Salve.

Sem os gatilhos nada se perde — a IuzyPay reconsulta o gateway periodicamente e no botão Verificar do pedido —, mas a confirmação deixa de ser imediata.

Como funciona o Pix por aqui

O QR do Pix da Iugu vale até o fim do dia do vencimento, enquanto o checkout mostra a janela de 1 hora da IuzyPay. Se o comprador pagar depois de o pedido expirar na sua tela, o pagamento não se perde: na próxima conferência a venda é reconhecida e o pedido volta a pago, com a entrega liberada normalmente.

Limites da Iugu hoje

• Sem split de comissão. Comissões de afiliados e co-produtores em vendas processadas pela Iugu liquidam sempre como “A pagar” — você repassa por fora e registra a baixa.
• Chargebacks não sincronizam. A Iugu não publica uma API de disputas: o pedido é marcado como chargeback quando a cobrança vira chargeback lá, mas a defesa é enviada no painel da Iugu, não pela Central de disputas da IuzyPay.
• Reembolso parcial só no cartão. No Pix, a Iugu devolve apenas o valor integral — o dashboard recusa o parcial nessas vendas em vez de tentar e falhar. Veja reembolsar uma venda.
• Cada item da cobrança precisa somar pelo menos R$ 1,00. É regra da Iugu: um order bump de centavos é recusado por lá (a cobrança cai no próximo gateway da sua conta, se houver).
• Parcelamento até 12x, com no mínimo R$ 5,00 por parcela. Também é regra da Iugu: uma venda de R$ 40 não fecha em 12x (daria R$ 3,33 a parcela). Você não precisa fazer conta: o checkout oferece só as parcelas que a Iugu aceita para aquele valor — na venda de R$ 40, até 8x. Veja parcelamento no cartão.

Segurança

Seu token é criptografado antes de ser salvo e nunca aparece novamente em texto. O número do cartão do comprador é enviado direto para a Iugu pelo navegador (padrão PCI SAQ-A) — dados sensíveis de cartão nunca passam pelos servidores da IuzyPay.