VibeFox ePay.bg 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: lev búlgaro (BGN), euro (EUR) ou dólar americano (USD). O pedido é cobrado na própria moeda, com 2 casas decimais. Quando o cliente finaliza a compra em outra moeda, o método de pagamento fica oculto.
Conta ePay.bg: você precisa do número de cliente (MIN) e da chave secreta do seu perfil de comerciante no ePay.bg: os reais em www.epay.bg e os de teste em demo.epay.bg (uma conta de teste é registrada separadamente). Você também precisa informar a URL de notificação da sua loja no perfil de comerciante.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um 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_epaybg_gateway-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_epaybg_gateway.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_epaybg_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você 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 ePay.bg Gateway e clique em Install (o botão verde +). O 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 a 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 o MIN e a chave secreta de teste e/ou real (veja Configuração).
5. Copie a URL exibida na seção Payment notifications (IPN) para o campo URL for receiving notifications do perfil de comerciante do ePay.bg, tanto no perfil de demonstração quanto no real. Sem ela, nenhum pedido recebe status.
6. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste e depois desative Test Mode.
OpenCart 4
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_epaybg_gateway.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 ePay.bg Gateway, 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 credenciais do ePay.bg e a URL de notificação como nos passos 3 a 6 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 notificação é diferente (veja Notificações de pagamento (IPN)).
Uma nova instalação começa com o método de pagamento desativado e o modo de teste ativado.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > 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 exibe um erro quando a moeda padrão da loja não é BGN, EUR nem USD; um aviso quando o método de pagamento está ativado, mas o MIN ou a chave secreta do modo selecionado estão vazios (nesse caso, ele fica oculto na finalização de compra, e ao salvar aparece o mesmo aviso); e Test mode is on: payments go to demo.epay.bg and no real money is charged. enquanto o modo de teste estiver ativado. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.
Ao salvar, Title não pode ficar vazio (até 128 caracteres), Sort Order deve ser um número inteiro e Total um número igual ou maior que 0; se algum campo estiver errado, nada é salvo.
ePay.bg
Enable/Disable: Enable ePay.bg Payment 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. Ele também é o nome do método de pagamento salvo no pedido. Padrão: ePay.bg. Obrigatório.
Description: o texto exibido ao cliente na etapa Confirm Order. Padrão: Pay securely via ePay.bg with a bank card or your ePay.bg account.
Sort Order: a posição do ePay.bg entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.
Geo Zone: oferecer o ePay.bg somente 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 compra, na moeda padrão da loja, que um pedido precisa atingir para que o ePay.bg seja oferecido. Deixe em branco para oferecer o ePay.bg em qualquer valor total.
Conta ePay.bg
O número de cliente (MIN) e a chave secreta aparecem no seu perfil de comerciante em www.epay.bg (real) e demo.epay.bg (conta de teste, registrada separadamente).
Test Mode: ativa o modo de teste. Os clientes são enviados ao ambiente de demonstração do ePay.bg e as requisições são assinadas com as credenciais de teste. Padrão: ativado. Enquanto estiver ativado, os clientes veem Test mode (demo.epay.bg): no real payment is taken. na etapa Confirm Order.
Test Merchant ID (MIN): o número de cliente (MIN) da sua conta de comerciante demo.epay.bg.
Test Secret Key: a chave secreta da sua conta de comerciante demo.epay.bg (64 caracteres).
Live Merchant ID (MIN): o número de cliente (MIN) da sua conta de comerciante www.epay.bg.
Live Secret Key: a chave secreta da sua conta de comerciante www.epay.bg (64 caracteres), usada na assinatura HMAC-SHA1.
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 para alterá-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save. Espaços e quebras de linha nas chaves coladas são removidos ao salvar.
Notificações de pagamento (IPN)
A notificação informa à sua loja que uma solicitação de pagamento foi paga, recusada ou expirou. O campo Notification URL mostra a URL que você deve informar como URL for receiving notifications no perfil de comerciante do ePay.bg, tanto no real quanto no de demonstração. No OpenCart 3 ela tem a forma de https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify, e no OpenCart 4 https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify. Ela é criada a partir do endereço da vitrine da sua instalação do OpenCart. Copie a URL exatamente como as configurações a mostram. Os pedidos recebem status apenas a partir dessas notificações assinadas; o cliente que volta à loja não paga um pedido.
O ePay.bg informa estes resultados para cada fatura:
Notificações sem um checksum válido são rejeitadas, e o ePay.bg continua enviando-as. O checksum é verificado com a chave secreta de cada modo que possui uma, de modo que pagamentos iniciados antes de alternar entre teste e real continuam sendo confirmados. Um pagamento precisa chegar no modo em que a solicitação foi feita; caso contrário, o pedido passa para o status de retenção. Sem a URL de notificação no perfil de comerciante, nenhum pedido recebe status.
Solicitação de pagamento
Invoice Prefix: apenas dígitos (até 10), colocados antes do ID do pedido do OpenCart para formar o número da fatura no ePay.bg, por exemplo 00001 + 123 = 00001123. Use prefixos diferentes para lojas diferentes em uma mesma conta do ePay.bg. Os demais caracteres são removidos ao salvar, com um aviso que mostra o prefixo salvo. Alterar o prefixo depois é seguro: as solicitações de pagamento em aberto são localizadas pela fatura salva em cada uma. Padrão: 00001.
Expiration Time: o tempo após o qual uma solicitação de pagamento não paga expira; o ePay.bg então a informa como expirada e o pedido não recebe nenhum status. Escolha 1, 3, 6, 12, 24, 48 ou 72 horas. O horário é enviado no fuso horário búlgaro, independentemente do fuso horário da sua loja. Padrão: 24 horas.
Language: o idioma da página de pagamento do ePay.bg, inglês ou búlgaro. Padrão: English.
Pedidos
O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele só recebe um status quando o ePay.bg informa o pagamento. Um pagamento recusado, expirado ou abandonado deixa o pedido sem status, e o cliente pode pagar novamente. Os campos de status abaixo listam os status de pedido do seu OpenCart.
Order Status After Payment: qual status é definido após um pagamento bem-sucedido.
Processing status: o status do OpenCart para Default e Processing. Padrão: Processing.
Completed status: o status do OpenCart para Completed. Padrão: Complete.
On Hold status: o status do OpenCart para On Hold e para os pagamentos que precisam de revisão manual: o valor total ou a moeda mudou após a solicitação de pagamento, a notificação chegou no outro modo, ou o status do pedido foi alterado antes da chegada do pagamento (por exemplo, cancelado). Esse pedido não é marcado como pago; uma observação explica o motivo. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.
Avançado
Logging: grava solicitações de pagamento e notificações em epay_bp_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 epay_bp_debug.old.log.php. Chaves secretas e dados de cartão não são registrados. Padrão: desativado. Erros são sempre registrados, mesmo com esta 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, as configurações do gateway e o log são removidos. Os registros de pagamento e os pedidos do ePay.bg são sempre mantidos. 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 o 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, ePay.bg). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. O OpenCart cria o pedido nesta 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 o envia ao ePay.bg com uma solicitação de pagamento assinada pelo valor total do pedido na moeda do pedido, com o número da fatura e o prazo de expiração. O pagamento aparece no ePay.bg como Order e com o número do pedido. No ePay.bg, o cliente paga com um cartão bancário ou com uma conta do ePay.bg.
Após o pagamento, o cliente volta à sua loja. O pedido só é marcado como pago depois que o ePay.bg o confirma pela notificação assinada. Em seguida, o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque. Se a notificação já tiver chegado, o cliente vê a página de sucesso do pedido do OpenCart. Caso contrário, uma página Payment confirmation diz Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment. com os botões Check again e Back to checkout.
Se o cliente cancelar no ePay.bg, ele volta à finalização de compra com The ePay.bg payment was cancelled. You can try again or choose another payment method. Se o ePay.bg tiver informado que a solicitação foi recusada ou expirou, a mensagem é The payment was not completed. You can try again or choose another payment method. No OpenCart 4 essas mensagens são exibidas acima da página de finalização de compra. O carrinho é mantido. Uma nova tentativa para o mesmo pedido usa o mesmo número de fatura. 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 com uma nova solicitação de pagamento. Quando outro pedido do mesmo carrinho já está pago, o cliente vai para a página de sucesso e nenhum novo pagamento é iniciado.
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 pagamento (por exemplo, cancelado), o cliente volta à finalização de compra com Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., e o próximo Confirm Order paga um novo pedido do carrinho. Se o pedido já estiver pago e o carrinho tiver mudado 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 o pedido não puder ser pago com o ePay.bg, o cliente permanece na etapa Confirm Order com uma mensagem curta acima do botão, por exemplo ePay.bg payments are temporarily unavailable. Please choose another payment method. ou informando que o ePay.bg não aceita pagamentos na moeda do pedido.
A notificação também funciona enquanto a loja está em modo de manutenção, porque o OpenCart 3 deixa passar 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. As notificações de pagamentos já iniciados são aceitas mesmo que você desative o método de pagamento.
A extensão aceita somente pagamentos únicos no ePay.bg. Não há reembolsos pelo OpenCart, cartões salvos, assinaturas ou pagamentos recorrentes, nem os códigos de pagamento em dinheiro EasyPay ou B-Pay.
Pedidos
Status do pedido
No status (missing order): o cliente foi enviado ao ePay.bg e não pagou, a notificação ainda não chegou ou o ePay.bg informou que a solicitação foi recusada ou expirou. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.
Processing, Completed ou On Hold status: o pagamento foi confirmado. O status segue Order Status After Payment. Uma observação mostra o número da fatura, a data do pagamento, o STAN e o código BORICA.
Status On Hold após o pagamento: o pagamento chegou, mas não para o que o pedido indica agora: o valor total ou a moeda mudou após a solicitação de pagamento, a notificação chegou no outro modo (teste ou real) em relação à solicitação, ou o método de pagamento do pedido não é mais o ePay.bg. O pagamento não é registrado como pago. O mesmo acontece se você já tiver dado ao pedido outro status, por exemplo cancelado. A observação explica o motivo. Confira o pagamento no painel de comerciante do ePay.bg e então atenda ou reembolse o pedido manualmente.
Se chegar um pagamento para um pedido que já está pago, o status não muda, e uma observação pede que você verifique um possível pagamento em duplicidade no painel de comerciante do ePay.bg. Se o cliente tiver pago dois pedidos do mesmo carrinho, o segundo recebe uma observação sobre um possível pagamento em duplicidade. Um aviso tardio de recusa ou expiração nunca altera um pedido pago; um pedido que já tem um status recebe apenas uma observação.
As observações são entradas do History do pedido que o cliente não vê.
Aba VibeFox ePay.bg Gateway
Em Sales > Orders, abra um pedido pago com o ePay.bg. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox ePay.bg Gateway mostra a fatura, o ambiente (teste ou real) com o rótulo Test mode para os pagamentos de teste, o valor e a moeda solicitados, o estado da solicitação de pagamento, o resultado da notificação, a data do pagamento, o STAN, o código BORICA e as ePay.bg notes do pedido. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.
Reembolsos
Reembolsos pelo OpenCart não estão disponíveis, porque a API WEB do ePay.bg não tem uma chamada de reembolso. Reembolse o pagamento no painel de comerciante do ePay.bg e atualize manualmente o status do pedido no OpenCart. Devoluções de produtos em Sales > Returns não devolvem dinheiro pelo ePay.bg.
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 ePay.bg Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > 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 estão a linha Product: opencart-payment-epaybg e o link Manage licenses and domains in your account, que abre a sua conta na 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 domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, o ePay.bg 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê 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, aparece um lembrete no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: 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 administrativo: 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
O ePay.bg não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o MIN e a chave secreta do modo selecionado estão preenchidos e se o cliente finaliza a compra em BGN, EUR ou USD. A página de configurações exibe um aviso quando as credenciais estão faltando. 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.
O pagamento foi feito, mas o pedido continua sem status: o pedido só recebe o seu status a partir da notificação do ePay.bg. Verifique se a URL de notificação está informada no perfil de comerciante do ePay.bg do modo que você usa (demo ou real), exatamente como aparece em Notification URL, e se a chave secreta desse modo está correta. Veja o campo Log na página da extensão; ative Logging para ver cada notificação.
A notificação responde ERR=Not valid CHECKSUM: nenhuma chave secreta salva corresponde ao perfil de comerciante que enviou a notificação. O ePay.bg continua tentando, então o pedido receberá o seu status assim que a chave estiver correta.
A notificação responde ERR=Not configured: nenhuma chave secreta está salva. Informe-a.
A notificação responde STATUS=NO para uma fatura: a fatura não foi emitida por esta loja, por exemplo por outra loja na mesma conta do ePay.bg. Dê a cada loja o seu próprio Invoice Prefix.
A notificação responde STATUS=ERR: um erro temporário, por exemplo duas notificações para o mesmo pedido no mesmo momento, ou o status do pedido não pôde ser definido. O ePay.bg envia a notificação novamente. O motivo está no log.
A URL de notificação mostra ERR=Method not allowed in the browser: isso é normal. A URL aceita somente requisições do ePay.bg.
O cliente vê This payment method is not available. Please reload the checkout page.: a sessão da finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desativado nesse meio tempo. O cliente deve recarregar a finalização de compra.
O cliente vê This order has nothing to pay.: o total do pedido é zero, então não há nada a enviar ao ePay.bg.
O pedido está no status On Hold após o pagamento: leia as observações na aba VibeFox ePay.bg Gateway (veja Status do pedido), confira o pagamento no painel de comerciante do ePay.bg e, em seguida, atenda o pedido ou reembolse o pagamento por lá.
O prefixo da fatura foi alterado ao salvar: o prefixo pode conter apenas dígitos, até 10. Os demais caracteres são removidos.
Para desenvolvedores: antes de o formulário de pagamento ser enviado ao ePay.bg, a extensão dispara o evento do OpenCart epay_bp_form_fields com os campos do formulário e o pedido, por exemplo para usar a página direta de pagamento com cartão (PAGE=credit_paydirect); os dados assinados e o checksum não podem ser alterados por ele.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox ePay.bg Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as suas 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 valores padrão em uma reinstalação. No OpenCart 4 também são removidos o evento de mensagem do checkout da extensão e a sua ação de inicialização, que deixa a notificação passar no modo de manutenção. Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de teste, MIN e chaves secretas, solicitação de pagamento, status após o pagamento, registro) e o log são removidos. Se estiver desativado, são mantidos para uma reinstalação posterior. Os registros de pagamento do ePay.bg são sempre mantidos, de modo que um pagamento iniciado antes de uma reinstalação continua sendo confirmado. Os pedidos existentes mantêm suas observações 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 ePay.bg Gateway na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
O ePay.bg é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pelo ePay.bg.