VibeFox ePayco for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Moeda: peso colombiano (COP) ou dólar americano (USD). Quando o cliente paga em outra moeda, 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 da 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 digitais) 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 único 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 para OpenCart 3 wcp_epayco_payment-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_epayco_payment.ocmod.zip. Instale apenas 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 administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_epayco_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, portanto 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. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox ePayco Payment e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole 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. Informe as quatro chaves da ePayco e escolha o tipo de checkout (veja Configuração).

5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test Mode ativado e com os cartões de teste da ePayco e, depois, desative Test Mode.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_epayco_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox ePayco Payment, 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, as chaves da ePayco e as configurações como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Somente a URL de confirmação é diferente (veja URL de confirmação).

Uma nova instalação começa com o método de pagamento desativado e o modo de teste desativado. A URL de confirmação é enviada à ePayco em cada pagamento, portanto nada precisa ser configurado no painel da ePayco.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página explica que o pedido só recebe um status depois que a ePayco confirma a transação. Ela 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 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. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter no máximo 128 caracteres, Sort Order deve ser um número inteiro, Total deve ser um número não negativo, e a zona geográfica e os status de pedido precisam existir. Caso contrário, um erro indica o campo e nada é salvo.

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. Ele também é o nome do método de pagamento salvo no pedido. Até 128 caracteres; se ficar vazio, o cliente verá ePayco. Padrão: ePayco.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely with ePayco.

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

Geo Zone: oferece a ePayco apenas 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 deve atingir para que a ePayco seja oferecida. Deixe vazio para oferecer a ePayco em qualquer valor.

Chaves da conta ePayco

Encontre as quatro chaves no painel da ePayco, em Integrations, API keys (a seção tem um link para o painel). P_CUST_ID_CLIENTE e P_KEY verificam as confirmações de pagamento; PUBLIC_KEY e PRIVATE_KEY criam as sessões de checkout. As mesmas chaves funcionam no modo de teste e no modo de produção.

Customer ID (P_CUST_ID_CLIENTE): seu ID de cliente da ePayco (numérico).

Secret Key (P_KEY): usada para verificar a assinatura das confirmações de pagamento da ePayco. Mantenha em sigilo.

Public Key (PUBLIC_KEY): sua chave pública de API da ePayco.

Private Key (PRIVATE_KEY): sua chave privada de API da ePayco. Mantenha em sigilo.

As chaves salvas Secret Key (P_KEY) e Private Key (PRIVATE_KEY) nunca mais são exibidas. O campo permanece 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 saved secret on save abaixo do campo e clique em Save.

Test Mode: as sessões de checkout são criadas como transações de teste. Os clientes pagam com os cartões de teste da ePayco e nenhum valor real é cobrado. As 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. na etapa Confirm Order e na página de pagamento.

Finalização de compra

Checkout Type: como o checkout da ePayco é aberto.

URL de confirmação

A URL de confirmação informa à sua loja o resultado de um pagamento. Ela é enviada automaticamente à ePayco com cada pagamento, portanto não há nada para configurar no painel da ePayco. A seção mostra a URL. No OpenCart 3 ela tem a forma https://your-store/index.php?route=extension/payment/wcp_epayco_payment/confirmation, e no OpenCart 4 https://your-store/index.php?route=extension/wcp_epayco_payment/payment/wcp_epayco_payment.confirmation. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Precisa estar acessível pela internet, sem ser bloqueada por firewall ou autenticação básica. Ela também funciona enquanto a loja está em modo de manutenção, porque o OpenCart 3 libera as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup action) para isso.

Cada confirmação precisa ter 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 nada. Sem a confirmação, um pedido só recebe o seu status quando o cliente volta à loja depois de pagar.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a ePayco confirma a transação. Um pagamento recusado ou abandonado deixa o pedido sem status, e o carrinho é mantido. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: a ePayco aprovou o pagamento, e o valor e a moeda conferem com o pedido. Padrão: Processando.

Awaiting Payment Status: a ePayco informou o pagamento como pendente ou retido (transferência PSE, redes de pagamento em dinheiro). O pedido muda automaticamente quando a ePayco aprova ou rejeita. Padrão: Pendente.

On Hold (Review) Status: a ePayco aprovou um pagamento cujo valor ou moeda difere do pedido, ou o aprovou depois que o pedido recebeu outro status (por exemplo, Cancelado). Uma nota explica o motivo. Não envie antes de conferir a transação no painel da ePayco. Padrão: Pendente, pois o OpenCart não tem o status Em espera. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Payment Failed Status: um pagamento pendente foi rejeitado, falhou, expirou ou foi cancelado. Um novo pagamento aprovado ainda paga o pedido. Padrão: Falhou.

