VibeFox ePayco for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Moeda: peso colombiano (COP) ou dólar americano (USD). Para carrinhos em 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 por firewall ou autenticação básica.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 upload terminar, clique em Configure ou, depois, encontre VibeFox ePayco Payment na lista de módulos e clique em Configure.
3. Informe sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Informe as quatro chaves do ePayco e escolha o tipo de finalização de compra (veja Configuração).
5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test Mode ativado e os cartões de teste do ePayco, depois desative Test Mode.
Na instalação, o módulo cria dois status de pedido, Awaiting ePayco payment e ePayco payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-lo em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox ePayco Payment > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando não estão preenchidas as quatro chaves (o método de pagamento fica então oculto na finalização de compra) e quando a moeda padrão da sua loja não é COP nem USD, e exibe Test mode is on: customers pay with ePayco test cards and no real money is charged. enquanto o modo de teste estiver ativo.
ePayco
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. É também o nome do método de pagamento salvo no pedido. 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 de produção.
Customer ID (P_CUST_ID_CLIENTE): 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 em sigilo.
Public Key (PUBLIC_KEY): sua chave pública de API do ePayco.
Private Key (PRIVATE_KEY): sua chave privada de API do ePayco. Mantenha em sigilo.
As chaves secretas 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.
Limpar as chaves secretas salvas: marque Secret Key (P_KEY) ou Private Key (PRIVATE_KEY) e clique em Save para remover a chave. Um campo vazio mantém o valor salvo.
Test Mode: as sessões de finalização de compra são criadas como transações de teste. Os clientes pagam com 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. Enquanto estiver ativo, os clientes veem TEST MODE — use ePayco test cards, no real money is charged. abaixo do método de pagamento e na página de pagamento.
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, então não há nada a configurar no painel do ePayco. A seção mostra a URL. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_epayco_payment/confirmation, possivelmente com um código de idioma como /en/. Ela precisa estar acessível pela internet, sem ser bloqueada por firewall ou autenticação básica. Funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
Cada confirmação precisa trazer uma assinatura válida feita com seu P_CUST_ID_CLIENTE e seu P_KEY. Confirmações sem assinatura válida são rejeitadas e não alteram nada. Sem a confirmação, um pedido só é criado quando o cliente volta à loja depois de pagar.
Avançado
Logging: grava erros da API e confirmações de pagamento em logs/epc_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados de clientes não são registrados. Padrão: desativado. Erros são sempre registrados, mesmo com a opção desativada.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ativado, desinstalar o módulo remove as configurações do módulo e o log. Os dados do ePayco salvos para os pedidos e os status de pedido do módulo sempre permanecem, para que os pedidos existentes continuem funcionando. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão ePayco) e confirma. O módulo cria uma sessão de finalização de compra do ePayco pelo total do carrinho na moeda do carrinho, com os impostos, o número do carrinho e o nome de faturamento, endereço, e-mail e telefone. O pagamento aparece no ePayco como Cart # e o número do carrinho. O idioma da finalização de compra é espanhol ou inglês, conforme o idioma da loja. Nesse ponto ainda não existe pedido.
Em seguida, o cliente vê a página ePayco payment com 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 como redirecionamento, conforme Checkout Type. A página também tem o botão Pay with ePayco e o link Choose another payment method. Cada clique no botão de pagamento cria uma nova sessão do ePayco.
Na finalização de compra do ePayco, o cliente paga com um dos métodos habilitados na sua conta ePayco. Depois, 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 do servidor ao ePayco quando o cliente volta. O simples retorno do cliente nunca paga um pedido. Em seguida, o pedido é criado e o cliente vê a página padrão de confirmação do pedido.
Para um pagamento pendente (por exemplo, PSE ou dinheiro), o pedido é criado em Awaiting ePayco payment e a página de confirmação mostra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Se o pagamento pendente for recusado ou expirar depois, a página mostra Your ePayco payment was not completed. Please contact us about this order. Se o ePayco ainda não tiver confirmado o pagamento quando o cliente voltar, uma página Payment confirmation mostra We are waiting for ePayco to confirm your payment. This page does not need to stay open. e um botão Check again.
Se o pagamento foi recusado, o cliente volta à finalização de compra com 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. O carrinho é mantido e nenhum pedido é criado.
Se o ePayco não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo We could not connect to ePayco. Please try again in a moment or choose another payment method. O motivo técnico é gravado no log.
O módulo aceita apenas pagamentos únicos. Não há reembolsos pela loja, cartões salvos, assinaturas ou pagamentos divididos, e o módulo não consulta periodicamente 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
No order yet: o cliente foi enviado ao ePayco e não pagou, o ePayco ainda não confirmou o pagamento ou o pagamento foi recusado. Existe apenas o carrinho.
Payment accepted: o ePayco aprovou o pagamento. O pagamento é registrado com a referência do ePayco (ref_payco) como ID da transação, e uma nota mostra a referência, o status, o valor, o método de pagamento e o código de aprovação.
Awaiting ePayco payment: o ePayco informou o pagamento como pendente ou retido, por exemplo uma transferência PSE ou um pagamento em dinheiro. O pedido muda automaticamente quando o ePayco aprova ou rejeita o pagamento.
ePayco payment on hold: o ePayco aprovou um pagamento cujo valor ou moeda difere do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou), ou aprovou um pagamento depois que o pedido havia sido cancelado. O valor efetivamente pago é registrado no pedido quando a moeda coincide. Não envie o pedido antes de verificar a transação no painel do ePayco.
Payment error: um pagamento pendente foi recusado, falhou, expirou ou foi cancelado. A nota mostra o motivo informado pelo ePayco. Um novo pagamento aprovado para o carrinho ainda paga o pedido. 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 em duplicidade e a estorne 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.
Bloco de pagamento do ePayco
A página do pedido mostra um bloco ePayco payment com a referência do ePayco (ref_payco), o ID da transação, o status, o método de pagamento, o código de aprovação, a data da transação, um selo Test mode para pagamentos de teste e as ePayco notes do pedido. Para um pedido em ePayco payment on hold, o bloco mostra um aviso para verificar a transação antes do envio.
Reembolsos
Reembolsos pela loja não são suportados. Estorne o pagamento no painel do ePayco e, se necessário, atualize o pedido manualmente no PrestaShop. Um estorno da transação de pagamento informado pelo ePayco coloca o pedido em Refunded.
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 ePayco Payment é o primeiro bloco de Modules > Module Manager > VibeFox ePayco Payment > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois, 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: presta-payment-epayco 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 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, 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. A loja do 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 na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado automaticamente de novo enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada e, 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
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 preenchidas e se a moeda do carrinho é COP ou USD. A página de configurações mostra um aviso quando faltam chaves. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: 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 é bloqueada por firewall, módulo de segurança ou autenticação básica. Veja o campo Log na página do módulo; ative Logging para ver cada confirmação. O pedido também é criado 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. Preencha-os nas configurações.
A confirmação responde «Order not found»: a confirmação se refere a um carrinho sem pagamento do ePayco desta loja.
A confirmação responde «Busy, retry later»: o pedido estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O ePayco repete a confirmação. O motivo está no log.
O cliente vê «We could not connect to ePayco»: o ePayco recusou PUBLIC_KEY e PRIVATE_KEY. O log 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 o log 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. 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á em ePayco payment on hold: leia as notas no bloco ePayco payment (veja Status do pedido) e verifique a transação no painel do ePayco antes de enviar.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox ePayco Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete Data on Uninstall estiver ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados do ePayco salvos para os pedidos e os status de pedido Awaiting ePayco payment e ePayco payment on hold 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 módulo não é afiliado nem endossado pelo ePayco.