VibeFox ECPay for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Moeda: novo dólar taiwanês (TWD). A ECPay cobra apenas em TWD, por isso o método de pagamento só é exibido quando o carrinho do cliente está em TWD. Adicione TWD em International > Localization > Currencies se a sua loja não a tiver. Os valores são enviados em TWD inteiros, porque a ECPay não aceita casas decimais: os totais do carrinho são arredondados para o dólar mais próximo. Use 0 casas decimais nos preços em TWD para evitar arredondamentos.
Conta ECPay: para pagamentos reais, você precisa do MerchantID, do HashKey e do HashIV da sua conta de comerciante ECPay, disponíveis no back-office de comerciante da ECPay (vendor.ecpay.com.tw). Para testes, não é necessária uma conta ECPay.
Acesso ao site: a sua loja precisa estar acessível pela internet via HTTP/HTTPS na porta 80/443, para que a ECPay possa enviar as notificações de pagamento. Um firewall ou a autenticação básica na frente do site as bloqueia.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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, depois, encontre VibeFox ECPay Payment Gateway na lista de módulos e clique em Configure.
3. Insira 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. Ative Enable/Disable, escolha os métodos de pagamento e mantenha Test Mode ligado para os primeiros testes. Clique em Save.
5. Para pagamentos reais, informe o Merchant ID, o Hash Key e o Hash IV (veja Configuração), desative Test Mode e clique em Save.
Na instalação, o módulo cria dois status de pedido: Awaiting ECPay payment e ECPay payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; o TWD precisa continuar permitido para o módulo.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra um erro quando a sua loja não tem a moeda TWD (nesse caso a ECPay não aparece na finalização de compra) ou um aviso quando a moeda padrão não é TWD (nesse caso a ECPay só é exibida para clientes que pagam em TWD). Ela mostra um erro quando o modo real não tem MerchantID, HashKey e HashIV. Enquanto o modo de teste estiver ligado, ela avisa que os pagamentos vão para o sandbox da ECPay com o comerciante de teste público 3002607, que nenhum dinheiro é cobrado e que qualquer pessoa que conheça as chaves públicas do sandbox poderia confirmar pedidos de teste, por isso o modo de teste deve estar desativado antes de você aceitar pedidos reais.
ECPay (綠界)
Enable/Disable: Enable ECPay Payment liga ou desliga o método de pagamento. Padrão: desligado.
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: ECPay (綠界). Obrigatório: a página não é salva com o título vazio.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
Conta ECPay
Encontre o seu MerchantID, HashKey e HashIV no back-office de comerciante da ECPay (vendor.ecpay.com.tw), em System development management > System integration settings (系統開發管理 > 系統介接設定).
Test Mode: envia os pagamentos para o sandbox da ECPay (payment-stage.ecpay.com.tw) com o comerciante de teste público da ECPay 3002607. Nenhum dinheiro real. As credenciais abaixo são usadas somente quando o modo de teste está desativado. Padrão: ligado. Enquanto estiver ligado, os clientes veem TEST MODE — ECPay sandbox, no real money is charged. abaixo do método de pagamento.
Merchant ID: o seu Merchant ID da ECPay (produção). Ignorado no modo de teste.
Hash Key: o seu Hash Key da ECPay (produção). Ignorado no modo de teste.
Hash IV: o seu Hash IV da ECPay (produção). Ignorado no modo de teste.
Espaços e quebras de linha nas credenciais coladas quebram todas as assinaturas, por isso eles são removidos ao salvar, e a página informa isso. Um Hash Key e um Hash IV salvos nunca são exibidos novamente: o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente para alterá-lo.
Clear saved secrets: marque Hash Key ou Hash IV e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Opções de pagamento
Enabled Payment Methods: os métodos oferecidos aos clientes. Com mais de um, o cliente escolhe na finalização de compra. Os pedidos ATM, CVS e código de barras permanecem em Awaiting ECPay payment até o cliente pagar. Pelo menos um método deve estar selecionado; se nenhum estiver, Credit Card é ativado e a página informa isso. Padrão: Credit Card.
Default Payment Method: o método pré-selecionado. Ele precisa ser um dos métodos ativados; caso contrário, é usado o primeiro método ativado. Padrão: Credit Card.
Order Prefix: o prefixo do número de transação da ECPay (MerchantTradeNo), com até 5 letras ou dígitos. Os outros caracteres são removidos ao salvar, com uma mensagem. Útil quando várias lojas compartilham uma conta ECPay: dê a cada loja o seu próprio prefixo. Padrão: EC.
Notificações de pagamento
A ECPay envia os resultados dos pagamentos para a sua loja. Esta seção mostra a Notification URL. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_ecpay_payment_gateway/notify, possivelmente com um código de idioma como /en/. A URL é enviada com cada pagamento, então nada precisa ser configurado na ECPay, mas ela deve ser acessível pela internet na porta 80/443, sem firewall ou autenticação básica na frente. O modo de manutenção e a restrição por país da sua loja não a bloqueiam.
Cada notificação é verificada pela sua assinatura CheckMacValue com as chaves do ambiente (teste ou real) em que o pagamento foi iniciado, e pelo MerchantID desse pagamento. Notificações sem assinatura válida são rejeitadas, e a ECPay as envia novamente. Sem a notificação, nenhum pedido é criado; verifique o pagamento no back-office da ECPay.
Avançado
Enable Logging: grava IDs de pedido, números de transação, valores e códigos de retorno da ECPay em logs/ecpay_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Nenhuma chave ou dado do cliente é registrado. Erros são sempre registrados, mesmo quando esta opção está desligada. Padrão: desligado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ligado, desinstalar o módulo remove as suas configurações e o log. Os registros de pagamento da ECPay e os status de pedido são sempre mantidos, para que os pedidos existentes continuem funcionando após uma reinstalação. Padrão: desligado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, ECPay (綠界)). Com vários métodos ativados, o cliente também escolhe Credit Card, ATM (Virtual Account), CVS (Convenience Store) ou Barcode em Payment Method.
Após confirmar, o cliente vê Redirecting to ECPay for payment. Please wait... e é enviado para a página de pagamento da ECPay, com um botão Proceed to ECPay caso o redirecionamento não comece. O total do carrinho é enviado em TWD inteiros, com os nomes e as quantidades dos produtos. A página da ECPay abre em chinês tradicional para os idiomas taiwanês e de Hong Kong, em chinês simplificado, coreano ou japonês para esses idiomas, e em inglês para todos os outros, seguindo o idioma da loja do cliente. Neste ponto ainda não existe pedido.
O pedido só é criado depois que a ECPay o confirma com uma notificação assinada do servidor. Quando o cliente clica no link de volta à loja na página da ECPay e o pedido já existe, abre-se a página padrão de confirmação do pedido. Ela mostra Your ECPay payment has been received. para um pedido pago, Your ECPay payment was received and is being reviewed by the store. para um pedido em espera e as instruções de pagamento para um pedido ATM, CVS ou de código de barras aguardando pagamento. Se a notificação ainda não chegou, uma página de Payment confirmation mostra We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. com os botões Check again e Back to checkout. Se a ECPay informou que o pagamento falhou, o cliente volta à finalização de compra com The payment was not completed. You can try again or choose another payment method. O carrinho é mantido.
Para ATM, CVS e código de barras, o cliente recebe primeiro os dados de pagamento. O pedido é criado em Awaiting ECPay payment, e o código do banco e a conta virtual, o código de pagamento da loja de conveniência ou os códigos de barras, o valor e a data Pay before são exibidos em ECPay payment instructions na página de confirmação do pedido e nos detalhes do pedido do cliente. Quando o cliente paga, a ECPay envia outra notificação e o pedido é marcado como pago. As instruções de pagamento não são incluídas nos e-mails do PrestaShop.
Cada tentativa cria um novo número de transação ECPay, porque a ECPay rejeita números reutilizados. Assim, novas tentativas após um pagamento com falha funcionam, e se o cliente voltar no navegador para a página de redirecionamento, uma nova tentativa é iniciada. Um carrinho pode ter até 30 tentativas de pagamento. Depois que o carrinho tem um pedido, ele não pode mais ser pago pela finalização de compra; um pedido ATM ou CVS aguardando pagamento é quitado com os dados já emitidos.
Se o pagamento não puder ser iniciado, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo The order total is too small for ECPay. quando o total fica abaixo de 1 TWD após o arredondamento. Os limites de valor próprios da ECPay por método são verificados na página da ECPay, não na finalização de compra.
O módulo aceita pagamentos únicos apenas na página da ECPay. Não há reembolsos pelo PrestaShop, cartões salvos, assinaturas ou pagamentos periódicos (定期定額), parcelamento, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, notas fiscais eletrônicas ou logística, e não há consulta de status no servidor: se a sua loja não puder receber a notificação, verifique o pagamento no back-office da ECPay.
Pedidos
Status do pedido
No order yet: o cliente foi enviado para a ECPay e ainda não pagou, ou a notificação ainda não chegou. Existe apenas o carrinho.
Awaiting ECPay payment: o cliente escolheu ATM, CVS ou código de barras e recebeu os dados de pagamento. A nota mostra o código do banco e a conta virtual, o código de pagamento ou os códigos de barras e o prazo.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o TradeNo da ECPay como ID da transação, e uma nota mostra o TradeNo, o tipo de pagamento, o valor e o número da transação (com uma marca de modo de teste para pagamentos sandbox).
ECPay payment on hold: a ECPay informou um valor ou uma moeda diferentes do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou), um pagamento sandbox chegou depois que você mudou para o modo real (nenhum dinheiro real foi cobrado), ou o pagamento chegou depois que o pedido havia sido cancelado (nesse caso, o pagamento é registrado). A nota explica o caso. Compare com o back-office da ECPay e então processe o pedido ou reembolse o pagamento por lá.
Payment error: a ECPay informou que o último pagamento ATM, CVS ou de código de barras de um pedido aguardando pagamento falhou. A nota mostra o código de retorno e a mensagem da ECPay.
Notificações repetidas são ignoradas. Um pedido pago, reembolsado ou cancelado nunca é reaberto por uma falha tardia. Um segundo pagamento para um pedido que já está pago, por exemplo a partir de duas abas do navegador, é anotado uma única vez como nota, para que você possa reembolsá-lo no back-office da ECPay. Pagamentos simulados iniciados no back-office da ECPay são apenas anotados e nunca marcam um pedido como pago, porque a ECPay não cobra dinheiro por eles.
Bloco de pagamento da ECPay
A página do pedido mostra um bloco ECPay payment com cada tentativa de pagamento do pedido: o MerchantTradeNo com um selo Test mode para tentativas sandbox, o método, o valor em TWD, o status, o TradeNo da ECPay, o tipo de pagamento e a data, além do código de retorno da ECPay. Abaixo ficam as ECPay notes do pedido. Para um pedido em ECPay payment on hold, o bloco lembra você de compará-lo com o back-office da ECPay.
Reembolsos
Reembolsos pelo PrestaShop não estão disponíveis. Reembolse o pagamento no back-office da ECPay e depois atualize o pedido manualmente no PrestaShop. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela ECPay.
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 ECPay Payment Gateway é o primeiro bloco de Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: presta-payment-ecpay 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, a ECPay 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 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 novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, 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 ECPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o carrinho do cliente está em TWD e, no modo real, se Merchant ID, Hash Key e Hash IV estão preenchidos. A página de configurações mostra uma mensagem em cada um desses casos. Em Payment > Preferences, verifique se o módulo está permitido para TWD, para o país do cliente e para o grupo do cliente.
O pagamento foi concluído, mas nenhum pedido foi criado: a notificação da ECPay não chegou à sua loja (site fora do ar, firewall, autenticação básica). A ECPay tenta novamente várias vezes. Você também pode verificar a transação no back-office da ECPay. Ligue Enable Logging para ver as notificações recebidas pelo módulo; notificações rejeitadas são registradas como erros de qualquer forma.
A notificação responde 0|CheckMacValue verification failed: o Hash Key ou o Hash IV não correspondem à sua conta ECPay, ou o pagamento foi iniciado no outro ambiente. Copie-os novamente do back-office da ECPay.
A notificação responde 0|MerchantID mismatch: a notificação pertence a outro comerciante da ECPay diferente daquele com o qual o pagamento foi iniciado.
A notificação responde 0|Order not found: o número de transação não foi emitido por esta loja, por exemplo quando várias lojas compartilham uma conta ECPay. Dê a cada loja o seu próprio Order Prefix.
A notificação responde 0|Retry: o carrinho estava sendo processado por outra notificação no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A ECPay envia a notificação novamente. Ligue Enable Logging para ver o motivo.
A URL de notificação mostra 0|Method not allowed in the browser: isso é normal. A URL aceita apenas requisições da ECPay.
O cliente vê «The order total is too small for ECPay.»: o total do carrinho fica abaixo de 1 TWD após o arredondamento e não pode ser pago com a ECPay.
O cliente vê «Too many payment attempts for this order»: o carrinho atingiu 30 tentativas de pagamento. Peça ao cliente que inicie um novo carrinho.
O pedido está em ECPay payment on hold: leia as notas no bloco ECPay payment (veja Status do pedido), compare com o back-office da ECPay e então processe o pedido ou reembolse o pagamento por lá.
Desenvolvedores: o hook actionEcpayPRequestParams permite que outro módulo altere os parâmetros enviados à ECPay; o comerciante, o número da transação e o valor não podem ser alterados por ele.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox ECPay Payment 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 ligado, as configurações e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamento da ECPay e os status de pedido Awaiting ECPay payment e ECPay payment on hold são sempre mantidos, para que notificações tardias de pagamentos antigos continuem sendo verificadas após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
A ECPay é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela ECPay.