VibeFox ifthenpay for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posterior (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: somente euro (EUR). A moeda EUR precisa estar habilitada na sua loja, e o método de pagamento só é exibido quando o cliente paga em 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 backoffice 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 domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote do OpenCart 3 wcp_ifthenpay_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_ifthenpay_gateway.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel de administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_ifthenpay_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo Payments. Localize VibeFox ifthenpay Gateway e clique em Install (o botão verde +). O seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento. A extensão gera a sua chave anti-phishing na instalação.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole a sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja Chave de licença).

4. Escolha o Payment Method, informe a chave ifthenpay dele e clique em Save, para que a Callback URL corresponda ao método escolhido.

5. Copie a Anti-phishing Key e a Callback URL da seção Callback e peça à ifthenpay que ative o callback para a sua chave (no backoffice ou pelo suporte da ifthenpay).

6. Ative Enable/Disable e clique em Save.

OpenCart 4

1. No painel de administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_ifthenpay_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo Payments. Localize VibeFox ifthenpay Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença, o método e a chave dele, e ative o callback como nas etapas 3 a 6 do OpenCart 3. A página de configurações e os campos são os mesmos nas duas versões. Só a Callback URL é diferente (veja Callback).

Uma instalação nova começa com o método de pagamento desativado e o modo de teste desativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Sem a chave do método selecionado, o método de pagamento não aparece na finalização de compra. Enquanto o gateway estiver habilitado sem essa chave, a página mostra ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, o método de pagamento precisa ser válido, o título pode ter no máximo 128 caracteres, Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0, e a zona geográfica e os status de pedido devem existir; caso contrário, nada é salvo.

ifthenpay

Enable/Disable: Enable ifthenpay Payment liga ou desliga o método de pagamento. Padrão: desligado.

Title: o título do método de pagamento exibido na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: ifthenpay. Se você deixar em branco, a finalização de compra mostrará ifthenpay.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay via Multibanco, MB WAY or Credit Card. Altere para corresponder ao método que você oferece.

Payment Method: o método oferecido na finalização de compra. Apenas a chave deste método é obrigatória.

Sort Order: a posição da ifthenpay entre os métodos de pagamento da finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: ofereça a ifthenpay somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que a ifthenpay seja oferecida. Deixe em branco para oferecer a ifthenpay com qualquer total. A ifthenpay só é oferecida quando o cliente paga em EUR, para valores de 0,01 a 99.999,99 EUR.

Chaves da ifthenpay

As chaves (formato ABC-123456) são exibidas no backoffice da ifthenpay (a seção tem um link para ele) 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 da página do cartão.

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á-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

Callback

O callback informa à sua loja que um pagamento foi feito. Peça à ifthenpay que ative o callback para cada chave que você usa, com a chave anti-phishing e a URL de callback desta seção. Pedidos de Multibanco e MB WAY são confirmados somente pelo callback; pagamentos com cartão também são confirmados pelo retorno assinado da página do cartão.

Anti-phishing Key: gerada pela extensão e 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. No OpenCart 3 ela começa com https://your-store/index.php?route=extension/payment/wcp_ifthenpay_gateway/callback; no OpenCart 4, com https://your-store/index.php?route=extension/wcp_ifthenpay_gateway/payment/wcp_ifthenpay_gateway.callback. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart e continua com os parâmetros do método. Copie a URL completa exatamente como as configurações a mostram. Se você alterar o Payment Method, salve e copie a nova URL.

A chave anti-phishing de cada callback é comparada com a sua. Uma chave ausente ou errada recebe a resposta 403, e o pedido não é alterado. O callback também precisa corresponder a um pagamento desta extensão: no Multibanco, por entidade e referência; no MB WAY, pelo pedido e por uma das suas solicitações MB WAY; no Credit Card, pelo pedido e por uma das suas solicitações de cartão. Sem um callback funcionando, pedidos de Multibanco e MB WAY nunca são confirmados, e pagamentos com cartão são confirmados somente pelo retorno assinado. O callback também funciona enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização que deixa passar o callback e o retorno do cliente da página do cartão.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Com Multibanco e MB WAY, o pedido recebe o status de espera assim que a ifthenpay emite a referência ou a solicitação MB WAY; com Credit Card, o pedido só recebe um status pelo callback ou pelo retorno assinado. Um pedido só é marcado como pago quando o valor corresponde ao total do pedido até o centavo. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido quando o pagamento é confirmado. Padrão: Processando.

