VibeFox ePay.bg 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: lev búlgaro (BGN), euro (EUR) ou dólar americano (USD). O carrinho é cobrado na própria moeda, com 2 casas decimais. Para carrinhos em outras moedas, a forma de pagamento fica oculta na finalização de compra.

Conta ePay.bg: você precisa do número de cliente (MIN) e da chave secreta do seu perfil de comerciante da ePay.bg: os de produção em www.epay.bg e os de teste em demo.epay.bg (uma conta de teste é registrada separadamente). Também é preciso informar a URL de notificação da sua loja no perfil de comerciante.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.

2. Quando o envio terminar, clique em Configure ou, mais tarde, encontre VibeFox ePay.bg Gateway na lista de módulos e clique em Configure.

3. Informe a 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 o MIN e a chave secreta de teste e/ou de produção (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 da ePay.bg, tanto no perfil de demonstração quanto no de produção. Sem ela, nenhum pedido é criado.

6. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste e depois desative Test Mode.

Ao instalar, o módulo cria o status de pedido ePay.bg payment on hold. O PrestaShop oferece o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. Cada botão Save salva a página inteira. Acima dos campos, a página mostra um erro quando a moeda padrão da loja não é BGN, EUR ou USD; um aviso quando o gateway 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.

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway ativa ou desativa a forma de pagamento. Padrão: desativado.

Title: o nome da forma de pagamento que o cliente vê na finalização de compra. Também é o nome da forma de pagamento salvo no pedido. Padrão: ePay.bg. Obrigatório.

Description: o texto exibido abaixo da forma de pagamento na finalização de compra. Padrão: Pay securely via ePay.bg with a bank card or your ePay.bg account.

Conta ePay.bg

O número de cliente (MIN) e a chave secreta aparecem no seu perfil de comerciante em www.epay.bg (produção) 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 da ePay.bg e as solicitações são assinadas com as credenciais de teste. Padrão: ativado.

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.

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. Espaços e quebras de linha em chaves coladas são removidos ao salvar.

Clear saved secret keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Payment notifications (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 deve ser informada como URL for receiving notifications no perfil de comerciante da ePay.bg, de produção e de teste. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_epaybg_gateway/notify, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram. Os pedidos são criados somente por estas notificações assinadas; o retorno do cliente à loja não cria nem paga um pedido.

A ePay.bg informa estes resultados para cada fatura:

Notificações sem soma de verificação válida são recusadas, e a ePay.bg continua enviando-as. A soma é verificada com a chave secreta de cada modo que tenha uma, de modo que pagamentos iniciados antes de você alternar entre teste e produção continuam sendo confirmados. Um pagamento precisa chegar no modo em que a solicitação foi feita; caso contrário, o pedido vai para ePay.bg payment on hold. Sem a URL de notificação no perfil de comerciante, nenhum pedido é criado.

Payment request

Invoice Prefix: somente dígitos (até 10), colocados antes do ID do carrinho para formar o número da fatura na ePay.bg, por exemplo 00001 + 123 = 00001123. Use prefixos diferentes para lojas diferentes em uma mesma conta ePay.bg. Outros caracteres são removidos ao salvar, com um aviso. Alterar o prefixo depois é seguro: as solicitações de pagamento abertas são encontradas pela fatura salva para cada uma. Padrão: 00001.

Expiration Time: o tempo após o qual uma solicitação de pagamento não paga expira; a ePay.bg então informa que ela expirou e nenhum pedido é criado. Escolha 1, 3, 6, 12, 24, 48 ou 72 horas. O horário é enviado no horário da Bulgária, independentemente do fuso horário da sua loja. Padrão: 24 horas.

Language: o idioma da página de pagamento da ePay.bg, inglês ou búlgaro. Padrão: inglês.

Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido.

Advanced

Logging: grava as solicitações de pagamento e as notificações em logs/epay_bp_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves secretas e dados de cartão 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, desinstalar o módulo remove as configurações do gateway e o log. Os registros de pagamento da ePay.bg, o status de pedido ePay.bg payment on hold e os pedidos são sempre mantidos. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe a forma de pagamento (por padrão ePay.bg) e confirma. O cliente vê Redirecting to ePay.bg for payment... e é enviado à ePay.bg com uma solicitação de pagamento assinada pelo total do carrinho na moeda do carrinho, com o número da fatura e o tempo de expiração. O pagamento aparece na ePay.bg como Cart e com o número do carrinho. A página também tem um botão Pay via ePay.bg, caso o redirecionamento não inicie, e um botão Cancel. Na ePay.bg, o cliente paga com cartão bancário ou com uma conta ePay.bg. Neste ponto ainda não existe pedido.

Após pagar, o cliente retorna à sua loja. O pedido é criado somente quando a notificação assinada da ePay.bg chega. Se ela já tiver chegado, o cliente vê a página padrão de confirmação do pedido. Se não, uma página Payment confirmation mostra Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. com os botões Check again e Back to checkout.

Se o cliente cancelar na ePay.bg, ele volta à finalização de compra com a mensagem The ePay.bg payment was cancelled. You can try again or choose another payment method. Se a 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. O carrinho é mantido. Uma nova tentativa para o mesmo carrinho usa o mesmo número de fatura.

Se o carrinho não puder ser pago com a ePay.bg, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo ePay.bg payments are temporarily unavailable. Please choose another payment method. ou informando que a ePay.bg não aceita pagamentos na moeda do carrinho.

A notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

O módulo aceita apenas pagamentos únicos na ePay.bg. Não há reembolsos pelo PrestaShop, cartões salvos, assinaturas ou pagamentos recorrentes, nem códigos de pagamento em dinheiro EasyPay ou B-Pay.

Pedidos

Status do pedido

No order yet: o cliente foi enviado à ePay.bg e não pagou, a notificação ainda não chegou ou a ePay.bg informou que a solicitação foi recusada ou expirou. Só existe o carrinho.

Payment accepted, Delivered or ePay.bg payment on hold: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o STAN como ID da transação (ou com o número da fatura, se não houver STAN), e uma nota mostra o número da fatura, a data do pagamento, o STAN e o código BORICA.

ePay.bg payment on hold after payment: o pagamento chegou, mas não corresponde ao que o carrinho indica agora: o total ou a moeda do carrinho foi alterado depois da solicitação de pagamento, ou a notificação chegou em um modo (teste ou produção) diferente do da solicitação. O pagamento não é registrado como pago. O mesmo acontece quando o carrinho já tem um pedido não pago, por exemplo um cancelado ou um feito com outra forma de pagamento. A nota explica o motivo. Confira o pagamento no painel do comerciante da ePay.bg e então processe ou reembolse o pedido manualmente.

Se chegar um pagamento para um pedido que já está pago ou reembolsado, o status não muda e uma nota pede que você verifique um pagamento duplicado no painel do comerciante da ePay.bg. Um aviso tardio de recusa ou expiração nunca altera um pedido pago.

Bloco de pagamento da ePay.bg

A página do pedido mostra um bloco ePay.bg payment com a fatura, o valor e a moeda solicitados, o resultado da notificação, a data do pagamento, o STAN, o código BORICA, um selo Test mode para pagamentos de teste e as ePay.bg notes do pedido.

Reembolsos

Reembolsos pelo PrestaShop não estão disponíveis, pois a WEB API da ePay.bg não tem uma chamada de reembolso. Reembolse o pagamento no painel do comerciante da ePay.bg e atualize o pedido no PrestaShop manualmente.

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 ePay.bg Gateway é o primeiro bloco de Modules > Module Manager > VibeFox ePay.bg Gateway > Configure, acima das configurações. Informe 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 ficam a linha Product: presta-payment-epaybg 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 único 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, a ePay.bg 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. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a forma de pagamento também fica oculta 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. 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 novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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

A 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 a moeda do carrinho é BGN, EUR ou USD. A página de configurações mostra um aviso quando as credenciais estão faltando. 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: o pedido só é criado pela notificação da ePay.bg. Verifique se a URL de notificação está informada no perfil de comerciante da ePay.bg do modo que você usa (demo ou produção), exatamente como mostrado em Notification URL, e se a chave secreta desse modo está correta. Veja o campo Log na página do módulo; 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. A ePay.bg continua tentando, então o pedido é criado 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 ePay.bg. Atribua 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 carrinho no mesmo instante, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A 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 apenas solicitações da ePay.bg.

O pedido está em ePay.bg payment on hold após o pagamento: leia as notas no bloco ePay.bg payment (veja Status do pedido), confira o pagamento no painel do comerciante da ePay.bg e, em seguida, processe o pedido ou reembolse o pagamento por lá.

O prefixo da fatura foi alterado ao salvar: o prefixo pode conter somente dígitos, até 10. Outros caracteres são removidos.

Para desenvolvedores, o readme menciona o hook actionEpayBpFormFields (o filtro epay_bp_form_fields da versão para WooCommerce), por exemplo para usar a página de cartão direto (PAGE=credit_paydirect).

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox ePay.bg Gateway 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 gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamento da ePay.bg e o status de pedido ePay.bg payment on hold são sempre mantidos, portanto um pagamento iniciado antes de uma reinstalação continua sendo confirmado. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

ePay.bg é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela ePay.bg.