Reversed Status: a ePayco estornou o pagamento do pedido. Padrão: Reembolsado.

Avançado

Logging: grava erros da API e confirmações de pagamento em epc_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para epc_p_debug.old.log.php. Chaves e dados dos clientes não são registrados. Padrão: desativado. Os erros são sempre registrados, mesmo com a opção desativada.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete Data on Uninstall: quando ativado, ao desinstalar a extensão são removidas as configurações da extensão e o log. Os dados da ePayco salvos para os pedidos sempre permanecem. Padrão: desativado.

Importar / Exportar

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

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

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, ePayco). Na etapa Confirm Order, o cliente vê a sua descrição e a nota After confirming the order you pay securely in the ePayco checkout (cards, PSE, cash, wallets). 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, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão cria uma sessão de checkout da ePayco para o total do pedido na moeda do pedido, com os impostos, o número do pedido e o nome, endereço, e-mail e telefone de cobrança. O pagamento aparece na ePayco como Order # e o número do pedido. O idioma do checkout é espanhol ou inglês, conforme o idioma da loja do cliente.

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. O checkout da 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 novo Confirm Order cria uma nova sessão da ePayco (o OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 atualiza o pedido da finalização de compra, então uma nova tentativa paga o mesmo pedido). Se um pedido anterior do mesmo carrinho já estiver pago ou aguardando a ePayco, o cliente é levado à página de sucesso do pedido e não é cobrado novamente.

No checkout da ePayco, o cliente paga com um dos métodos habilitados na sua conta ePayco. Depois, a ePayco envia a confirmação para a sua loja e devolve o cliente. O pedido só é marcado como pago depois que a ePayco o confirma: pela confirmação assinada ou por uma requisição do servidor à ePayco quando o cliente retorna. O simples retorno do cliente nunca paga um pedido. Depois, o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização de estoque, e o cliente vê a página de sucesso do pedido do OpenCart.

Para um pagamento pendente (por exemplo, PSE ou dinheiro), o pedido recebe Awaiting Payment Status e a página de sucesso mostra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Se o pagamento pendente já tiver sido rejeitado ou expirado quando o cliente retornar, a página mostra Your ePayco payment was not completed. Please contact us about this order. Se a ePayco ainda não tiver confirmado o pagamento quando o cliente retornar, uma página Payment confirmation mostra We are waiting for ePayco to confirm your payment. This page does not need to stay open. e o 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 ter pago, 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 o pedido permanece sem status. No OpenCart 4 essas mensagens são exibidas acima da página de finalização de compra.

O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se, nesse meio tempo, esse pedido tiver sido encerrado sem um pagamento da ePayco (por exemplo, o pagamento pendente falhou ou você o cancelou), o cliente volta à finalização de compra com a mensagem sobre o pagamento recusado, e o próximo Confirm Order paga um novo pedido do carrinho. Se o pedido já tiver um status, mas o carrinho mudou desde então, inclusive com uma nova quantidade, o cliente volta à finalização de compra, e o próximo Confirm Order paga o novo carrinho com um novo pedido. Um pedido pago nunca é mostrado como pago para um carrinho diferente.

Se a ePayco não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, 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.

A extensão aceita apenas pagamentos únicos. Não há reembolsos pela loja, cartões salvos, assinaturas ou pagamentos divididos, e ela não consulta a ePayco sobre transações pendentes: os pedidos são atualizados pela confirmação da ePayco e pelo retorno do cliente.

Pedidos

Status do pedido

No status (missing order): o cliente foi enviado à ePayco e não pagou, a ePayco ainda não confirmou o pagamento, ou o pagamento foi recusado. Em Sales > Orders, esses pedidos aparecem apenas com o filtro Order Status definido como Missing Orders.

Order Status After Payment (default Processing): a ePayco aprovou o pagamento. Uma nota mostra a referência da ePayco, o estado, o valor, o método de pagamento e o código de aprovação.

Awaiting Payment Status (default Pending): a ePayco informou o pagamento como pendente ou retido, por exemplo uma transferência PSE ou um pagamento em dinheiro. Quando a ePayco o aprova, o pedido passa para Order Status After Payment; quando é rejeitado, falha, expira ou é cancelado, o pedido passa para Payment Failed Status. O OpenCart envia um e-mail ao cliente sobre essas mudanças.

On Hold (Review) Status (default Pending): a ePayco aprovou um pagamento com valor ou moeda diferentes do pedido, ou aprovou um pagamento depois que você deu ao pedido outro status (por exemplo, Cancelado). A nota explica isso. Confira a transação no painel da ePayco antes de enviar.

