VibeFox ifthenpay for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Moeda: somente euro (EUR). O método de pagamento fica oculto quando a moeda da loja ou do pedido não é EUR. A ifthenpay aceita valores totais 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

1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_ifthenpay_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate. O plugin gera a sua chave anti-phishing.

3. Abra as configurações: WooCommerce > Settings > Payments > ifthenpay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Informe a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Escolha o Payment Method e informe a chave ifthenpay correspondente. Salve, para que a Callback URL corresponda ao método escolhido.

6. 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 backoffice ou pelo suporte da ifthenpay).

7. Ative o Enable/Disable.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > ifthenpay. Sem a chave do método selecionado, o método de pagamento não aparece na finalização da compra, e a lista de métodos de pagamento o marca como precisando de ação. Ao salvar um gateway ativado sem essa chave, a página exibe ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.

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 da compra. Padrão: ifthenpay.

Description: a descrição do método de pagamento exibida na finalização da compra. 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 da compra. Só a chave desse método é obrigatória.

Chaves ifthenpay

As chaves (formato ABC-123456) são exibidas no backoffice da ifthenpay ou enviadas pela ifthenpay quando o método de pagamento é ativado para a sua conta.

Multibanco Key: sua chave ifthenpay Multibanco (MB) para referências dinâmicas.

MB WAY Key: sua chave ifthenpay MB WAY.

Credit Card Key: sua chave ifthenpay Credit Card. Ela também verifica a assinatura do retorno do cliente da página de cartões.

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. Pedidos 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 de cartões.

Anti-phishing Key: gerada pelo plugin, 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. Começa com https://your-site/wc-api/ifthenpay_payment_callback/ e continua com os parâmetros do método. Copie a URL completa exatamente como as configurações a mostram.

A chave anti-phishing de cada callback é comparada com a sua. Uma chave ausente ou incorreta recebe resposta 403, e o pedido não é alterado. O callback também precisa corresponder a um pedido deste gateway: no Multibanco, por entidade e referência; no MB WAY, pelo pedido e uma das suas solicitações MB WAY; no cartão de crédito, pelo pedido e sua solicitação de cartão. Sem um callback funcionando, pedidos Multibanco e MB WAY nunca são confirmados, e pagamentos com cartão são confirmados somente pelo retorno assinado.

Avançado

Test Mode: Enable test/sandbox mode. Cartão de crédito 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 finalização da compra exibe um selo TEST MODE. Padrão: desligado.

Order Status After Payment: o status do pedido definido após um pagamento confirmado, com uma única mudança de status e um único e-mail ao cliente. Pedidos que contêm apenas produtos virtuais para download são sempre concluídos pelo WooCommerce.

Debug Log: Enable logging. Requisições de API e callbacks são gravadas em WooCommerce > Status > Logs, origem wcp_ifthenpay_gateway. Erros são sempre registrados. Chaves, a chave anti-phishing e números de telefone nunca são registrados. Padrão: desligado.

Delete Data on Uninstall: Remove the plugin settings, the anti-phishing key and the logs when the plugin is deleted (orders are kept). Padrão: desligado.

Finalização da compra

Multibanco. Na finalização da compra o cliente vê You will receive a Multibanco reference to complete the payment. Ao fazer o pedido, o plugin cria uma referência Multibanco dinâmica para o total do pedido. O pedido fica Em espera, o estoque é reduzido e o carrinho é esvaziado. A página de pedido recebido e os e-mails de pedido enviados enquanto o pedido está em espera exibem Multibanco Payment Details: entidade, referência e valor, com Please use these details to pay at any Multibanco ATM or through your online banking. Se o cliente fizer o pedido novamente com o mesmo valor, a mesma referência é reutilizada. O pedido é confirmado 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 de faturamento é preenchido. O plugin envia uma solicitação de pagamento ao telefone, o pedido fica Em espera, o estoque é reduzido e o carrinho é esvaziado. A página de pedido recebido informa A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. Todas as solicitações do pedido são mantidas, então uma solicitação anterior aprovada no aplicativo ainda é aceita. O pedido é confirmado pelo callback.

