VibeFox ifthenpay for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Moeda: somente euro (EUR). O método de pagamento fica oculto quando a moeda do carrinho não é EUR. A ifthenpay aceita valores de 0,01 a 99.999,99 EUR.
Conta ifthenpay: cadastre-se em ifthenpay.com. Você precisa da chave do método que oferece: Multibanco, MB WAY ou Credit Card (formato ABC-123456). As chaves são exibidas no back office da ifthenpay (backoffice.ifthenpay.com) ou enviadas pela ifthenpay quando o método é ativado para a sua conta. A ifthenpay também precisa ativar o callback para a sua chave (veja Configuração), e a sua loja precisa estar acessível pela internet.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure, ou encontre VibeFox ifthenpay Gateway mais tarde na lista de módulos e clique em Configure. O módulo gera a sua chave anti-phishing na instalação.
3. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Escolha o Payment Method, informe a chave da ifthenpay para ele e clique em Save, para que a Callback URL corresponda ao método escolhido.
5. Copie a Anti-phishing Key e a Callback URL exibidas nas configurações e peça à ifthenpay para ativar o callback para a sua chave (no back office ou pelo suporte da ifthenpay).
6. Ative o Enable/Disable e clique em Save.
Na instalação, o módulo cria dois status de pedido: Awaiting ifthenpay payment e ifthenpay payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; o EUR deve continuar permitido.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox ifthenpay Gateway > Configure. Cada seção com o botão Save salva a página inteira. Sem a chave do método selecionado, o método de pagamento não é exibido no checkout. Enquanto o gateway estiver ativado sem essa chave, a página mostra ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.
ifthenpay
Enable/Disable: Enable ifthenpay Payment liga ou desliga o método de pagamento. Padrão: off.
Title: o título do método de pagamento exibido no checkout. Ele também é o nome do método de pagamento salvo no pedido. Padrão: ifthenpay.
Description: a descrição do método de pagamento exibida no checkout. Padrão: Pay via Multibanco, MB WAY or Credit Card. Altere-a para corresponder ao método que você oferece.
Payment Method: o método oferecido no checkout. Somente a chave desse método é obrigatória.
Chaves ifthenpay
As chaves (formato ABC-123456) são exibidas no back office da ifthenpay ou enviadas pela ifthenpay quando o método de pagamento é ativado para a sua conta.
Multibanco Key: a sua chave ifthenpay Multibanco (MB) para referências dinâmicas.
MB WAY Key: a sua chave ifthenpay MB WAY.
Credit Card Key: a sua chave ifthenpay Credit Card. Ela também verifica a assinatura do retorno do cliente a partir da página de cartões.
As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la.
Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Callback (notificações de pagamento)
O callback informa à sua loja que um pagamento foi feito. Peça à ifthenpay para ativar o callback para cada chave que você usa, com a chave anti-phishing e a URL de callback indicadas abaixo. Os pedidos Multibanco e MB WAY são confirmados somente pelo callback; os pagamentos com cartão também são confirmados pelo retorno assinado da página de cartões.
Anti-phishing Key: gerada pelo módulo, exibida para cópia. A ifthenpay a envia de volta em cada callback; callbacks sem ela são rejeitados.
Callback URL: a URL de callback do método de pagamento selecionado, com os marcadores da ifthenpay, exibida para cópia. Com URLs amigáveis, ela começa assim: https://your-shop/module/wcp_ifthenpay_gateway/callback, possivelmente com um código de idioma como /en/, e continua com os parâmetros do método. Copie a URL inteira exatamente como as configurações a exibem.
A chave anti-phishing de cada callback é comparada com a sua. Uma chave ausente ou incorreta recebe a resposta 403, e o pedido não é alterado. O callback também precisa corresponder a um pagamento deste módulo: no Multibanco, pela entidade e referência; no MB WAY, pelo carrinho e uma das suas solicitações MB WAY; no Credit Card, pelo carrinho e uma das suas solicitações de cartão. Sem um callback funcionando, os pedidos Multibanco e MB WAY nunca são confirmados, e os pagamentos com cartão são confirmados somente pelo retorno assinado. O callback funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
Avançado
Test Mode: Credit Card e Multibanco usam os endpoints sandbox da ifthenpay; nenhum dinheiro real é cobrado, e você usa as chaves de teste fornecidas pela ifthenpay. O MB WAY não tem sandbox: teste-o com uma chave de teste da ifthenpay. O checkout exibe um selo TEST MODE. Padrão: off.
Order Status After Payment: o status do pedido definido após um pagamento confirmado, com uma única mudança de status.
Debug Log: as requisições à API e os callbacks são gravados em logs/ifthenpay_p_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados. Chaves, a chave anti-phishing e números de telefone completos nunca são registrados. Padrão: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ativado, ao desinstalar o módulo são removidas as configurações do módulo, a chave anti-phishing e o log. Os pedidos e os registros de pagamento da ifthenpay sempre permanecem. Padrão: off.
Checkout
Multibanco. No checkout, o cliente vê You will receive a Multibanco reference to complete the payment. Quando o cliente confirma, o módulo cria uma referência Multibanco dinâmica para o total do carrinho, e o pedido é criado em Awaiting ifthenpay payment. A página de confirmação do pedido mostra Multibanco Payment Details: entidade, referência e valor, com Please use these details to pay at any Multibanco ATM or through your online banking. Os mesmos dados são adicionados ao e-mail de confirmação do pedido. O pedido é pago quando a ifthenpay envia o callback de pagamento.
MB WAY. O cliente informa o MB WAY phone number (912 345 678, +351 912 345 678 ou 351#912345678 para outros países); o telefone do endereço de cobrança é preenchido. O módulo envia uma solicitação de pagamento para o telefone, e o pedido é criado em Awaiting ifthenpay payment. A página de confirmação do pedido diz A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. O pedido é pago quando a ifthenpay envia o callback. Somente um número de telefone mascarado é armazenado.
Cartão de crédito. O cliente vê You will be redirected to a secure page to enter your card details. e é enviado para a página de cartões da ifthenpay. Ainda não existe pedido, e o carrinho é mantido. Após um pagamento bem-sucedido, o cliente retorna à sua loja. O retorno só é aceito com uma assinatura válida da ifthenpay, a chave segura do carrinho, um segredo dessa tentativa e a solicitação de cartão do carrinho; então o pedido é criado como pago, e o cliente vê a página padrão de confirmação do pedido. Se o retorno não puder ser verificado, nada muda, e uma página Payment confirmation mostra Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. com o botão Check again; o callback cria o pedido assim que chegar. Se o pagamento com cartão falhar ou for cancelado, o cliente volta ao checkout com The card payment was not completed. You can try again or choose another payment method. ou The card payment was cancelled. You can try again or choose another payment method. Cada tentativa de cartão do carrinho é mantida, por isso um pagamento feito em uma aba anterior ainda é aceito.
O pedido só é marcado como pago depois que a ifthenpay confirma, e o valor é conferido até o centavo com o total do pedido. Se o pagamento não puder ser iniciado, o cliente permanece no checkout com uma mensagem curta, por exemplo The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. ou The payment service is temporarily unavailable. Please try again in a few minutes. O motivo técnico é gravado no log.
O módulo oferece um método ifthenpay por vez. Não há suporte a Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX ou Pay-by-Link, nem a assinaturas ou cartões salvos, nem a expiração ou cancelamento automático de referências Multibanco não pagas, nem a consulta do status do pagamento.
Pedidos
Status do pedido
No order yet: um pagamento com cartão foi iniciado e ainda não está confirmado, ou falhou ou foi cancelado. Existe apenas o carrinho.
Awaiting ifthenpay payment: uma referência Multibanco foi emitida ou uma solicitação MB WAY foi enviada. O PrestaShop reduz o estoque quando o pedido é criado. Referências não pagas e solicitações MB WAY recusadas não cancelam o pedido automaticamente; cancele você mesmo esses pedidos, se necessário.
Payment accepted or Delivered: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com a referência Multibanco, o ID da solicitação MB WAY ou o ID da solicitação do cartão como ID da transação, e uma nota mostra como ele foi confirmado.
ifthenpay payment on hold: o valor recebido foi diferente do total do pedido (por exemplo, o carrinho foi alterado depois que um pagamento com cartão começou), ou o pagamento chegou depois que o pedido foi cancelado. A nota explica isso, e o cliente não é solicitado a pagar novamente. Verifique o pagamento no back office da ifthenpay e conclua ou reembolse o pedido manualmente. Um pagamento correto posterior para esse pedido não o altera.
Um segundo pagamento para um pedido que já está pago apenas acrescenta uma nota, para verificar se há um pagamento duplicado no back office da ifthenpay. Pedidos reembolsados e pedidos cancelados após o pagamento nunca são reabertos.
Bloco de pagamento da ifthenpay
A página do pedido mostra um bloco ifthenpay payment com as tentativas de pagamento do pedido (data, método, um selo Sandbox para pagamentos de teste, valor, entidade e referência Multibanco ou o telefone MB WAY mascarado, ID da solicitação da ifthenpay e status), um aviso Manual review enquanto o pedido estiver em ifthenpay payment on hold, e as ifthenpay notes do pedido.
Reembolsos
Reembolsos pelo PrestaShop não são suportados. Reembolse o pagamento no back office da ifthenpay e registre-o manualmente no PrestaShop. Um callback de devolução (DEVOLVIDO) apenas acrescenta uma nota. Os demais status informados pela ifthenpay também apenas acrescentam uma nota.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox ifthenpay Gateway é o primeiro bloco em Modules > Module Manager > VibeFox ifthenpay Gateway > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo aparecem a linha Product: presta-payment-ifthenpay e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a ifthenpay não é exibida aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A loja PrestaShop não sabe que você está conectado ao back office, então o método de pagamento também fica oculto para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A ifthenpay não aparece no checkout: verifique se a licença está ativa, se o Enable/Disable está ligado, se a chave do Payment Method selecionado está preenchida, se a moeda do carrinho é EUR e se o total está entre 0,01 e 99.999,99 EUR. Em Payment > Preferences, verifique se o módulo está permitido para o EUR, para o país do cliente e para o grupo do cliente.
O cliente pagou, mas o pedido continua em Awaiting ifthenpay payment ou nenhum pedido foi criado: o callback não está chegando à sua loja. Verifique se a ifthenpay ativou a URL de callback e a chave anti-phishing para a chave que você usa, e se a URL é a do método selecionado. A loja precisa estar acessível pela internet, não em localhost nem atrás de um login. Procure as linhas Callback rejected no campo Log na página do módulo.
O callback responde 403 Forbidden: a chave anti-phishing no callback está ausente ou é diferente da que está nas configurações. Envie novamente à ifthenpay a chave exibida nas configurações.
O callback responde 503 Not configured: a chave anti-phishing ainda não foi gerada. Abra uma vez as configurações do módulo; a ifthenpay tentará o callback novamente.
O callback responde 503 Busy: o mesmo carrinho estava sendo processado por outra requisição naquele momento. A ifthenpay tentará o callback novamente.
O callback responde Order not found: a referência ou a solicitação não pertence a um pagamento deste módulo, ou o carrinho foi pedido com outro método de pagamento.
Por que um pedido pago foi colocado em espera? O valor recebido era diferente do total do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Leia as notas no bloco ifthenpay payment, verifique o pagamento no back office da ifthenpay e conclua ou reembolse o pedido manualmente.
Não foi possível enviar a solicitação MB WAY: o número de telefone não está vinculado ao MB WAY ou está em formato incorreto. Use 912 345 678, ou 351#912345678 para números de outros países.
Modo de teste e MB WAY: a ifthenpay não tem sandbox para o MB WAY; use uma chave de teste fornecida pela ifthenpay.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox ifthenpay Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se o Delete Data on Uninstall estiver ativado, as configurações do módulo, a chave anti-phishing e o log são removidos; após uma reinstalação, uma nova chave anti-phishing é gerada e precisa ser enviada novamente à ifthenpay. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamento da ifthenpay (referências e IDs de solicitação) e os status de pedido Awaiting ifthenpay payment e ifthenpay payment on hold são sempre mantidos, para que os callbacks de referências emitidas antes encontrem seus pedidos após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.
A ifthenpay é uma marca de seu respectivo titular. Este módulo não é afiliado nem endossado pela ifthenpay.