Payment Failed Status (default Failed): um pagamento pendente não foi concluído. A nota mostra o motivo informado pela ePayco. Um novo pagamento aprovado ainda paga o pedido. Uma falha tardia nunca altera um pedido pago.

Reversed Status (default Refunded): a ePayco estornou o pagamento que quitou este pedido.

Se a ePayco informar outro pagamento aprovado para um pedido que já está pago, o status não muda. Uma nota pede que você verifique se houve cobrança duplicada e a estorne na ePayco, se necessário. Se o cliente pagar um segundo pedido do mesmo carrinho (por exemplo, a partir de duas janelas da ePayco abertas), esse pedido não recebe status, o cliente vê a página de sucesso do pedido, e o pedido pago recebe uma nota pedindo que você estorne o segundo pagamento na ePayco. Uma transação de teste de um pedido feito no modo de produção, e uma transação que já pertence a outro pedido, são ignoradas. As notas são registros do History do pedido que o cliente não vê.

Aba VibeFox ePayco Payment

Em Sales > Orders, abra um pedido pago com a ePayco. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox ePayco Payment mostra a ePayco reference (ref_payco), o Transaction ID, o State, o Payment method, o Approval code, a Transaction date, o Mode (com o rótulo Test mode nos pagamentos de teste), o Attempt status e as ePayco notes do pedido. Para um pedido em revisão, a aba mostra um aviso para conferir a transação antes do envio. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos pela loja não são suportados. Reembolse o pagamento no painel da ePayco e, se necessário, atualize o pedido manualmente no OpenCart. Um estorno da transação de pagamento informado pela ePayco define o pedido como Reversed Status. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela ePayco.

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 ePayco Payment é o primeiro bloco em Extensions > Extensions > Payments > VibeFox ePayco Payment > 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 aparecem a linha Product: opencart-payment-epayco 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 painel administrativo (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 único domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a ePayco não é exibida 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. Um usuário administrador conectado ao painel no mesmo navegador continua vendo 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é-visualização não está disponível: a loja não vê o login do painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente de forma automática 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, e depois uma vez por semana. Nenhum cron job é necessário. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

ePayco does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado, se as quatro chaves foram informadas e se o cliente paga em COP ou USD. A página de configurações mostra um aviso quando faltam chaves. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

The payment went through, but the order stays without a status: a confirmação da ePayco não chega à sua loja. Verifique se a URL de confirmação mostrada nas configurações abre pela internet e não é bloqueada por firewall, extensão de segurança ou autenticação básica. Veja o campo Log na página da extensão; ative Logging para ver cada confirmação. O pedido também recebe o seu status quando o cliente volta à loja depois de pagar.

Confirmation answers Invalid signature: Customer ID (P_CUST_ID_CLIENTE) ou Secret Key (P_KEY) não corresponde à conta da ePayco que recebeu o pagamento. Copie os dois novamente do painel da ePayco.

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE ou P_KEY está vazio. Informe-os nas configurações.

Confirmation answers Order not found: a confirmação se refere a um pedido sem um pagamento da ePayco desta loja.

Confirmation answers Busy, retry later: o pedido estava sendo atualizado por outra requisição no mesmo momento. A ePayco tenta a confirmação novamente. O motivo está no log.

The customer sees We could not connect to ePayco: a ePayco recusou PUBLIC_KEY e PRIVATE_KEY. O log mostra a resposta da ePayco. Copie as duas chaves novamente.

The customer sees ePayco could not start the payment: a ePayco não criou a sessão de checkout. Leia no log o erro da ePayco.

The customer sees This payment method is not available right now: a sessão de checkout não corresponde mais ao pedido, o método de pagamento foi desativado nesse meio tempo ou as chaves foram removidas. O cliente recarrega a finalização de compra.

The ePayco checkout does not open: o cliente vê The ePayco checkout could not be loaded. Please reload the page or choose another payment method. O script do checkout da 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.

A test payment did not pay the order: transações de teste nunca pagam pedidos feitos no modo de produção. Faça o pedido de teste enquanto Test Mode estiver ativo.

Order is in the review status after payment: leia as notas na aba VibeFox ePayco Payment (veja Status do pedido) e confira a transação no painel da ePayco antes do envio.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox ePayco Payment. 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 padrões em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, seus eventos e a sua ação de inicialização, que deixa a confirmação e o retorno do cliente passarem no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações de pagamento (título, descrição, chaves, modo de teste, tipo de checkout, log) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os dados da ePayco salvos para os pedidos sempre são mantidos, de modo que confirmações tardias de pedidos antigos continuam funcionando 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, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox ePayco Payment na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A ePayco é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela ePayco.