Awaiting payment status: uma referência Multibanco ou uma solicitação MB WAY foi emitida, e o cliente ainda precisa pagar. Os dados do Multibanco são enviados com este status, no e-mail do pedido e no histórico de pedidos do cliente. Padrão: Pendente.

Payment on hold status: a ifthenpay informou um pagamento que não corresponde ao pedido (valor, moeda), um pagamento feito depois que o pedido foi cancelado, ou um pagamento de um pedido cujo carrinho já estava pago. Uma nota explica o motivo. Padrão: Pendente, porque o OpenCart não tem um status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

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. A etapa Confirm Order mostra um selo TEST MODE. Padrão: desligado.

Debug Log: requisições de API e callbacks são gravados em ifthenpay_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e é rotacionado ao atingir 5 MB. Erros são sempre registrados. Chaves, a chave anti-phishing e números de telefone completos nunca são registrados. Padrão: desligado.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para limpá-lo.

Delete Data on Uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway, a chave anti-phishing e o log. Pedidos e registros de pagamento da ifthenpay são sempre mantidos. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves da ifthenpay não são exportadas.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. Chaves salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, ifthenpay). Na etapa Confirm Order, o cliente vê a sua descrição e a indicação do método. O OpenCart cria o pedido nessa etapa, ainda sem status.

No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte de baixo da página de finalização de compra.

Multibanco. O cliente vê You will receive a Multibanco reference to complete the payment. Quando o cliente clica em Confirm Order, a extensão cria uma referência Multibanco dinâmica para o total do pedido, e o pedido recebe o Awaiting payment status. A página de sucesso 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 enviados no e-mail do pedido e aparecem no histórico de pedidos do cliente. Se já tiver sido emitida uma referência para o pedido com o mesmo valor, ela é reutilizada. O pedido é pago quando a ifthenpay envia o callback de pagamento.

