Hubpay
← Conectar PSPs

Conectar Iugu

⏱ Tempo estimado: 10 minutos

O Iugu (grupo Itaú) é forte em SaaS e cobranças recorrentes. A integração com o Hubpay usa apenas um API Token simples.

1

Criar conta no Iugu

  1. Acesse iugu.com
  2. Clique em "Crie sua conta" ou "Começar agora"
  3. Preencha seus dados (CPF/CNPJ)
  4. Complete a verificação de identidade
  5. Aguarde aprovação
2

Habilitar Pix

  1. No painel Iugu (alia.iugu.com), vá em Configurações
  2. Procure por Métodos de Pagamento ou Formas de Recebimento
  3. Ative o Pix
  4. Siga as instruções pra vincular uma chave Pix à conta
3

Obter API Token

  1. No painel, vá em Administração → Configuração de conta
  2. Ou em Configurações → Integrações via API
  3. Copie o API Token (de produção ou de conta de teste, conforme desejado)
⚠️O Iugu usa a mesma URL de API pra teste e produção. O que diferencia é o tipo de conta (conta de teste vs conta real). Certifique-se de usar o token correto.
4

Conectar no Hubpay

  1. Acesse hubpay.dev/dashboard/psps
  2. Clique em Conectar novo PSP
  3. Selecione Iugu
  4. Selecione o ambiente:
    • Test se está usando token de conta de teste
    • Live se está usando token de conta de produção
  5. Dê um label (ex: "Iugu principal")
  6. Cole o API Token
  7. Clique em Salvar credencial
5

Configurar webhook (gatilho)

Após salvar, siga as instruções na tela pra configurar o gatilho no painel do Iugu. O Iugu chama webhooks de "Gatilhos". Configure:

  • Evento: Mudança de Status da Fatura (invoice.status_changed)
  • URL: a URL mostrada na tela do Hubpay
  • Header customizado x-hubpay-token: cole o token mostrado na tela
6

Testar

bash
curl -X POST https://api.hubpay.dev/v1/charges \
  -H "Authorization: Bearer hpx_test_SUA_CHAVE_HUBPAY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "provider": "iugu",
    "description": "Teste Iugu Pix",
    "payer": {
      "email": "teste@example.com",
      "name": "Cliente Teste",
      "document": "12345678900"
    }
  }'
⚠️O Iugu recomenda email do pagador. Se não informar, o Hubpay usa um email padrão, mas recomendamos sempre enviar.

Solução de problemas

ErroCausaSolução
502 com "unauthorized"API Token inválidoVerifique se copiou sem espaços extras
502 com "Pix não habilitado"Pix não ativado na conta IuguAtive em Configurações → Métodos de Pagamento
Invoice criada mas sem Pixpayable_with não incluiu "pix"O Hubpay já configura isso automaticamente. Se persistir, verifique se Pix está ativo na conta
Webhook não chegaGatilho não configuradoConfigure em Configurações → Gatilhos no painel Iugu

Links úteis