G UIA DE I NSTALAÇÃO. Módulo ipagare para Magento - versão PDF
Download "G UIA DE I NSTALAÇÃO. Módulo ipagare para Magento - versão 3.3"
1 G UIA DE I NSTALAÇÃO Módulo ipagare para Magento - versão 3.3 De 27/10/2011
2 ÍNDICE 1. PREFÁCIO... 3 Este documento... 3 Confidencialidade... 3 Histórico de atualizações APRESENTAÇÃO... 4 Novidades... 4 Serial de uso... 4 Limitações ou problemas conhecidos... 4 Requisitos... 5 Atualizando... 5 Outras informações INSTALANDO O MÓDULO STATUS DOS PEDIDOS RECURSOS ADICIONAIS... 9 Compra com 1 clique... 9 Gestão de risco ClearSale CUSTOMIZANDO O MÓDULO Modificando os parâmetros enviados pelo Magento Processando campainhas do ipagare Exibição da URL da página de sucesso Exibição da URL da página de falha RESOLVENDO PROBLEMAS COMUNS
3 1. Prefácio Este documento Este documento objetiva guiar o processo de instalação do módulo do sistema de pagamento online ipagare para a plataforma de e-commerce Magento. Confidencialidade O destinatário deste documento obriga-se a manter sigilo relativamente a todos os termos e condições deste guia, bem como acerca de quaisquer informações, materiais, documentos, especificações técnicas ou comerciais, marcas e patentes, direitos de autor, inovações e aperfeiçoamentos desenvolvidos ou a desenvolver, relativamente às partes, rotinas, módulos, conjunto de módulos, softwares ou sistemas, ou dados gerais que, em razão do presente guia, venha a ter acesso ou conhecimento, não podendo, sob qualquer pretexto, revelar, reproduzir ou deles dar conhecimento a terceiros, salvo por determinação judicial ou se houver consentimento autorizado específico, prévio e por escrito da IDEA TECNOLOGIA DA INFORMAÇÃO LTDA. Histórico de atualizações Data Alterações 27/10/2011 Compatível com novas versões do Magento: - Community 1.6 e Enterprise 1.10 e 1.11 Captura e cancelamento de pagamentos por cartão de crédito através do backoffice do Magento. 09/09/2011 Novidades da versão 3.2 do módulo Versão 3.0 ou superior é gratuita para clientes antigos (fechados até 31/08/2011) ipagare Premium e paga para novos clientes (a partir de 01/09/2011). Instruções sobre obtenção do serial de uso 26/07/2011 Recurso de compra com 1 clique Automatizações na instalação do módulo 20/06/2011 Criação do documento 3
4 2. Apresentação Novidades Esta versão apresenta as seguintes novidades: Compatível com novas versões do Magento: Community 1.6 e Enterprise 1.10 e Cancelamento e captura de pagamentos por cartão de crédito através do backoffice do Magento. Serial de uso Desde a versão 3.2 você precisa de um Serial para configurar o módulo no Magento, além do Código do Estabelecimento e Código de Segurança. Sem o Serial não é possível realizar vendas em ambiente de produção, apenas em teste. Para futuras versões do módulo, o Serial será o mesmo. Para obter o seu Serial: - se você já é cliente ipagare antes de 31/08/2011, entre em contato com nosso suporte técnico e solicite a geração do Serial gratuitamente. Após, ele estará sempre disponível no menu Configurações > Módulos > Magento do Painel de Controle do ipagare. - se você se tornou cliente ipagare após 01/09/2011 e contratou o módulo Magento, obtenha o serial a partir do menu Configurações > Módulos > Magento do Painel de Controle do ipagare. Caso você não tenha acesso a este menu, entre em contato com nosso suporte. Limitações ou problemas conhecidos Temos conhecimento das seguintes limitações nesta versão: Não possui suporte a multishipping. Um novo pedido é gerado ao tentar pagar novamente um pedido a partir da página de falha. Para que não ocorra problemas com o Internet Explorer 9, é necessário realizar uma das alterações abaixo: o Solução 1: ir em admin/sistema/configurações/design/html head/miscellaneous Scripts e adicionar: <meta http-equiv="x-ua-compatible" content="ie=8" /> 4
5 o o Solução 2: ir em: skin/frontend/base/default/js/opcheckout.js e comentar a linha (aprox. 643). Conteúdo da linha: elements[i].disabled = true; Este problema de compatibilidade é do Magento e ocorre também com outros métodos de pagamento. OneStepCheckout: se existir mais de um método de pagamento instalado no Magento (além do módulo ipagare), o OSC só carrega o bloco HTML do método de pagamento selecionado na página. Os blocos dos outros métodos não são carregados. Esta é uma limitação do próprio OSC. Se ocorrer o erro HTTP 404 (NOT FOUND) ao tentar acessar as configurações do módulo na Administração do Magento, faça o seguinte: o o o Faça logout da Administração Limpe a cache em /var/cache Faça login na Administração e tente acessar o módulo. Requisitos Magento Community: , 1.4.2, 1.5, 1.6 e Enterprise: 1.10 e ipagare Conta ipagare Premium. Se você não tem uma conta, acesse Atualizando Se você está atualizando a partir de qualquer versão anterior, é importante saber que a versão 3.3 ainda não possui suporte a multishipping, que são contempladas nas próximas versões. Se você utiliza esta funcionalidade com uma versão antiga do módulo, não faça a atualização. Se você utiliza o recurso de compra com 1 clique com a versão 2.3 do módulo, não atualize para a versão 3.3. Entre em contato com nossa equipe de suporte para obter outras orientações. Importante: - Teste o módulo primeiro e só depois instale em produção. Se a sua loja já está em produção, monte um ambiente de testes com os mesmos módulos e plugins do 5
6 ambiente de produção e teste o módulo ipagare Magento. Caso tudo esteja funcionando corretamente, instale o módulo em produção. - Desinstale versões anteriores do módulo. Se você já utiliza alguma versão anterior do módulo ipagare Magento, desinstale todo o módulo e instale a versão 3.2. Não utilize a opção Reinstalar do Magento Connect. Outras informações Instalação do Magento Este guia não tratará sobre a instalação do Magento. Para tal, consulte a respectiva documentação em Leitura da documentação de integração do ipagare É recomendável a leitura dos guias de integração do ipagare, disponíveis em para a compreensão dos parâmetros que são citados neste documento. Envio de s O presente módulo não realiza o envio de s pelo Magento na confirmação do pagamento, pois o ipagare já possui esta funcionalidade. 6
7 3. Instalando o módulo A instalação é muito simples. Basta você acessar o Painel de Controle do ipagare: Se você ainda não estiver integrado com o ipagare, uma caixa será exibida no canto superior direito da tela dando a opção de configurar a conta para uso com Magento. Se esta caixa não aparecer, acesse o menu Configurações > Integração e após a tab Magento. Você será redirecionado ao passo-a-passo de instalação. É só seguir todas as instruções. 7
8 4. Status dos pedidos Quando há troca de informação entre seu site e o ipagare, o status do pedido pode ser alterado. Abaixo, segue a tabela de como um pedido pode se comportar de sua efetivação até a confirmação do pagamento pelo ipagare. Ação Status em seu site Status no ipagare Pedido efetuado Pendente (Pending) Novo Emissão de boleto Pendente (Pending) Pendente Pagamento efetuado Confirmado (Confirmed) Magento x Em processamento (Processing) Magento 1.4.x, 1.5.x e 1.6.x. Fatura do pedido é gerada. Pendente se cartão de crédito sem captura Pago demais casos Pedido cancelado (via administração do Magento) Cancelado (Canceled) Não há alteração Pagamento cancelado (via painel do ipagare) Cancelado (Canceled) Cancelado 8
9 5. Recursos adicionais Compra com 1 clique O recurso de Compra com 1 Clique do ipagare permite ao estabelecimento: Oferecer um processo de pagamento mais rápido e fácil Favorecer a venda por impulso Estimular clientes a realizar novas compras Fidelizar clientes Como funciona Quando o cliente for realizar o pagamento, ao informar os dados do cartão de crédito ele poderá marcar a opção Armazenar meu cartão. O cartão de crédito será encriptado e armazenado de forma segura no ipagare. 9
10 Na próxima compra que o cliente realizar em sua loja, o cartão de crédito armazenado será apresentado como primeira opção de pagamento. O cliente poderá escolher pagar com este cartão ou utilizar as outras opções de pagamento. Configuração Para ativar a Compra com 1 Clique, acesse a Administração do Magento: Acesse o menu System > Configuration > Payment Methods. Selecione a opção Yes em Habilitar compra com 1 clique? nas configurações do ipagare. O recurso de Compra com 1 Clique também deve estar ativo no ipagare. Para tanto, acesse o Painel de Controle do ipagare: Acesse o menu Configurações > Compra com 1 Clique. Marque a opção Sim em Ativar módulo de compra com 1 clique. 10
11 Atualizando da versão 2.3 Se você utiliza a compra com 1 clique com a versão 2.3 do módulo ipagare Magento, não faça a atualização para a versão 3.1. Entre em contato com nossa equipe de suporte para receber outras orientações. Outras informações Visitantes e clientes não logados não terão a opção de Armazenar meu cartão. O estabelecimento não consegue saber quais clientes tem cartão armazenado salvo e não tem acesso aos dados de cartão de crédito dos clientes. Apenas o cliente sabe se tem um cartão armazenado, durante o checkout. O cliente pode, durante o checkout, remover o cartão de crédito. Cada cliente pode ter apenas um cartão de crédito armazenado. O módulo ipagare Magento implementa o recurso de compra com 1 clique do ipagare, conforme descrito na documentação da API ( clique). Para armazenar os tokens de cada cartão de crédito armazenado, é criada uma tabela automaticamente durante a instalação do módulo em seu Magento. Se a tabela já existir, esta será sobrescrita. Gestão de risco ClearSale A solução de gestão de risco ClearSale permite o estabelecimento identificar transações com risco de fraude e já está integrada ao ipagare. Configuração Para ativar a gestão de risco, acesse o menu Configurações > Gestão de Risco ClearSale do Painel de Controle do ipagare e marque a opção Ativo. Após, acesse o menu System > Configuration > Payment Methods da Administração do Magento e execute 3 tarefas de instalação necessárias para o correto funcionamento do ClearSale: 1. Cadastro dos estados brasileiros: é realizado o cadastro de estados brasileiros. Caso a sua loja Magento já tenha este cadastro, não é necessário executar esta tarefa. 2. Exibir CPF/CNPJ como obrigatório: o campo de CPF/CNPJ será considerado obrigatório. Caso a sua loja Magento já tenha este campo como obrigatório, não é necessário executar esta tarefa. 3. Sobrescrever os arquivos de endereço: por padrão, o Magento exibe apenas dois campos de endereço, sem separar o logradouro, número, complemento e bairro. Esta tarefa, ao ser executada, cria mais duas linhas de endereço, totalizando 4, e adiciona labels para cada um dos campos de endereço. 11
13 6. Customizando o módulo Abaixo são apresentadas configurações opcionais caso se deseje modificar o comportamento padrão do módulo e da integração do ipagare com o Magento. IMPORTANTE: estas customizações requerem alteração nos códigos-fonte do módulo. Qualquer alteração imprópria pode afetar o funcionamento do mesmo. Modificando os parâmetros enviados pelo Magento Para modificar os parâmetros enviados pela loja Magento ao ipagare, siga os seguintes passos: 1. Abra o arquivo \app\code\local\mage\ipagare\model\api\ipagare.php 2. Localize os seguintes métodos: getpayparams: método que monta os parâmetros enviados ao ipagare. getopcoespagamento: método que monta as opções de pagamento apresentadas ao usuário. Este método não está implementado. Consulte o Guia de Integração Outros Serviços do ipagare para maiores informações sobre como personalizar as opções de pagamento. Processando campainhas do ipagare É possível alterar a maneira como seu site processa as campainhas de status de pagamentos enviadas pelo ipagare. Abaixo, são apresentados os comportamentos padrão do módulo e como proceder para modificar estes comportamentos. Campainha de alteração de status O recebimento e o processamento dos parâmetros é realizado no arquivo No método \app\code\local\mage\ipagare\controllers\ipgcontroller.php notificationaction() O módulo processa os parâmetros retornados pelo ipagare e gera a fatura do pedido (Magento 1.4.x, 1.5.x e 1.6.x) em caso de pagamento confirmado. Para alterar este comportamento, realize alterações no método citado. 13
14 Campainha de falha de pagamento O recebimento da campainha de falha de pagamento é realizado no arquivo No método \app\code\local\mage\ipagare\controllers\ipgcontroller.php paymentfailureaction() Não foi implementada nenhuma lógica no processamento desta campainha. Apenas são buscados os parâmetros enviados pelo ipagare e nada é feito. Para modificar o comportamento, altere o método citado. Exibição da URL da página de sucesso A exibição da página de sucesso no pagamento é realizado no arquivo No método \app\code\local\mage\ipagare\controllers\ipgcontroller.php successaction() O módulo processa os parâmetros retornados pelo ipagare e gera a fatura do pedido (Magento 1.4.x, 1.5.x e 1.6.x) em caso de pagamento confirmado. Para modificar a página de sucesso, use o arquivo: \app\design\frontend\default\default\template\ipagare\success.phtml Exibição da URL da página de falha A exibição da página de falha no pagamento é realizado no arquivo \app\code\local\mage\ipagare\controllers\ipgcontroller.php No método failureaction() O módulo processa os parâmetros retornados e exibe o motivo da falha no pagamento. Além disso, permite que o cliente tente pagar novamente o pedido. Para modificar a página de falha, use o arquivo: \app\design\frontend\default\default\template\ipagare\failure.phtml 14
15 7. Resolvendo problemas comuns Abaixo segue uma relação de problemas comuns durante a instalação do módulo ipagare para Magento, e qual a ação a ser tomada. Após realizar qualquer alteração informada neste guia, a cache do Magento deve ser limpa para o correto funcionamento. Para isso, abra a pasta RAIZ_MAGENTO\var\cache\ E apague todo seu conteúdo. Para certificar-se que a integração está funcionando corretamente, faça uma compra pela loja Magento e vá até o final efetuando um pagamento com sucesso. Ao consultar o pedido na administração do Magento, o mesmo deve estar com status "Completo" ou Processando, dependendo da versão do Magento. Se o pagamento teve sucesso e mesmo assim o status do pedido está "Pendente" (Magento x) ou a fatura não foi gerada (Magento 1.4.x, 1.5.x e 1.6.x), há duas possibilidades: o O ipagare não conseguiu enviar para o Magento a campainha de pagamento confirmado através da URL DE CAMPAINHA. Se for este o caso, o ipagare tentará realizar cinco tentativas de campainha e, se não conseguir, enviará um para os endereços de configurados no Painel de Controle, menu "Configurações > Integração", campo " s para notificações de erros". o A versão de campainha configurada no ipagare ( Configurações > Integração ) está diferente da versão configurada no admin do Magento. Verifique se a URL DE CAMPAINHA está corretamente configurada e se a mesma é acessível, pois é através dela que o Magento recebe a campainha de sucesso e altera o status do pedido para "Completo" ou Processando. Se seu site não possui https (conexão segura) na página de pagamento, é provável que o navegador pergunte ao usuário se ele deseja exibir os itens não seguros da página (pois o ipagare possui conexão segura). Se o usuário responder não", o comportamento pode não ser o esperado. Se o carrinho de compras não é limpo após pagar o pedido, verifique se as URLs estão configuradas corretamente no painel de controle do ipagare. Se ainda assim o problema persistir e seu site utilizar um tema personalizado, verifique se foram seguidas corretamente as instruções da seção Instalando o módulo no Magento com tema personalizado deste documento. Se algum parâmetro está chegando ao ipagare sem nenhum valor, é possível que haja problema em alguma customização realizada no Magento. Para verificar, ative o log do Magento e, no arquivo RAIZ_MAGENTO\app\code\local\Mage\Ipagare\Model\Api\Ipagare.php método getpayparams, descomente a linha 165 (aproximadamente), cujo conteúdo é Mage::log($requestParams); 15