Como integrar a iPag na Loja Virtual — Magento 1 openmage
Esta documentação orienta o lojista em todo o processo de integração do gateway de pagamento iPag com a loja virtual Magento 1 openmage. Ao final, sua loja estará configurada para processar pagamentos via Cartão de Crédito, Cartão de Débito, Boleto e Pix através da iPag, conforme desejar configurar.
O que você vai aprender:
- Como localizar e gerar as chaves de API (API ID e API Key) no painel da iPag.
- Como acessar e configurar o módulo iPag dentro do painel administrativo do Magento 1 openmage.
- Como configurar cada forma de pagamento: Cartão de Crédito, Cartão de Débito, Boleto e Pix.
- Como validar se a integração está funcionando corretamente na loja.
É necessário possuir uma conta ativa na iPag e ter permissão para visualizar credenciais de API.
Tutorial em Vídeo
Assista ao vídeo tutorial completo com a demonstração passo a passo da integração:
Parte 1 — Gerar as chaves de API no painel da iPag
Parte 2 — Configurar o Módulo iPag no Magento 1
Passo a Passo por Escrito
A integração é dividida em duas partes: primeiro, a geração das credenciais no painel da iPag; depois, a configuração do módulo dentro do painel Magento 1.
Parte 1 — Gerar as chaves de API no painel da iPag
Passo 1: Acesse o painel da iPag
Resultado esperado: O painel administrativo da iPag é carregado com o dashboard principal.
Passo 2: Acesse as credenciais de integração
No canto superior direito do painel, clique na imagem da sua conta (ícone de perfil). No menu suspenso que será aberto, clique em Credenciais de integração.
Resultado esperado: A tela de "Credenciais de integração" é exibida, mostrando os campos API_ID e API_KEY.
Passo 3: Renove e copie a Chave de API
Na tela de Credenciais de integração:
- Clique no botão vermelho Renovar chave de API.
- Um pop-up solicitará a confirmação da renovação. Clique novamente no botão vermelho para confirmar.
- A nova API_KEY será exibida na tela. Copie a chave clicando no ícone de cópia ao lado do campo.
- Clique em Confirmar para fechar o pop-up.
Resultado esperado: A mensagem "A renovação da chave de API foi concluída" é exibida, e a nova API_KEY está disponível para cópia.
Armazene a chave em local seguro imediatamente. Após clicar em Confirmar, não será possível visualizá-la novamente. Caso perca a chave, será necessário repetir o processo de renovação — e isso invalidará a chave anterior, desconectando integrações ativas.
Parte 2 — Configurar o Módulo iPag no Magento 1
Passo 4: Acesse o módulo iPag no painel Magento
No painel administrativo da sua loja Magento 1 openmage, navegue pelo menu superior até Sistema > Configurações. No menu lateral esquerdo, localize a seção Vendas > Formas de pagamento.
Resultado esperado: Na página é exibida com as seções de cada forma de pagamento da iPag: Cartão de Crédito (IPag), Cartão de Débito (IPag), Boleto (IPag) e Pix (IPag).
Passo 5: Configure o Cartão de Crédito (IPag)
Clique na seção Cartão de Crédito (IPag) para expandir os campos. Preencha conforme abaixo:
| Campo | Valor recomendado |
|---|---|
| Habilitado | Sim |
| Ambiente | Loja |
| Tipo de Transação | Online |
| Mensagem de confirmação (transações híbridas) | Texto de sua preferência |
| Tipo de Cartão de Crédito | Selecione todas as bandeiras que deseja aceitar |
| New order status | Aguardando pagamento |
| Enviar email ao finalizar o pedido? | Sim |
| Título | Cartão de crédito (ou o título que desejar exibir no checkout) |
| Código/Login no IPag | Seu e-mail de acesso ao painel iPag |
| API key IPag | Cole a chave API gerada no Passo 3 |
| Número Máximo de Parcelas | Quantidade de parcelas que você quer deixar disponível na sua loja virtual. |
| Valor mínimo de cada parcela | Valor mínimo por parcela (ex: 10.00), não é necessário colocar "R$" e utilizar o ponto ao invés da virgula, para separar números decimais. |
| Taxa de Juros (%) | Porcentagem de juros por parcela (se desejar aplicar), para o consumidor. |
| Número de parcelas sem juros | Quantidade de parcelas isentas de juros, conforme desejar. |
| Oferecer desconto para pagamento à vista? | Sim ou Não |
| Desconto à vista (em %) | Porcentagem de desconto no crédito à vista |
| Nº Máx. Parcelas por bandeira (Visa, Mastercard, Amex...) | Mesma quantidade informada em "Número Máximo de Parcelas" |
| Gera fatura para transações aprovadas | Somente capturadas |
| Payment from applicable countries | Todos os Países |
| Valor Mínimo do Pedido | Conforme sua regra de negócio |
| Valor Máximo do Pedido | Conforme sua regra de negócio |
| Usar Sandbox IPag | Não (Sim apenas se estiver usando chaves de teste) |
| Verificar retorno das transações no IPag | Sim |
| Cancelar Automaticamente | Sim |
| Valor padrão para conversão | Deixe em branco se utilizar Real (R$) |
| Ativar compra por 1 clique | Não (recomendado manter padrão) |
| Exibir campo CVV para cartões armazenados | Não (recomendado manter padrão) |
| Atributo para bloquear parcelamento | Deixe em branco, a menos que deseje bloquear parcelamento para produtos específicos. Nesse caso, crie um atributo boolean (YES/NO), preencha este campo com o código do atributo e ative-o nos produtos que devem aceitar apenas pagamento à vista. |
| Recuperar documento do cliente do endereço? | Não (Sim somente se utilizar campo customizado para documento) |
Certifique-se de que as bandeiras de cartão informadas no campo "Nº Máx. Parcelas por bandeira" tenham a mesma quantidade inserida no campo "Número Máximo de Parcelas". Configurações divergentes podem causar inconsistências no checkout.
Passo 6: Configure o Pix (IPag)
Clique na seção Pix (IPag) para expandir os campos. Preencha conforme abaixo:
| Campo | Valor recomendado |
|---|---|
| Habilitado | Sim |
| Título | Pix |
| Pix | Pix |
| New order status | Aguardando pagamento |
| Código/Login no IPag | Seu e-mail de acesso ao painel iPag |
| Enviar email ao finalizar o pedido? | Sim |
| Texto Personalizado | "Após a confirmação do pedido, você será redirecionado para a página de visualização do QR Code Pix." |
| Gerar fatura automática para pix pagos | Sim (recomendado) |
| Status para pix faturados automaticamente | Pagamento confirmado |
| Payment from applicable countries | Todos os Países |
| Valor Mínimo do Pedido | Conforme sua regra de negócio |
| Valor Máximo do Pedido | Conforme sua regra de negócio |
| Usar Sandbox IPag | Não (Sim apenas se estiver usando chaves de teste) |
Recomendamos manter a opção "Gerar fatura automática para pix pagos" como Sim, pois isso garante que pedidos pagos via Pix sejam faturados automaticamente ao receber a confirmação de pagamento, evitando trabalho manual.
Passo 7: Configure o Boleto e Débito (IPag) — se necessário
Caso deseje habilitar também Boleto (IPag) e/ou Cartão de Débito (IPag), expanda a respectiva seção e siga a mesma lógica de configuração: habilite o módulo, insira as credenciais (e-mail e API Key), defina os parâmetros de pedido mínimo/máximo e selecione o ambiente correto (Produção ou Sandbox).
Passo 8: Salve a configuração e atualize o cache
Após preencher todos os campos, clique no botão Salvar Configuração no canto superior direito da página.
Resultado esperado: A mensagem "A configuração foi salva" é exibida após salvar.
Em seguida, atualize o cache do Magento. Acesse Sistema > Gerenciamento de Cache, selecione "Marcar todos" e clique no botão laranja "Enviar" ao lado do Atualizar. Para mais detalhes sobre o processo de limpeza de cache, consulte a documentação: Como atualizar o cache do Magento 1.
Resultado esperado: a mensagem "11 tipo(s) de cache atualizados" confirma que as alterações foram aplicadas.
Integração configurada com sucesso. O módulo iPag está ativo e pronto para processar pagamentos na sua loja virtual.
Validação e Testes
Após seguir todos os passos, é fundamental verificar se a integração está funcionando corretamente.
1. Realize um pedido de teste via Cartão de Crédito: Acesse a loja virtual, adicione um produto ao carrinho e finalize a compra selecionando Cartão de Crédito como forma de pagamento. Se estiver em ambiente de produção, utilize um cartão real com valor baixo ou, se em sandbox, utilize os dados de teste fornecidos pela iPag.
2. Realize um pedido de teste via Pix: Repita o processo, desta vez selecionando Pix como forma de pagamento. O QR Code Pix deve ser exibido na tela de confirmação do pedido.
3. Verifique os pedidos no painel Magento: Acesse Vendas > Pedidos no painel administrativo e confirme que os pedidos de teste foram registrados com o status "Aguardando pagamento".
4. Verifique as transações no painel da iPag: Acesse o painel da iPag em https://app.ipag.com.br e confirme que as transações de teste aparecem no histórico de transações.
Resultado esperado: Os pedidos aparecem no painel Magento e as transações correspondentes estão registradas no painel da iPag. Ao confirmar o pagamento (captura no cartão ou pagamento do Pix), o status do pedido é atualizado automaticamente.
Caso o pagamento não seja processado ou o status não seja atualizado, revise as credenciais (e-mail e API Key), verifique se o campo "Verificar retorno das transações no IPag" está como Sim e confirme que o ambiente (Produção/Sandbox) está correto.
Observações Importantes
- Nunca compartilhe suas chaves de API publicamente. Elas funcionam como credenciais de acesso à sua conta na iPag.
- Caso suspeite de uso indevido, acesse o painel da iPag e gere novas chaves imediatamente. Lembre-se de atualizar a nova chave no painel Magento.
- Ambiente Sandbox vs. Produção: Utilize o ambiente Sandbox apenas para testes. Para transações reais, certifique-se de que o campo "Usar Sandbox IPag" esteja como Não e que as chaves inseridas sejam de produção.
Referências e Relacionados
Caso tenha ficado alguma dúvida entre em contato com nosso time de suporte através do chat online dentro da sua loja virtual ou através do e-mail web@tryideas.com.br