VibeFox SimplePay 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 da loja: HUF, EUR ou USD. O SimplePay não aceita outras moedas, e o método de pagamento não é oferecido para elas.
Contas de comerciante do SimplePay: o SimplePay fornece uma conta de comerciante separada para cada moeda e contas separadas para produção e sandbox. Para cada conta, você precisa do seu MERCHANT e da sua SECRET KEY no painel de comerciante do SimplePay (admin.simplepay.hu para produção, sandbox.simplepay.hu para sandbox), conta > Dados técnicos. Se você vende apenas em HUF, a conta em HUF basta. Não são necessárias outras chaves.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_simplepay_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > SimplePay (OTP) > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira o MERCHANT e a SECRET KEY das suas contas do SimplePay para cada moeda em que você vende: contas sandbox para testes e contas de produção para pagamentos reais (veja Configuração).
6. Copie a IPN URL exibida na página de configurações para cada conta de comerciante (produção e sandbox) no painel do SimplePay.
7. Ative Enable/Disable, faça um teste de pagamento com Sandbox mode ativado e depois desmarque Sandbox mode para receber pagamentos reais.
Ao atualizar da versão 1.0, o Merchant ID e a Secret key únicos da 1.0 são transferidos para a conta da moeda da loja, no modo que estava ativo (sandbox ou produção). Confira as contas após a atualização.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > SimplePay (OTP). Acima dos campos, a página avisa quando a moeda da loja não é compatível com o SimplePay, ou quando a moeda da loja não tem conta de comerciante no modo atual. Nos dois casos, o método de pagamento não é oferecido para pedidos nessa moeda. Enquanto o modo sandbox estiver ativado, a página mostra Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged. Na lista de métodos de pagamento, o SimplePay aparece como precisando de configuração até que o modo atual tenha pelo menos uma conta de comerciante.
Geral
Enable/Disable: Enable SimplePay Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: SimplePay (Card Payment).
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit or debit card via SimplePay. Comerciantes húngaros devem exibir na finalização de compra a declaração de transferência de dados do SimplePay (Adattovábbítási nyilatkozat). Você pode colocá-la aqui, com o link.
Sandbox mode: Use the SimplePay sandbox envia os pagamentos para o sandbox do SimplePay e usa as contas sandbox. Ele troca tanto o endereço da API quanto as contas de comerciante. Nenhum dinheiro real é cobrado. Padrão: ativado. Desmarque para receber pagamentos reais com as contas de produção.
Contas de comerciante de produção
As contas usadas quando Sandbox mode está desativado. Preencha as contas das moedas em que a sua loja vende. Os valores de MERCHANT e SECRET KEY estão no painel de comerciante do SimplePay (admin.simplepay.hu), conta > Dados técnicos. Uma conta só é usada quando os dois campos estão preenchidos.
HUF account — Merchant ID: o MERCHANT da sua conta de produção em HUF.
HUF account — Secret key: a SECRET KEY da sua conta de produção em HUF.
EUR account — Merchant ID e EUR account — Secret key: o mesmo para a sua conta de produção em EUR.
USD account — Merchant ID e USD account — Secret key: o mesmo para a sua conta de produção em USD.
Contas de comerciante sandbox
As contas usadas quando Sandbox mode está ativado. Os campos são os mesmos das contas de produção: HUF account — Merchant ID, HUF account — Secret key e os mesmos pares para EUR e USD. Pegue os valores no painel de comerciante sandbox do SimplePay (sandbox.simplepay.hu), conta > Dados técnicos.
IPN URL
O IPN é a mensagem que o SimplePay envia à sua loja quando o status do pagamento muda. É a forma normal de um pedido ser marcado como pago. A página de configurações mostra a IPN URL da sua loja. Ela tem este formato: https://your-site/wc-api/simplepay_payment_callback/. Cadastre essa URL em cada conta de comerciante, de produção e sandbox, no painel do SimplePay. Se o seu site usa prefixo de idioma nas URLs ou redireciona outros endereços, copie a URL exatamente como as configurações a mostram, pois um IPN redirecionado se perde.
O IPN deve ser assinado com a SECRET KEY da conta de comerciante que ele indica. IPNs sem assinatura válida são rejeitados. O plugin confirma cada IPN válido ao SimplePay na forma assinada exigida pelo SimplePay. Estes status de IPN alteram o pedido:
Os status Falhou e Cancelado só são aplicados à última tentativa de pagamento de um pedido que ainda está Aguardando pagamento. Os demais status são registrados em log e não alteram o pedido. Sem o IPN, um pedido só é confirmado quando o cliente volta à loja após um pagamento bem-sucedido.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido imediatamente, sem uma segunda mudança de status.
Avançado
Logging: Enable logging grava chamadas à API, IPNs e retornos em WooCommerce > Status > Logs, origem wcp_simplepay_gateway. Chaves e dados dos clientes não são registrados. Erros são sempre registrados, mesmo quando a opção está desativada. Padrão: desativado.
Delete Data on Uninstall: Remove all plugin data when uninstalling. Quando ativado, excluir o plugin remove as configurações do gateway e os logs do plugin. Os dados dos pedidos são sempre mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão SimplePay (Card Payment)) e faz o pedido. O plugin inicia um pagamento com cartão do SimplePay pelo total do pedido na moeda do pedido, com a conta de comerciante dessa moeda no modo atual, e envia o cliente para a página de pagamento do SimplePay. A página mostra o que a sua conta de comerciante permite para pagamentos com cartão. O e-mail do cliente e, quando estiver completo, o endereço de cobrança são enviados ao SimplePay. A página de pagamento usa o idioma do seu site quando o SimplePay o suporta; caso contrário, usa o inglês. Um pagamento iniciado pode ser concluído em até 30 minutos.
Após um pagamento bem-sucedido, o cliente volta à página de pedido recebido da sua loja. O retorno, por si só, nunca paga um pedido: o plugin consulta ao SimplePay o status da transação com uma requisição assinada, então o pedido é confirmado mesmo que o IPN chegue atrasado. A página de pedido recebido mostra Successful transaction. SimplePay transaction ID: e o ID. Se o pagamento ainda não estiver confirmado, mostra Your payment is being confirmed by SimplePay. SimplePay transaction ID: e o ID.
Se o pagamento falhar, for cancelado ou expirar, o cliente é enviado de volta à finalização de compra ou, se o carrinho estiver vazio, à página Pay for order. Lá o cliente vê a mensagem do SimplePay com o ID da transação, por exemplo Cancelled payment. You cancelled the payment ou Timeout. The time allowed to complete the payment has expired. Em caso de falha no pagamento, o cliente é orientado a conferir os dados informados e a entrar em contato com o banco emissor do cartão. O cliente pode tentar novamente. Cada nova tentativa recebe sua própria referência do SimplePay, por exemplo 123, 123-2, 123-3.
Se o SimplePay não conseguir iniciar o pagamento, o cliente vê The SimplePay payment could not be started. Please try again or choose another payment method. Se a moeda do pedido não tiver conta de comerciante, a mensagem é SimplePay is not available for the currency of this order. Please choose another payment method. O motivo técnico é adicionado às notas do pedido e ao log. Os gerentes da loja que estiverem logados também o veem na mensagem.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita apenas pagamentos únicos com cartão, capturados na página do SimplePay. Não há cartões salvos nem pagamentos com um clique, assinaturas ou pagamentos recorrentes, e não há autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado ao SimplePay e ainda não pagou, ou o SimplePay ainda não confirmou o pagamento. A nota do pedido mostra a transação iniciada, o valor e o modo (sandbox ou produção).
Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o ID da transação e se o IPN ou a consulta de status confirmou o pagamento. O ID da transação do SimplePay é salvo como ID de transação do pedido. Um pagamento bem-sucedido atrasado também conclui um pedido que estava como Falhou ou Cancelado.
On hold: o total ou a moeda do pedido foram alterados depois que o pagamento foi iniciado, então o valor pago não corresponde ao pedido. A nota do pedido mostra os dois valores. Confira o pedido e atenda-o ou reembolse o pagamento.
Failed: o SimplePay informou que a última tentativa de pagamento não foi autorizada ou é fraude.
Cancelled: o SimplePay informou que a última tentativa de pagamento expirou ou foi cancelada.
Um pedido reembolsado ou concluído nunca é reaberto por um IPN atrasado. Se um segundo pagamento for bem-sucedido para um pedido que já está pago, o pedido não é alterado novamente. Uma nota pede que você verifique no painel do SimplePay e reembolse caso seja duplicado.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via SimplePay (OTP). Reembolsos totais e parciais são aceitos. Reembolsos em HUF devem ser em forints inteiros. O reembolso é enviado com a conta de comerciante e no modo (sandbox ou produção) em que o pagamento foi feito, então essa conta precisa continuar nas configurações. Se o SimplePay não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido, com o ID da transação de reembolso do SimplePay e o motivo, se você tiver informado um.
Reembolsos feitos no painel de comerciante do SimplePay não são sincronizados com o WooCommerce. Registre-os manualmente no WooCommerce, sem usar Refund via SimplePay (OTP).
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 > SimplePay (OTP). 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 removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta na vibefox.net.
Sem uma chave ativa, o SimplePay não é exibido aos clientes na finalização de 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 que estiverem logados 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. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
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
O SimplePay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se a moeda do pedido é HUF, EUR ou USD, e se essa moeda tem Merchant ID e Secret key no modo atual: as contas sandbox enquanto Sandbox mode estiver ativado, as contas de produção enquanto estiver desativado. A página de configurações mostra um aviso quando a moeda da loja não tem conta.
O pagamento foi feito, mas o pedido continua Aguardando pagamento: o IPN não chegou à loja. No painel de comerciante do SimplePay, confira a IPN URL da conta de comerciante que você usa (produção ou sandbox, moeda do pedido). Ela precisa ser exatamente a URL mostrada nas configurações, e o seu servidor precisa estar acessível pela internet. O pedido também é confirmado quando o cliente volta à loja depois de pagar.
O IPN responde Invalid signature: o IPN indica uma conta de comerciante que não está nas configurações, ou a Secret key está errada. Digite o MERCHANT e a SECRET KEY exatamente como o painel de comerciante do SimplePay os mostra. O SimplePay repete os IPNs não confirmados.
O IPN responde Order not found ou Unknown transaction: o IPN é de um pedido ou de uma transação que esta loja não iniciou. O pedido não é alterado.
O IPN responde Busy, retry: o pedido estava sendo confirmado por outra requisição ao mesmo tempo. O SimplePay tenta o IPN novamente.
O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou veja WooCommerce > Status > Logs, origem wcp_simplepay_gateway. Uma secret key errada gera Invalid response signature from SimplePay. Check the secret key of the merchant account. Erros do SimplePay aparecem como SimplePay error code(s): seguido dos códigos.
Depois de alternar entre sandbox e produção: novos pagamentos usam as contas do novo modo. Pedidos iniciados antes mantêm a conta de comerciante e o modo com que foram iniciados: os IPNs, consultas de status e reembolsos deles usam essa conta. Mantenha nas configurações as contas do modo antigo enquanto esses pedidos estiverem abertos ou puderem ser reembolsados.
O pedido fica On hold depois do pagamento: leia a nota do pedido. O total ou a moeda do pedido foram alterados depois que o pagamento foi iniciado. Atenda o pedido ou reembolse o pagamento.
O reembolso falha: leia a mensagem. SimplePay refunds in HUF must be whole amounts. significa que o valor em HUF tinha casas decimais. Se a mensagem disser que a conta de comerciante deste pagamento não está configurada, informe novamente a conta (moeda e modo) com que o pagamento foi feito. Se o SimplePay reembolsou um valor diferente, a mensagem pede que você confira o reembolso no painel do SimplePay.
O bloco de licença mostra 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 da 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 da licença deste plugin são sempre removidos. As configurações do gateway e os logs do plugin só são removidos se Delete Data on Uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e dados do SimplePay.
O SimplePay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo SimplePay.