VibeFox ePay.bg for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo.

PHP: 8.0 ou superior.

Moeda da loja: lev búlgaro (BGN), euro (EUR) ou dólar americano (USD). O pedido é cobrado na própria moeda, com 2 casas decimais. Para outras moedas, o método de pagamento fica oculto na finalização de compra.

Conta da 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 (a 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: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_epaybg_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate. O WooCommerce precisa estar ativo.

3. Abra as configurações: WooCommerce > Settings > Payments > ePay.bg > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.

4. Informe sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Informe o MIN e a chave secreta de teste e/ou de produção (veja Configuração).

6. Copie a URL de notificação exibida na seção Payment notifications (IPN) para o campo URL for receiving notifications do perfil de comerciante da ePay.bg, tanto no perfil demo quanto no de produção. Sem ela, os pedidos permanecem em Pagamento pendente.

7. Ative Enable/Disable. Faça um pedido de teste no modo de teste e depois desmarque Test Mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > ePay.bg. Acima dos campos, a página mostra um erro quando a moeda da loja não é BGN, EUR nem USD, um aviso quando o gateway está ativado mas o MIN ou a chave secreta do modo selecionado está vazio (nesse caso ele fica oculto na finalização de compra, e ao salvar aparece o mesmo erro), e Test mode is on: payments go to demo.epay.bg and no real money is charged. enquanto o modo de teste estiver ativado. Na lista de métodos de pagamento, a ePay.bg aparece marcada como pendente de configuração até que as credenciais do modo selecionado sejam informadas.

Geral

Enable/Disable: Enable ePay.bg Payment Gateway liga ou desliga o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: ePay.bg.

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

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

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). Quando ativado, 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 em demo.epay.bg.

Test Secret Key: a chave secreta da sua conta de comerciante em demo.epay.bg (64 caracteres).

Live Merchant ID (MIN): o número de cliente (MIN) da sua conta de comerciante em www.epay.bg.

Live Secret Key: a chave secreta da sua conta de comerciante em www.epay.bg (64 caracteres), usada para a assinatura HMAC-SHA1.

Se você atualizar a partir da versão 1.0, o único conjunto de credenciais dessa versão é movido para os campos de teste quando o modo de teste estava ativado.

Notificações de pagamento (IPN)

A notificação informa à sua loja que uma solicitação de pagamento foi paga, recusada ou expirou. Esta seção mostra a URL de notificação, que tem este formato: https://your-site/wc-api/epaybg_payment_callback/. Informe-a como URL for receiving notifications no perfil de comerciante da ePay.bg, de produção e de teste. Os pedidos só são marcados como pagos por essas notificações assinadas; o retorno do cliente à loja não marca um pedido como pago.

A ePay.bg informa estes resultados para cada fatura:

Cada notificação é verificada com a chave secreta do modo selecionado. Notificações sem uma soma de verificação válida são rejeitadas, e a ePay.bg continua a enviá-las. Sem a URL de notificação no perfil de comerciante, nenhum pedido é marcado como pago.

Solicitação de pagamento

Invoice Prefix: somente dígitos (até 10), colocados antes do ID do pedido para formar o número da fatura da ePay.bg, por exemplo 00001 + 123 = 00001123. Use prefixos diferentes para lojas diferentes em uma mesma conta da ePay.bg. Os demais caracteres são removidos ao salvar. Alterar o prefixo depois é seguro: os pedidos pendentes são encontrados pela fatura salva no pedido. 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 a informa como expirada e o pedido pendente é cancelado. Escolha 1, 3, 6, 12, 24, 48 ou 72 horas. O horário é enviado no horário da Bulgária, seja qual for o fuso horário do seu site. 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. O status é definido imediatamente, sem uma segunda mudança de status.

Avançado

Logging: Enable logging grava as solicitações de pagamento e as notificações em WooCommerce > Status > Logs, origem wcp_epaybg_gateway, sem chaves secretas nem dados de cartão. Padrão: desativado.

