VibeFox ECPay for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo.
PHP: 8.0 ou superior.
Moeda da loja: novo dólar taiwanês (TWD). A ECPay cobra apenas em TWD, e a forma de pagamento é ocultada quando a loja, ou o pedido que está sendo pago, usa outra moeda. Os valores são enviados em TWD inteiros, porque a ECPay não aceita decimais: os totais do pedido são arredondados para o dólar mais próximo. Use 0 casas decimais para preços em TWD para evitar arredondamento.
Conta ECPay: para pagamentos reais você precisa do MerchantID, da HashKey e da HashIV da sua conta de comerciante ECPay, obtidos no back-office de comerciante da ECPay (vendor.ecpay.com.tw). Para testes não é necessária nenhuma conta ECPay.
Acesso ao site: o seu site deve estar acessível pela internet via HTTP/HTTPS na porta 80/443, para que a ECPay possa entregar as notificações de pagamento. Modo de manutenção, um firewall ou autenticação básica na frente do site as bloqueiam.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_ecpay_payment_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate. O WooCommerce precisa estar ativo.
3. Abra as configurações: WooCommerce > Settings > Payments > ECPay (綠界) > Manage, ou clique em Settings sob o nome do plugin na página de Plugins.
4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Ative Enable/Disable, escolha as formas de pagamento e mantenha Test Mode ativado para os primeiros testes. No sandbox, você pode pagar com o cartão de teste da ECPay 4311-9522-2222-2222 (qualquer data de validade futura, CVV 222, código 3-D Secure da página do sandbox).
6. Para pagamentos reais, digite o MerchantID, a HashKey e a HashIV (veja Configuração) e desmarque Test Mode.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > ECPay (綠界). Acima dos campos, a página mostra um erro quando a moeda da loja não é TWD (a ECPay não é exibida na finalização de compra nesse caso) e quando o modo de produção está sem MerchantID, HashKey e HashIV. Enquanto o modo de teste está ativado, 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 precisa ser desativado antes de aceitar pedidos reais.
Geral
Enable/Disable: Enable ECPay Payment ativa ou desativa a forma de pagamento. Padrão: desativado.
Title: o nome da forma de pagamento que os clientes veem na finalização de compra. Padrão: ECPay (綠界).
Description: o texto exibido sob a forma de pagamento na finalização de compra. Padrão: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
Conta ECPay
Encontre 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: Enable sandbox/test mode envia os pagamentos para o sandbox da ECPay (payment-stage.ecpay.com.tw) com o comerciante de teste público ECPay 3002607. Sem dinheiro real. As credenciais abaixo só são usadas quando o modo de teste está desativado. Padrão: ativado.
Merchant ID: seu Merchant ID da ECPay (produção). Ignorado no modo de teste.
Hash Key: sua Hash Key da ECPay (produção). Ignorada no modo de teste.
Hash IV: sua Hash IV da ECPay (produção). Ignorada no modo de teste.
Espaços e quebras de linha nas credenciais coladas quebram todas as assinaturas, então são removidos ao salvar, e a página avisa sobre isso.
Opções de pagamento
Enabled Payment Methods: as formas oferecidas aos clientes. Com mais de uma, o cliente escolhe na finalização de compra. Pedidos de ATM, CVS e Barcode ficam com status Aguardando até o cliente pagar. Pelo menos uma forma deve ser selecionada; se nenhuma for, Credit Card é ativado. Padrão: Credit Card.
Default Payment Method: a forma pré-selecionada. Ela precisa ser uma das formas ativadas; caso contrário, a primeira forma ativada é usada. Padrão: Credit Card.
Order Prefix: o prefixo do número de transação ECPay (MerchantTradeNo), com até 5 letras ou dígitos. Outros caracteres são removidos ao salvar. Útil quando várias lojas compartilham uma conta ECPay: dê a cada loja seu próprio prefixo. Padrão: EC.
Notificações de pagamento
A ECPay envia os resultados de pagamento para sua loja. Esta seção mostra a URL de notificação. Ela se parece com https://your-site/wc-api/ecpay_p_callback/. A URL é enviada em cada pagamento, então nada precisa ser configurado na ECPay, mas ela precisa estar acessível pela internet na porta 80/443, sem modo de manutenção, firewall ou autenticação básica na frente.
Cada notificação é verificada pela assinatura CheckMacValue com as chaves do ambiente (teste ou produção) em que o pagamento foi iniciado. Notificações sem assinatura válida são rejeitadas, e a ECPay as envia novamente. Sem a notificação, nenhum pedido é marcado como pago; verifique o pagamento no back-office da ECPay.
Avançado
Enable Logging: Log payment events and API calls grava os IDs de pedido, números de transação, valores e códigos de retorno da ECPay em WooCommerce > Status > Logs, origem wcp_ecpay_payment_gateway. Nenhuma chave ou dado de cliente é registrado. Padrão: desativado.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Remove todas as configurações, logs e metadados de pedido deste plugin. Padrão: desativado.
Finalização de compra
O cliente escolhe a forma 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. Enquanto o modo de teste está ativado, a forma de pagamento mostra TEST MODE — ECPay sandbox, no real money is charged.
Depois que o pedido é feito, 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 para o caso de o redirecionamento não iniciar. O total do pedido é enviado em TWD inteiros com os nomes e quantidades dos itens. A página da ECPay abre em chinês tradicional para os idiomas do site 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.
O pedido só é marcado como pago depois que a ECPay confirma com uma notificação de servidor assinada. Quando o cliente volta para a página de pedido recebido antes de a confirmação chegar, a página mostra We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: com um botão Pay.
Para ATM, CVS e Barcode, o cliente primeiro recebe os detalhes de pagamento. O pedido passa para Aguardando, e o código bancário e a conta virtual, o código de pagamento em 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 agradecimento, em My account > Orders e no e-mail de pedido com status Aguardando. Quando o cliente paga, a ECPay envia outra notificação e o pedido é marcado como pago.
Cada visita à página de pagamento cria um novo número de transação ECPay, porque a ECPay rejeita números reutilizados. Assim, a página Pay for order e novas tentativas após um pagamento com falha funcionam, e notificações para qualquer um desses números são associadas ao pedido. Um pedido pode ter até 30 tentativas de pagamento.
Os próprios limites de valor da ECPay por método, por exemplo para pagamentos em lojas de conveniência, são verificados na página da ECPay, não na finalização de compra.
A forma de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita apenas pagamentos únicos na página da ECPay. Não há reembolsos pelo WooCommerce, cartões salvos, assinaturas ou pagamentos periódicos (定期定額), parcelamento, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, notas fiscais eletrônicas ou logística, nem consulta de status no servidor: se o seu site não puder receber a notificação, verifique o pagamento no back-office da ECPay.
Pedidos
Status do pedido
Pending payment: o cliente foi enviado para a ECPay e ainda não pagou, ou a notificação ainda não chegou.
On hold, waiting for payment: o cliente escolheu ATM, CVS ou Barcode e recebeu os detalhes de pagamento. A nota do pedido mostra o código bancário e a conta virtual, o código de pagamento ou os códigos de barras e o prazo.
Processing: o pagamento foi confirmado (o padrão do WooCommerce; pedidos somente com produtos virtuais para download passam para Concluído). A nota do pedido mostra o TradeNo da ECPay, o tipo de pagamento, o valor e o número de transação. O ID da transação é o TradeNo da ECPay.
On hold after payment: a ECPay informou um valor ou moeda diferentes do pedido, um pagamento de sandbox chegou depois que você mudou para o modo de produção (nenhum dinheiro real foi cobrado), ou o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica isso. Compare com o back-office da ECPay e conclua ou reembolse o pedido manualmente.
Failed: a ECPay informou que a última tentativa de pagamento falhou. A nota mostra o código de retorno e a mensagem da ECPay. O cliente pode tentar de novo.
Notificações repetidas são ignoradas. Um pedido pago, cancelado ou reembolsado nunca é reaberto por uma notificação antiga. Um segundo pagamento para um pedido já pago, por exemplo a partir de duas abas do navegador, é registrado como uma nota do pedido, 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 o pedido como pago, porque a ECPay não cobra dinheiro por eles.
Reembolsos
Reembolsos pelo WooCommerce não estão disponíveis. Reembolse o pagamento no back-office da ECPay e depois 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 está no topo de WooCommerce > Settings > Payments > ECPay (綠界). 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 seu domínio. Use Check now para verificar o status de novo, Change key para digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do seu domínio. Libere a vaga na sua conta em 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. Gerentes de loja com sessão iniciada continuam vendo a forma de pagamento, marcada (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um aviso aparece na página de Plugins e nas páginas do WooCommerce. 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 de novo automaticamente em segundo plano.
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á ativado, se a moeda da loja é TWD e se, no modo de produção, o Merchant ID, a Hash Key e a Hash IV estão definidos. A página de configurações mostra um erro em cada um desses casos.
O pagamento foi feito, mas o pedido continua em Pagamento pendente: a notificação da ECPay não chegou ao seu site (site fora do ar, firewall, modo de manutenção, autenticação básica). A ECPay tenta novamente várias vezes. Você também pode verificar a transação no back-office da ECPay e concluir o pedido manualmente. Ative Enable Logging para ver as notificações que o plugin recebeu.
A notificação responde 0|CheckMacValue verification failed: a Hash Key ou a Hash IV não correspondem à sua conta ECPay. Copie-as de novo do back-office da ECPay.
A notificação responde 0|MerchantID mismatch: a notificação pertence a um comerciante 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 seu próprio Order Prefix.
O cliente vê The order total is too small for ECPay.: o total do pedido está abaixo de 1 TWD após o arredondamento e não pode ser pago com a ECPay.
O pedido está Aguardando com uma nota de divergência de valor: o valor informado pela ECPay é diferente do total do pedido, por exemplo porque o pedido foi editado depois que o cliente começou a pagar. Compare com o back-office da ECPay e conclua ou reembolse o pedido manualmente.
O pedido está Aguardando após um pagamento de sandbox: o pagamento foi feito no modo de teste, mas a loja agora está no modo de produção. Nenhum dinheiro real foi cobrado. Verifique o pedido manualmente.
O cliente vê Too many payment attempts for this order: o pedido chegou a 30 tentativas de pagamento. Peça ao cliente para fazer um novo pedido.
O bloco de licença mostra um erro: siga a mensagem no 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 contatado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações, os dados da ECPay armazenados 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 posterior. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A ECPay é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela ECPay.