MB WAY. O cliente digita o MB WAY phone number (912 345 678, +351 912 345 678 ou 351#912345678 para outros países); o telefone do pedido é preenchido. A extensão envia uma solicitação de pagamento para o telefone, e o pedido recebe o Awaiting payment status. A página de sucesso 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. Por padrão, o OpenCart 4 não pede telefone na finalização de compra; o campo fica vazio e o cliente informa o número.

Credit Card. O cliente vê You will be redirected to a secure page to enter your card details. e é enviado à página de cartão da ifthenpay. O pedido permanece sem status, e o carrinho é mantido. Após um pagamento bem-sucedido, o cliente volta à sua loja. O retorno só é aceito com uma assinatura válida da ifthenpay, um segredo daquela tentativa e uma solicitação de cartão do pedido; então o pedido é marcado como pago, e o cliente vê a página de sucesso do pedido do OpenCart. Se o retorno não puder ser verificado, nada muda, e uma página de Payment confirmation mostra Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. com os botões Check again e Back to checkout; o callback confirma o pagamento assim que chega. Se o pagamento com cartão falhar ou for cancelado, o cliente volta à finalização de compra 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 pedido é mantida, então um pagamento feito em uma aba antiga também é aceito. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra.

Quando o pagamento é confirmado, o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails de pedido habituais. O OpenCart 3 cria um novo pedido toda vez que a etapa Confirm Order é exibida; o OpenCart 4 atualiza o pedido da finalização de compra, então, após um pagamento com cartão cancelado ou com falha, ou uma solicitação MB WAY recusada, o cliente paga o mesmo pedido com uma nova tentativa. Se o mesmo carrinho já tiver um pedido pago ou um pedido aguardando pagamento de Multibanco ou MB WAY, o cliente vai para a página de sucesso desse pedido, em vez de iniciar um novo pagamento. Os dados do Multibanco e a indicação do MB WAY só são exibidos na página de sucesso enquanto o pedido estiver aguardando pagamento. Uma alteração do carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio.

No OpenCart 4, o pedido permanece na finalização de compra até a página de sucesso ser exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio tempo (por exemplo, você cancelou um pedido aguardando pagamento de Multibanco), o cliente volta à finalização de compra com Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Se o pedido já tiver sido feito e o carrinho tiver mudado desde então, a mensagem é Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. Nos dois casos, o próximo Confirm Order paga um novo pedido do carrinho.

Se o pagamento não puder ser iniciado, o cliente permanece na etapa Confirm Order com uma mensagem curta acima do botão, 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.

A extensão oferece um método ifthenpay por vez. Ela não tem Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX ou Pay-by-Link, nem assinaturas ou cartões salvos, nem expiração ou cancelamento automático de referências Multibanco não pagas, nem consulta do status de pagamento.

Pedidos

Status do pedido

No status (missing order): um pagamento com cartão foi iniciado e ainda não foi confirmado, ou falhou ou foi cancelado. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Awaiting payment status (default Pending): uma referência Multibanco foi emitida ou uma solicitação MB WAY foi enviada. Referências não pagas e solicitações MB WAY recusadas não cancelam o pedido automaticamente; cancele esses pedidos você mesmo, se necessário.

Order Status After Payment (default Processing): o pagamento foi confirmado. Uma nota mostra a referência Multibanco, a transação MB WAY ou o ID da solicitação de cartão, e como foi a confirmação.

Payment on hold status (default Pending): o valor recebido era diferente do total do pedido (por exemplo, o carrinho foi alterado depois que um pagamento com cartão foi iniciado), o pagamento chegou depois que o pedido foi cancelado, ou outro pedido do mesmo carrinho já estava pago. A nota explica, e o cliente não é solicitado a pagar novamente. Confira o pagamento no backoffice da ifthenpay e conclua ou reembolse o pedido manualmente. Um pagamento correto posterior para um pedido assim não o altera.

Um segundo pagamento para um pedido que já está pago apenas adiciona uma nota para verificar uma possível cobrança duplicada no backoffice da ifthenpay. Um pedido que você tenha movido para outro status (por exemplo, reembolsado) nunca é reaberto; uma nota é adicionada.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox ifthenpay Gateway

Em Sales > Orders, abra um pedido pago com a ifthenpay. Na parte de baixo da página do pedido, ao lado de History e Additional, a aba VibeFox ifthenpay Gateway lista as tentativas de pagamento do pedido (data, método, um rótulo Sandbox para pagamentos de teste, valor, entidade e referência do Multibanco ou o telefone mascarado do MB WAY, ID da solicitação da ifthenpay e status), um aviso Payment on hold enquanto o pedido estiver retido, e as ifthenpay notes do pedido. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos pelo OpenCart não são suportados. Reembolse o pagamento no backoffice da ifthenpay e registre-o manualmente no OpenCart. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela ifthenpay. Um callback de reembolso (DEVOLVIDO) apenas adiciona uma nota. Outros status informados pela ifthenpay também apenas adicionam uma nota.

Chave de licença

A extensão 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 Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit, acima das configurações. Cole 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 deles estão a linha Product: opencart-payment-ifthenpay e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do administrador (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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a sua vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a ifthenpay não é exibida aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente verá This payment method is not available. Please choose another one. Um usuário administrador conectado ao painel no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4, essa prévia não está disponível: a loja não vê o login do administrador, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit do painel: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A ifthenpay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se a chave do Payment Method selecionado está preenchida, se o cliente paga em EUR e se o total está entre 0,01 e 99.999,99 EUR. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido.

O cliente pagou, mas o pedido continua aguardando pagamento ou sem status: 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. Ative o Debug Log e veja o campo Log na página da extensão.

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 mostrada nas configurações.

O callback responde 503 Not configured: a chave anti-phishing ainda não foi gerada. Abra as configurações da extensão uma vez; a ifthenpay tentará o callback novamente.

O callback responde 503 Busy: o mesmo pedido 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 desta extensão, ou o pedido foi feito com outro método de pagamento.

Por que um pedido pago foi colocado em espera? O valor recebido era diferente do total do pedido, o pagamento chegou depois que o pedido foi cancelado, ou outro pedido do mesmo carrinho já estava pago. Leia as notas na aba VibeFox ifthenpay Gateway, confira o pagamento no backoffice da ifthenpay e conclua ou reembolse o pedido manualmente.

A solicitação MB WAY não pôde ser enviada: o número de telefone não está vinculado ao MB WAY ou está em um formato errado. 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

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox ifthenpay Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos valores padrão em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixa passar o callback e o retorno do cliente no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway, 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, eles são mantidos para uma reinstalação posterior. Os registros de pagamento da ifthenpay (referências e IDs de solicitação) são sempre mantidos, então os callbacks de referências emitidas antes continuam encontrando os seus pedidos após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox ifthenpay Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

ifthenpay é uma marca comercial de seu respectivo titular. Esta extensão não é afiliada nem endossada pela ifthenpay.