Cartão de crédito. O cliente vê You will be redirected to a secure page to enter your card details. e é enviado à página de cartões da ifthenpay. O pedido permanece em Pagamento pendente até ser pago, e o estoque não é reduzido antes disso. Após um pagamento bem-sucedido, o cliente retorna à sua loja. O retorno só é aceito com uma assinatura válida da ifthenpay, a chave do pedido, um segredo dessa tentativa e a solicitação de cartão do pedido; então o pedido é marcado como pago. Se o retorno não puder ser verificado, o pedido não muda, e a página de pedido recebido exibe Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. Um pagamento com cartão que falha marca o pedido como Falhou, e um cancelado o deixa em Pagamento pendente. Nos dois casos, o cliente vai à página Pay for order 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.

O pedido só é marcado como pago depois que a ifthenpay confirma o pagamento, e o valor é conferido até o centavo com o total do pedido. Se o pagamento não puder ser iniciado, o cliente vê 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 método de pagamento funciona na finalização da compra clássica, nos blocos Carrinho e Finalização de compra (com o campo de telefone do MB WAY) e na página Pay for order. É compatível com o HPOS (High-Performance Order Storage) do WooCommerce.

O plugin oferece um método ifthenpay por vez. Não oferece 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 do pagamento.

Pedidos

Status do pedido

On hold (waiting for payment): uma referência Multibanco foi emitida ou uma solicitação MB WAY foi enviada. Referências não pagas não são canceladas automaticamente; cancele você mesmo esses pedidos, se necessário.

Pending payment: um pagamento com cartão foi iniciado e ainda não foi confirmado, ou foi cancelado.

Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra a entidade e a referência Multibanco, a transação MB WAY ou o ID da solicitação do cartão.

On hold after payment: o valor recebido era diferente do total do pedido, ou o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica isso. Confira o pagamento no backoffice da ifthenpay e conclua ou reembolse o pedido manualmente.

Failed: o cliente voltou da página de cartões com um erro.

Uma segunda notificação de pagamento para um pedido já pago apenas adiciona uma nota, para verificar um possível pagamento duplicado no backoffice da ifthenpay. Pedidos reembolsados e pedidos cancelados após o pagamento nunca são reabertos.

Reembolsos

Reembolsos pelo WooCommerce não são suportados. Reembolse o pagamento no backoffice da ifthenpay e registre-o manualmente no WooCommerce. Um callback de reembolso (DEVOLVIDO) apenas adiciona uma nota ao pedido. Outros status informados pela ifthenpay também apenas adicionam uma nota.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > ifthenpay. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site 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 na finalização da compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Os gerentes da loja conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A ifthenpay não aparece na finalização da compra: 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 é EUR e se o total está entre 0,01 e 99.999,99 EUR. Na página Pay for order, vale a moeda do pedido.

O cliente pagou, mas o pedido continua On hold ou Pending payment: 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. O site precisa estar acessível pela internet, não em localhost e não atrás de um login. Procure linhas Callback rejected em WooCommerce > Status > Logs, origem wcp_ifthenpay_gateway.

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 a página de configurações uma vez; a ifthenpay tentará o callback novamente.

O callback responde Order not found: a referência ou a solicitação não pertence a um pedido deste gateway, por exemplo porque o método de pagamento foi trocado depois que o pedido foi feito.

Por que um pedido pago foi colocado em On hold? O valor recebido era diferente do total do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Leia a nota do pedido, confira o pagamento no backoffice 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.

O bloco de licença exibe um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway, a chave anti-phishing e os logs são removidos somente se Delete Data on Uninstall estiver ligado. Caso contrário, permanecem para uma reinstalação futura. Pedidos e os seus dados da ifthenpay (referências, IDs de solicitação) são sempre mantidos. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A ifthenpay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela ifthenpay.