VibeFox Omise for WooCommerce — Ajuda
Requisitos
WordPress: 6.2 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não ativa sem ele; se o WooCommerce for desativado depois, o gateway não é carregado e um aviso é exibido para o administrador.
PHP: 8.0 ou superior.
HTTPS: os campos do cartão ficam na sua página de finalização de compra, por isso ela precisa ser servida por HTTPS e livre de scripts não confiáveis. Os dados do cartão, ainda assim, nunca chegam ao seu servidor. A Omise envia webhooks apenas para endereços HTTPS.
Moeda da loja: uma de THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Para outras moedas, o método de pagamento fica oculto na finalização de compra.
Conta na Omise: você precisa da chave pública e da chave secreta da sua conta na Omise, tanto para o modo de teste quanto para o de produção, em Settings > Keys no painel da Omise, e de um endpoint de webhook em Settings > Webhooks (veja Configuração).
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_omise_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Omise > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe as chaves de teste e de produção da Omise e adicione no painel da Omise a URL do webhook mostrada na página de configurações (veja Configuração).
6. Ative Enable/Disable. Teste um pagamento no modo de teste com um cartão de teste da Omise, como 4242 4242 4242 4242, e depois desmarque Test mode.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Omise. Acima dos campos, a página mostra Test mode is on — orders are charged with the test keys, no real money is moved. enquanto o modo de teste estiver ativo, e avisa quando a chave pública ou a secreta do modo atual está faltando ou quando a moeda da loja não é aceita pela Omise. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Na lista de métodos de pagamento, a Omise aparece como pendente de configuração até que as duas chaves do modo atual sejam informadas.
Geral
Enable/Disable: Enable card payments via Omise ativa ou desativa 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: Credit / Debit Card.
Description: o texto exibido acima do formulário de cartão na finalização de compra. Padrão: Pay securely with your credit or debit card via Omise.
Chaves de API
Você encontra as chaves no painel da Omise, em Settings > Keys. As chaves de teste começam com pkey_test_ e skey_test_, e as de produção com pkey_ e skey_. Ao salvar, uma chave com o prefixo errado (por exemplo, uma chave de teste em um campo de produção) é recusada com um erro, e o valor anterior é mantido.
Test mode: Use the test keys (no real charges). Alterna as duas chaves. Reembolsos, capturas e verificações de status de um pedido sempre usam as chaves do modo em que o pedido foi pago. Padrão: ativado.
Test public key: a chave pública do modo de teste, pkey_test_...
Test secret key: a chave secreta do modo de teste, skey_test_...
Live public key: a chave pública do modo de produção, pkey_...
Live secret key: a chave secreta do modo de produção, skey_...
Pagamento e webhook
A seção mostra a URL do webhook da sua loja. Ela tem a forma https://your-site/wp-json/omise-payment/v1/webhook. Copie-a exatamente como as configurações a mostram e adicione-a no painel da Omise em Settings > Webhooks (somente HTTPS). O plugin processa estes eventos:
O conteúdo do webhook nunca é considerado confiável: a cobrança precisa ser a salva no pedido, e o status dela é relido pela API da Omise com as chaves do modo do pedido. Sem o webhook, um pedido cujo cliente fecha o navegador durante o 3-D Secure fica Em espera até você executar Omise: Sync payment status, e as capturas feitas no painel da Omise não são recebidas automaticamente.
Payment action: o que acontece com o valor no cartão.
Per-charge webhook: Send the webhook URL with every charge. Útil quando várias lojas compartilham uma mesma conta na Omise. Funciona somente se o site usar HTTPS; caso contrário, é usado o webhook do painel. Padrão: desativado.
Avançado
Debug log: Log API requests and payment events grava as etapas do pagamento em WooCommerce > Status > Logs, origem wcp_omise_payment. Chaves, tokens e dados do cartão nunca são registrados. Padrão: desativado.
Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Credit / Debit Card) e preenche o formulário do cartão: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) e Security code (CVV). No modo de teste, o formulário mostra TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. Quando o pedido é feito, o Omise.js transforma o cartão em um token de uso único no navegador. Os campos do cartão nunca são enviados ao seu servidor.
Sua loja cria a cobrança com a chave secreta pelo total do pedido, na moeda do pedido. A descrição da cobrança é o nome da loja e o número do pedido, e o ID do pedido é salvo nos metadados da cobrança. Se o banco exigir 3-D Secure, o cliente é redirecionado ao banco e depois volta à sua loja. O resultado é sempre relido pela API da Omise.
O pedido só é marcado como pago depois que a Omise confirma: a cobrança precisa estar capturada, e o valor e a moeda precisam corresponder ao pedido. Com Authorize only, o pedido fica Em espera após uma autorização bem-sucedida. O cliente vê a página de pedido recebido.
Se o cartão for recusado, o cliente permanece na finalização de compra com Payment failed: e um motivo, por exemplo saldo insuficiente, código de segurança inválido ou recusa do emissor do cartão, e pode tentar de novo. Após uma falha no 3-D Secure, o cliente é levado à página Pay for order. Se o pagamento não puder ser confirmado logo após o 3-D Secure, o cliente vê We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.
Uma nova tentativa nunca cobra duas vezes: se a cobrança anterior do pedido já estiver paga ou autorizada, o pedido é concluído sem uma nova cobrança. Uma tentativa de 3-D Secure não concluída expira antes de qualquer nova cobrança.
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 WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita apenas cartões. Não possui outros métodos de pagamento da Omise (PromptPay, TrueMoney, bancos móveis, parcelamentos, Konbini, PayNow), cartões salvos ou clientes da Omise, assinaturas nem captura parcial.
Pedidos e reembolsos
Status do pedido
Pagamento pendente: o cliente está no 3-D Secure ou ainda não concluiu o pagamento.
Processando: o pagamento foi confirmado. Pedidos com apenas produtos virtuais para download passam a Concluído, como é habitual no WooCommerce. A nota do pedido mostra o valor, o ID da cobrança e como ela foi confirmada (finalização de compra, retorno do 3-D Secure, webhook, captura manual ou sincronização manual). O ID da transação é o ID da cobrança na Omise (chrg_...).
Em espera, aguardando captura: o cartão foi autorizado com Authorize only. Use Omise: Capture payment ou Omise: Void authorization.
Em espera, pendente: a Omise ainda não confirmou o pagamento, por exemplo porque o cliente fechou o navegador durante o 3-D Secure. O webhook ou Omise: Sync payment status atualiza o pedido.
Em espera, divergência: o valor ou a moeda da cobrança é diferente do pedido. A nota mostra os dois valores. Confira o pedido e conclua-o ou reembolse o pagamento.
Falhou: o pagamento foi recusado. Um pedido pago nunca é rebaixado por um evento de falha posterior.
Cancelado: a cobrança expirou ou a autorização foi anulada.
Se chegar uma cobrança paga ou autorizada para um pedido que já está Cancelado ou Reembolsado, o pedido não é reaberto. Uma nota pede que você verifique o painel da Omise e reembolse ou reabra o pedido manualmente.
Ações do pedido
Omise: Capture payment: captura o valor total autorizado. Exibida somente para pedidos autorizados.
Omise: Void authorization: anula a autorização; nenhum dinheiro é capturado e o pedido é cancelado. Exibida somente para pedidos autorizados.
Omise: Sync payment status: lê a cobrança na Omise e atualiza o pedido. A nota também mostra o total reembolsado pela Omise.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Omise. São aceitos reembolsos totais e parciais. O reembolso é enviado no modo em que o pagamento foi feito, por isso a chave secreta desse modo precisa estar preenchida. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID de reembolso da Omise. Para uma autorização que ainda não foi capturada, só é possível um reembolso total, que anula a autorização. Se a Omise recusar o reembolso, o WooCommerce mostra Refund failed. com a mensagem da Omise, e nenhum reembolso é registrado.
Reembolsos feitos no painel da Omise não são importados como reembolsos do WooCommerce. O Omise: Sync payment status mostra o total reembolsado; crie reembolsos manuais correspondentes no WooCommerce, se necessário.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Omise. 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 na vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta na vibefox.net.
Sem uma chave ativa, a Omise 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. Os gerentes da loja que estiverem 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 Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e capturas e reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado de novo automaticamente em segundo plano.
Solução de problemas
A Omise não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se as duas chaves do modo atual foram informadas (as de teste no modo de teste, as de produção nos demais casos) e se a moeda é aceita. Na página Pay for order, vale a moeda do pedido. A página de configurações mostra um aviso quando as chaves ou a moeda estão incorretas.
O pagamento foi feito, mas o pedido continua em Pagamento pendente ou Em espera: o webhook não está funcionando. No painel da Omise, confira se a URL do webhook é exatamente a mostrada nas configurações e se usa HTTPS. Depois execute Omise: Sync payment status no pedido. Ative o Debug log para ver as respostas do webhook.
O webhook responde Earlier charge of the order, order not changed: o evento se refere a uma tentativa anterior do pedido, que foi substituída por uma nova tentativa. Nada é alterado no pedido. Se essa cobrança anterior ainda estiver paga ou autorizada na Omise, uma nota do pedido informa isso uma vez: verifique no painel da Omise se houve pagamento duplicado e reembolse ou anule-o por lá.
O webhook responde Charge ID does not match order: a cobrança do evento pertence a outro pedido. Nada é alterado.
O webhook responde Order is being processed, retry later ou Failed to verify charge: o pedido estava bloqueado por outra requisição, ou a API da Omise não pôde ser acessada. A Omise tenta o webhook novamente.
Erro ao salvar: key must start with ... ou must be a live key: uma chave foi colada no campo errado. As chaves de teste começam com pkey_test_ / skey_test_, e as de produção com pkey_ / skey_.
O cliente vê Card payments are temporarily unavailable: as chaves estão incorretas, ou o token do cartão pertence ao outro modo (um token de teste em produção, ou o contrário). Confira as chaves e Test mode.
O cliente vê We could not reach the payment provider: nenhuma resposta válida veio da Omise ao criar a cobrança. Uma cobrança pode ter sido criada mesmo assim; a nota do pedido pede que você verifique o painel da Omise antes de cobrar o pedido novamente.
O cliente vê This order is already being paid: a finalização de compra foi enviada duas vezes ao mesmo tempo. O cliente deve aguardar e verificar o e-mail antes de tentar de novo.
O pedido fica Em espera após o pagamento: leia a nota do pedido. O pedido aguarda a captura, a Omise ainda não confirmou o pagamento, ou o valor ou a moeda diferem do pedido.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está preenchida. Informe-a e tente de novo.
Falha o reembolso parcial de um pedido autorizado: o pagamento está apenas autorizado. Capture-o primeiro, ou reembolse o valor total para anulá-lo.
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 da vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o 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 e os logs só são removidos se Delete data on uninstall estava ativado. Caso contrário, eles ficam guardados para uma reinstalação futura. Os dados da Omise salvos nos pedidos fazem parte do histórico de pagamentos e são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Omise é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Omise.