VibeFox Omise 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.
HTTPS: os campos do cartão ficam na sua página de finalização de compra, então ela deve ser servida por HTTPS. Mesmo assim, os dados do cartão nunca chegam ao seu servidor. A Omise envia webhooks apenas para endereços HTTPS, e a página 3-D Secure do banco precisa ser um endereço HTTPS.
Moeda: uma de THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Para um carrinho em qualquer outra moeda, 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, para o modo de teste e para o modo 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 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 Omise Payment na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Insira as chaves da Omise de teste e de produção e adicione no painel da Omise a URL do webhook exibida na página de configurações (veja Configuração).
5. Ative Enable/Disable e clique em Save. Teste um pagamento no modo de teste com um cartão de teste da Omise, como 4242 4242 4242 4242, e depois desative Test mode.
Ao instalar, o módulo cria três status de pedido: Omise payment authorized, Omise payment on hold e Awaiting Omise payment. O método de pagamento é oferecido para os países ativos no momento da instalação. Se você ativar mais países depois, permita o módulo para eles em Payment > Preferences, onde também pode limitá-lo por moeda e grupo de clientes.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Omise Payment > Configure. Cada seção tem o próprio botão Save, que salva a página inteira. 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, avisa quando faltar a chave pública ou secreta do modo atual e avisa quando a Omise não aceitar a moeda padrão da sua loja. Nesses casos, o método de pagamento fica oculto na finalização de compra.
Omise
Enable/Disable: Enable card payments via Omise ativa ou desativa o método de pagamento. Padrão: off.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. É também o nome do método de pagamento salvo no pedido. Padrão: Credit / Debit Card. Obrigatório.
Description: o texto exibido acima do formulário do 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) não é salva: o valor anterior é mantido e um aviso é exibido.
Test mode: usa as chaves de teste, sem cobranças reais. Ele troca as duas chaves ao mesmo tempo. Capturas, reembolsos e verificações de status de um pedido sempre usam as chaves do modo em que o pedido foi pago. Padrão: on.
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_...
As 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á-la.
Clear saved secrets: marque uma chave secreta e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Pagamento e webhook
Webhook URL: o endereço do webhook da sua loja. Com URLs amigáveis, ele tem este formato: https://your-shop/module/wcp_omise_payment/webhook. Copie-o exatamente como as configurações o mostram e adicione-o no painel da Omise, em Settings > Webhooks (somente HTTPS). O módulo trata estes eventos (eles também estão listados nesta seção):
A Omise não assina os webhooks, por isso o conteúdo do webhook nunca é considerado confiável: a cobrança precisa ter sido criada por esta loja para aquele carrinho, e o status dela é relido na API da Omise com a chave secreta do modo do pagamento. Sem o webhook, um pedido cujo cliente fecha o navegador durante o 3-D Secure não é criado automaticamente, e as capturas feitas no painel da Omise não são registradas até que você clique em Sync payment status.
Payment action: o que acontece com o valor no cartão.
Per-charge webhook: envia a URL do webhook com cada cobrança. Útil quando várias lojas compartilham uma única conta na Omise. Funciona somente se a loja usar HTTPS; caso contrário, é usado o webhook do painel. Padrão: off.
Avançado
Debug log: grava as requisições à API e os eventos de pagamento em logs/omise_p_debug.log.php, na pasta do módulo. O arquivo não pode ser lido pela web. Chaves, tokens e dados do cartão nunca são registrados. Padrão: off. Enquanto estiver desativado, nada é gravado, nem mesmo erros; por isso, ative-o quando estiver procurando um problema.
Log: mostra o tamanho e as últimas entradas do registro, com um botão para limpá-lo.
Delete data on uninstall: quando ativado, ao desinstalar o módulo as configurações e o log de depuração são removidos. As cobranças e os reembolsos da Omise dos pedidos fazem parte do histórico de pagamentos e são sempre mantidos. Padrão: off.
Finalização de compra
Na etapa de pagamento, 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 cliente faz o pedido, o Omise.js transforma o cartão em um token de uso único no navegador, usando o endereço de cobrança do carrinho. Os dados do cartão nunca são enviados à sua loja. Campos ausentes ou inválidos são mostrados abaixo do formulário, por exemplo Please enter a valid card number.
Sua loja então cria a cobrança com a chave secreta pelo total do carrinho, na moeda do carrinho. A descrição da cobrança é o nome da loja e o número do carrinho, e o ID do carrinho é salvo nos metadados da cobrança. Nesse momento, ainda não existe pedido. Se o banco exigir o 3-D Secure, o cliente é enviado à página do banco e volta à sua loja, e o resultado é relido na API da Omise.
O pedido só é marcado como pago depois que a Omise confirma: a cobrança precisa estar capturada, e seu valor e sua moeda precisam corresponder ao carrinho. O cliente vê a página padrão de confirmação do pedido com Your card payment has been received. Com Authorize only, a página diz Your card payment has been authorized. The amount will be charged when your order is processed. Se a Omise ainda informar o pagamento como pendente, o pedido é criado em Awaiting Omise payment e a página diz Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Se o pagamento não puder ser confirmado logo após o 3-D Secure, uma página de Payment confirmation mostra We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. e um botão Check again.
Se o cartão for recusado, nenhum pedido é criado. 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 da emissora do cartão, e pode tentar novamente com o mesmo carrinho. Se o 3-D Secure falhar, o cliente volta à finalização de compra com o motivo; se a cobrança tiver expirado ou sido estornada nesse meio tempo, a mensagem é The payment was not completed. Please try again.
Uma nova tentativa nunca cobra duas vezes: se a cobrança anterior do carrinho já estiver paga ou autorizada, o pedido é criado sem nova cobrança. Uma tentativa 3-D Secure não concluída expira antes que uma nova cobrança seja feita. Se uma segunda cobrança continuar paga para um carrinho que já tem pedido (por exemplo, em outra aba do navegador), o pedido não é alterado e uma nota pede que você a reembolse ou anule no painel da Omise.
O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo aceita apenas cartões. Ele não oferece outros métodos de pagamento da Omise (PromptPay, TrueMoney, bancos móveis, parcelamentos), nem cartões salvos ou clientes da Omise, nem assinaturas e nem captura parcial.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente está no 3-D Secure, ou o cartão foi recusado. Só o carrinho existe.
Payment accepted: o pagamento foi confirmado. O pagamento é registrado com o ID da cobrança da Omise (chrg_...) como ID da transação, e uma nota mostra o valor, a cobrança e como ela foi confirmada (finalização de compra, retorno do 3-D Secure, webhook, nova tentativa de pagamento, captura manual ou sincronização manual). As notas são mensagens privadas do pedido, visíveis somente no back office.
Omise payment authorized: o cartão foi autorizado com Authorize only. Use Capture payment ou Void authorization.
Awaiting Omise payment: a Omise ainda não confirmou o pagamento. O webhook ou o Sync payment status atualiza o pedido.
Omise payment on hold: o valor ou a moeda da cobrança diferem do pedido, por exemplo porque o carrinho foi alterado durante o 3-D Secure. A nota mostra os dois valores. Um pagamento capturado continua registrado no pedido. Verifique o pedido e atenda-o ou reembolse o pagamento.
Payment error: um pagamento pendente falhou depois. Um pedido pago nunca é rebaixado por um evento de falha posterior.
Canceled: a cobrança expirou ou a autorização foi cancelada.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
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.
Bloco de pagamento da Omise
A página do pedido mostra um bloco Omise payment com o ID da cobrança, a ação de pagamento, o status da cobrança, a bandeira e os últimos dígitos do cartão, os valores cobrado, do pedido e reembolsado, um selo Test mode para pagamentos de teste e o histórico de reembolsos. Os botões do bloco exigem a permissão para editar pedidos e a chave secreta do modo em que o pagamento foi feito. Não é necessário acesso às páginas de módulos. O resultado de cada ação aparece no topo do bloco.
Capture payment: captura o valor autorizado integral e define o pedido como Payment accepted. Exibido somente para pedidos autorizados.
Void authorization: anula a autorização; nenhum dinheiro é capturado e o pedido é definido como Canceled. Exibido somente para pedidos autorizados.
Sync payment status: relê a cobrança na Omise e atualiza o pedido. A nota também mostra o total reembolsado na Omise.
Reembolsos
No bloco Omise payment, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Omise. Confirme a pergunta Refund this amount through Omise? This cannot be undone. Reembolsos totais e parciais são suportados. Os reembolsos são feitos no valor e na moeda cobrados pela Omise; assim, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, e não até o total do pedido. O reembolso é enviado no modo em que o pagamento foi feito, então a chave secreta desse modo precisa estar configurada. O motivo é salvo junto ao reembolso na Omise. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso da Omise. Um reembolso total define o pedido como Refunded; um reembolso parcial não altera o status. Para uma autorização que ainda não foi capturada, só é possível o reembolso total, e ele anula a autorização. Se a Omise recusar o reembolso, o bloco mostra Refund failed. com a mensagem da Omise, e nenhum reembolso é registrado.
O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Omise. Os reembolsos feitos no painel da Omise não são registrados no PrestaShop; o Sync payment status mostra o total reembolsado.
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 Omise Payment é o primeiro bloco de Modules > Module Manager > VibeFox Omise Payment > 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 aparecem a linha Product: presta-payment-omise e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o 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 Chave não encontrada, Esta chave pertence a outro produto, Limite de domínios atingido ou Licença expirou em 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 estiver acessível, 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 em vibefox.net.
Sem uma chave ativa, a Omise não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, o cliente vê Este método de pagamento não está disponível. Escolha outro. A vitrine do PrestaShop não sabe que você está logado no back office, então o método de pagamento também fica oculto para 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: os pagamentos já iniciados continuam sendo confirmados, e os reembolsos continuam funcionando.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia durante os primeiros 14 dias após a chave ser inserida e, depois, uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
Omise does not appear at checkout: verifique se a licença está ativa, se o Enable/Disable está ligado, se as duas chaves do modo atual estão preenchidas (chaves de teste no modo de teste, chaves de produção nos demais casos) e se a moeda do carrinho é uma das moedas suportadas. A página de configurações mostra um aviso quando faltam chaves. 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.
The payment went through, but no order was created or the order stays Awaiting Omise payment: o webhook não está funcionando. No painel da Omise, verifique se a URL do webhook é exatamente a exibida em Webhook URL e se usa HTTPS. Em um pedido existente, clique em Sync payment status. Ative o Debug log para ver as respostas do webhook.
Webhook answers Charge ID does not match order or Order not found: a cobrança do evento não foi criada por esta loja para aquele carrinho. Nada é alterado.
Webhook answers Order is being processed, retry later or Failed to verify charge: o carrinho foi bloqueado por outra requisição no mesmo instante, a API da Omise não pôde ser acessada, ou a chave secreta do modo do pagamento está ausente. A Omise tenta o webhook novamente.
Webhook answers The order could not be created, retry later: o pedido não pôde ser criado, por exemplo porque o módulo está desativado. Ative o Debug log para ver o motivo.
The webhook URL shows Method not allowed in the browser: isso é normal. A URL aceita apenas requisições da Omise.
Warning on save: key must start with ... or must be a live key: uma chave foi colada no campo errado e não foi salva. As chaves de teste começam com pkey_test_ / skey_test_, e as de produção com pkey_ / skey_.
The customer sees 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 inverso). Verifique as chaves e o Test mode.
The customer sees 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; verifique o painel da Omise antes que o cliente pague novamente.
The customer sees This order is already being paid: a finalização de compra foi enviada duas vezes no mesmo instante. O cliente aguarda um momento e verifica o e-mail antes de tentar de novo.
Order is Omise payment on hold after payment: leia a nota no pedido (veja Status do pedido) e depois atenda o pedido ou reembolse o pagamento.
Refund fails with a message about the mode: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está definida. Insira-a e tente novamente.
Partial refund of an authorized order fails: o pagamento está apenas autorizado. Capture-o primeiro, ou reembolse o valor integral para anulá-lo.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Omise Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se o Delete data on uninstall estiver ativado, as configurações e o log de depuração são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As cobranças e os reembolsos da Omise e os status de pedido Omise payment authorized, Omise payment on hold e Awaiting Omise payment são sempre mantidos, de modo que os pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Omise é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Omise.