VibeFox ePayco for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 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: peso colombiano (COP) ou dólar americano (USD). Para outras moedas, o método de pagamento fica oculto na finalização de compra.
Conta ePayco: você precisa das quatro chaves da sua conta ePayco: P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY e PRIVATE_KEY. Elas estão no painel do ePayco, em Integrations, API keys. As mesmas chaves funcionam no modo de teste e no modo de produção. Os métodos de pagamento que o cliente pode usar (cartões, PSE, redes de pagamento em dinheiro, carteiras) são os habilitados na sua conta ePayco.
Site público: a URL de confirmação da sua loja precisa estar acessível pela internet, sem ser bloqueada pelo modo de manutenção, por um firewall ou pela autenticação básica.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_epayco_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > ePayco > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira as quatro chaves do ePayco e escolha o tipo de finalização de compra (veja Configuração).
6. Ative Enable/Disable. Teste um pagamento em Test Mode com os cartões de teste do ePayco e depois desmarque Test Mode.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > ePayco. Acima dos campos, a página avisa quando nem todas as quatro chaves foram inseridas (o método de pagamento fica oculto na finalização de compra), quando a moeda da loja não é COP nem USD, e mostra Test mode is on: customers pay with ePayco test cards and no real money is charged. enquanto o modo de teste estiver ativo. Na lista de métodos de pagamento, o ePayco aparece como necessitando de configuração até que as quatro chaves sejam inseridas.
Geral
Enable/Disable: Enable ePayco Payment 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: ePayco.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with ePayco.
Chaves da conta ePayco
Encontre as quatro chaves no painel do ePayco, em Integrations, API keys. P_CUST_ID_CLIENTE e P_KEY verificam as confirmações de pagamento; PUBLIC_KEY e PRIVATE_KEY criam as sessões de finalização de compra. As mesmas chaves funcionam no modo de teste e no modo de produção.
Customer ID (P_CUST_ID_CLIENTE): o seu ID de cliente do ePayco (numérico).
Secret Key (P_KEY): usada para verificar a assinatura das confirmações de pagamento do ePayco. Mantenha-a em segredo.
Public Key (PUBLIC_KEY): a sua chave pública de API do ePayco.
Private Key (PRIVATE_KEY): a sua chave privada de API do ePayco. Mantenha-a em segredo.
Test Mode: Enable test mode cria as sessões de finalização de compra como transações de teste. Os clientes pagam com os cartões de teste do ePayco, e nenhum dinheiro real é cobrado. Transações de teste nunca pagam pedidos criados no modo de produção. Padrão: desativado.
Finalização de compra
Checkout Type: como a finalização de compra do ePayco é aberta.
URL de confirmação
A URL de confirmação informa à sua loja o resultado de um pagamento. Ela é enviada ao ePayco automaticamente com cada pagamento, por isso não há nada a configurar no painel do ePayco. A seção mostra a URL, que tem este formato: https://your-site/wc-api/epc_p/. Ela precisa estar acessível pela internet, sem ser bloqueada pelo modo de manutenção, por um firewall ou pela autenticação básica.
Cada confirmação precisa trazer uma assinatura válida feita com o seu P_CUST_ID_CLIENTE e o seu P_KEY. Confirmações sem assinatura válida são rejeitadas e não alteram o pedido. Sem a confirmação, um pedido só é atualizado quando o cliente volta à loja depois de pagar.
Avançado
Logging: Enable logging registra erros da API e confirmações de pagamento em WooCommerce > Status > Logs, origem wcp_epayco_payment. Chaves e dados do cliente não são registrados. Padrão: desativado.
Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados do ePayco salvos nos pedidos são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão ePayco) e faz o pedido. O plugin cria uma sessão de finalização de compra do ePayco pelo total do pedido, na moeda do pedido, com os impostos do pedido, o número do pedido e o nome, endereço, e-mail e telefone de cobrança. O idioma da finalização de compra é espanhol ou inglês, conforme o idioma do site. Em seguida, o cliente vai para a página de pagamento do pedido, que mostra Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. A finalização de compra do ePayco abre como pop-up ou por redirecionamento, conforme Checkout Type. A página também tem o botão Pay with ePayco e o link Choose another payment method. No modo de teste, a página e a finalização de compra mostram TEST MODE — use ePayco test cards, no real money is charged.
Na finalização de compra do ePayco, o cliente paga com um dos métodos habilitados na sua conta ePayco. Depois disso, o ePayco envia a confirmação para a sua loja e devolve o cliente. O pedido só é marcado como pago depois que o ePayco confirma: pela confirmação assinada ou por uma consulta feita pelo servidor ao ePayco quando o cliente volta. O simples retorno do cliente nunca paga um pedido.
Se o pagamento ainda não estiver confirmado, a página de pedido recebido mostra We are waiting for ePayco to confirm your payment. This page does not need to stay open. Para um pagamento pendente (por exemplo PSE ou dinheiro), ela mostra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved.
Se o pagamento foi recusado, o cliente volta à página Pay for order com a mensagem Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. Se o cliente voltar sem pagar, a mensagem é The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again.
Se o ePayco não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo We could not connect to ePayco. Please try again in a moment or choose another payment method. O motivo é adicionado às notas do pedido e ao log.
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 HPOS (High-Performance Order Storage) do WooCommerce. Os textos exibidos ao cliente estão traduzidos para o espanhol.
O plugin aceita apenas pagamentos únicos. Não há reembolsos pelo WooCommerce, cartões salvos, assinaturas ou pagamentos divididos, e o plugin não consulta o ePayco sobre transações pendentes: os pedidos são atualizados pela confirmação do ePayco e pelo retorno do cliente.
Pedidos
Status do pedido
Pending payment: o cliente foi enviado ao ePayco e ainda não pagou, ou o ePayco ainda não confirmou o pagamento.
Processing: o pagamento foi aceito (pedidos com apenas produtos virtuais para download ficam Concluído, o padrão do WooCommerce). A nota do pedido mostra a referência do ePayco, o estado, o valor, o método de pagamento e o código de aprovação. O ID da transação do pedido é a referência do ePayco (ref_payco).
On hold, payment pending: o ePayco informou que o pagamento está pendente ou retido, por exemplo uma transferência PSE ou um pagamento em dinheiro. O pedido muda automaticamente quando o ePayco confirma ou rejeita o pagamento.
On hold, amount/currency mismatch: o ePayco aprovou um pagamento cujo valor ou moeda é diferente do pedido. Não envie antes de conferir a transação no painel do ePayco.
On hold, payment for a cancelled order: o ePayco aprovou um pagamento depois que o pedido foi cancelado. Restaure o pedido ou reembolse o pagamento no ePayco.
Failed: o pagamento foi recusado, falhou, expirou, foi abandonado, cancelado ou interrompido pelo antifraude. A nota mostra o motivo informado pelo ePayco. O cliente pode tentar novamente. Uma falha tardia nunca altera um pedido pago.
Refunded: o ePayco estornou o pagamento deste pedido.
Se o ePayco informar outro pagamento aprovado para um pedido que já está pago, o status não muda. Uma nota pede que você verifique uma possível cobrança duplicada e a reembolse no ePayco, se necessário. Uma transação de teste para um pedido feito no modo de produção, e uma transação que já pertence a outro pedido, são ignoradas com uma nota.
Reembolsos: reembolsos pelo WooCommerce não são suportados. Reembolse o pagamento no painel do ePayco e, em seguida, registre o reembolso no WooCommerce com Refund manually.
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 > ePayco. 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 inserir 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 do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o ePayco 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 continuam vendo o método de pagamento, marcado com (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um aviso aparece na página de Plugins e nas páginas do WooCommerce. Os 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 precisam de renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
O ePayco não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se as quatro chaves foram inseridas e se a moeda da loja é COP ou USD. Na página Pay for order, a moeda do pedido é verificada. A página de configurações mostra um aviso quando algo está faltando.
O pagamento foi feito, mas o pedido continua Pending payment: a confirmação do ePayco não chega à sua loja. Verifique se a URL de confirmação exibida nas configurações abre pela internet e não está bloqueada pelo modo de manutenção, firewall, plugin de segurança ou autenticação básica. Ative Logging e veja WooCommerce > Status > Logs, origem wcp_epayco_payment. O pedido também é atualizado quando o cliente volta à loja depois de pagar.
A confirmação responde Invalid signature: Customer ID (P_CUST_ID_CLIENTE) ou Secret Key (P_KEY) não corresponde à conta do ePayco que recebeu o pagamento. Copie os dois novamente do painel do ePayco.
A confirmação responde Gateway not configured: P_CUST_ID_CLIENTE ou P_KEY está vazio. Insira-os nas configurações.
A confirmação responde Busy, retry later: o pedido estava sendo atualizado por outra requisição no mesmo momento. O ePayco tenta a confirmação novamente.
O cliente vê We could not connect to ePayco: o ePayco recusou PUBLIC_KEY e PRIVATE_KEY. A nota do pedido mostra a resposta do ePayco. Copie as duas chaves novamente.
O cliente vê ePayco could not start the payment: o ePayco não criou a sessão de finalização de compra. Leia a nota do pedido para ver o erro do ePayco.
A finalização de compra do ePayco não abre: o cliente vê The ePayco checkout could not be loaded. Please reload the page or choose another payment method. O script da finalização de compra do ePayco não pôde ser carregado na página de pagamento do pedido. O cliente pode recarregar a página ou usar Choose another payment method.
Um pagamento de teste não pagou o pedido: transações de teste nunca pagam pedidos feitos no modo de produção. Faça o pedido de teste com Test Mode ativado.
O pedido está On hold: leia a nota do pedido. O ePayco informou o pagamento como pendente, o valor ou a moeda aprovados eram diferentes do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Verifique a transação no painel do ePayco antes de enviar.
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 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.
Para desenvolvedores, a documentação do plugin lista os filtros epc_p_supported_currencies (moedas para as quais o método de pagamento é oferecido), epc_p_session_payload (dados enviados ao ePayco) e epc_p_icon (ícone da finalização de compra).
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 e os logs são removidos somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma eventual reinstalação. Os dados do ePayco salvos nos pedidos são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
ePayco é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo ePayco.