Delete Data on Uninstall: Remove all plugin data when uninstalled. Se marcada, as configurações do gateway, os dados da ePay.bg salvos nos pedidos e os logs do plugin são excluídos quando o plugin é desinstalado. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão, ePay.bg) e faz o pedido. O cliente vê Redirecting to ePay.bg for payment... e é enviado para a ePay.bg com uma solicitação de pagamento assinada pelo total do pedido na moeda do pedido, com o número da fatura e o tempo de expiração. A página também tem um botão Pay via ePay.bg, caso o redirecionamento não comece, e um botão Cancel order. Na ePay.bg, o cliente paga com um cartão bancário ou com uma conta ePay.bg.

Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago quando chega a notificação assinada da ePay.bg. O carrinho só é esvaziado na página de pedido recebido.

Se o cliente cancelar na ePay.bg, o pedido é cancelado da forma padrão do WooCommerce e o carrinho é mantido, para que o cliente possa escolher outro método de pagamento.

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

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. Ele é compatível com o armazenamento de pedidos de alto desempenho (HPOS) do WooCommerce.

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

Pedidos

Status dos pedidos

Pending payment: o cliente foi enviado para a ePay.bg e ainda não pagou, ou a notificação ainda não chegou. A nota do pedido diz Awaiting ePay.bg payment.

Processing, Completed or On Hold: o pagamento foi confirmado. O status segue a opção Order Status After Payment. A nota do pedido mostra o número da fatura, a data do pagamento, o STAN e o código BORICA. O ID da transação é o STAN (ou o número da fatura, se não houver STAN).

On hold after payment: o pagamento chegou, mas não para o que o pedido informa agora: o total ou a moeda foi alterado depois da solicitação de pagamento, a solicitação foi feita no outro modo ou o gateway foi alternado depois entre teste e produção, o método de pagamento do pedido foi alterado, ou o pedido havia sido cancelado antes. A nota do pedido explica o motivo. Confira o pagamento no painel do comerciante da ePay.bg e conclua ou reembolse o pedido manualmente.

Cancelled: a ePay.bg informou a solicitação de pagamento como recusada ou expirada, ou o cliente cancelou na ePay.bg. O WooCommerce restaura o estoque. Um pedido cancelado não pode ser pago novamente, porque o número da fatura da ePay.bg é o prefixo mais o ID do pedido. O cliente faz um novo pedido.

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

Reembolsos

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

Chave de licença

O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > ePay.bg. 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga de domínio dele. Libere a vaga na sua conta em 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. Gerentes da loja conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete 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 exigem renovação. O status é verificado novamente de forma automática em segundo plano.

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á ligado, se o MIN e a chave secreta do modo selecionado estão preenchidos e se a moeda da loja é BGN, EUR ou USD. A página de configurações mostra um aviso em cada um desses casos.

O pagamento foi concluído, mas o pedido continua em Pagamento pendente: o pedido só é marcado como pago 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) e se a chave secreta do modo ativo está correta. Ative Logging e consulte WooCommerce > Status > Logs, origem wcp_epaybg_gateway.

A notificação responde ERR=Not valid CHECKSUM: a chave secreta nas configurações não corresponde ao perfil de comerciante que enviou a notificação. As notificações são verificadas com a chave do modo selecionado no momento e depois com a chave do outro modo, de modo que solicitações de pagamento feitas antes de você trocar de modo ainda são aceitas. A ePay.bg continua tentando, então o pedido é atualizado assim que a chave estiver correta.

A notificação responde ERR=Not configured: a chave secreta do modo selecionado está vazia. Informe-a.

A notificação responde STATUS=NO para uma fatura: a fatura não pertence a um pedido da ePay.bg desta loja, por exemplo porque foi emitida por outra loja na mesma conta da 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 do mesmo pedido no mesmo momento. A ePay.bg envia a notificação novamente.

O pedido está em Aguardando após o pagamento: leia a nota do pedido. O total ou a moeda mudou depois da solicitação de pagamento, a solicitação foi feita no outro modo ou o modo foi alternado depois, o método de pagamento mudou ou o pedido havia sido cancelado. Confira o pagamento no painel do comerciante da ePay.bg.

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

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 em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o 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, o readme menciona o filtro epay_bp_form_fields, por exemplo para usar a página direta de cartão (PAGE=credit_paydirect).

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua o plugin na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway, os dados da ePay.bg salvos nos pedidos e os logs só são removidos se Delete Data on Uninstall estava ativado. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

ePay.bg é uma marca registrada do respectivo proprietário. Este plugin não é afiliado nem endossado pela ePay.bg.