VibeFox KOMOJU for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Conta KOMOJU: você precisa da chave secreta (sk_live_... e, para o modo de teste, sk_test_...) e do token secreto de um webhook criado no painel da KOMOJU (veja Configuração). A chave publicável não é necessária. A KOMOJU precisa conseguir acessar a URL do webhook da sua loja.
Moeda do carrinho: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD ou VND. Para carrinhos em outras moedas, o método de pagamento fica oculto.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 KOMOJU Payment na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox em License key no bloco de licença no topo da página de configuração e clique em Activate (veja Chave de licença).
4. No painel da KOMOJU, adicione um webhook com a URL e os eventos mostrados na seção Webhook URL e copie o token secreto dele (veja Configuração).
5. Insira a chave secreta de produção e o token secreto do webhook de produção, e os de teste para o modo de teste. Ative Enable/Disable e clique em Save.
Na instalação, o módulo cria dois status de pedido: Awaiting KOMOJU payment e KOMOJU payment on hold. O PrestaShop vincula um novo módulo de pagamento apenas aos países ativos naquele momento: um país que você ativar depois deve ser marcado para o módulo em Payment > Preferences. Ali você também pode limitar moedas e grupos de clientes.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox KOMOJU Payment > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra KOMOJU Sandbox Mode is enabled. enquanto o modo de teste estiver ativo. Ela avisa quando o modo atual não tem chave secreta (o método de pagamento fica oculto na finalização de compra) ou token secreto de webhook (as notificações da KOMOJU são rejeitadas e, assim, pagamentos konbini e transferência bancária nunca são confirmados), e quando a KOMOJU não aceita a moeda padrão da loja (o método de pagamento fica oculto para carrinhos nessa moeda).
Pagamento KOMOJU
Enable/Disable: Enable KOMOJU Payment Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
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: KOMOJU Payment.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.
Chaves de API de produção
As chaves estão no painel da KOMOJU: a chave secreta em Settings > API keys e o token secreto do webhook em Settings > Webhooks (adicione antes ali a URL do webhook mostrada na seção Webhook URL).
Live Secret Key: sua chave secreta KOMOJU de produção. Ela começa com sk_live_.
Live Webhook Secret Token: o token secreto do webhook de produção. Ele é usado para verificar a assinatura de cada notificação.
Modo de teste
A KOMOJU usa o mesmo endereço de API para pagamentos de teste e de produção: a chave é que define o modo. Os pagamentos mantêm o modo em que foram feitos, então reembolsos e verificações de status de um pedido sempre usam a chave desse modo.
Sandbox Mode: Enable test mode (use the test keys below, no real payments). Padrão: desativado. Enquanto estiver ativo, a finalização de compra mostra Test mode acima da descrição.
Sandbox Secret Key: sua chave secreta de teste da KOMOJU. Ela começa com sk_test_.
Sandbox Webhook Secret Token: o token secreto do webhook do modo de teste.
Chaves e tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.
Limpar segredos salvos: marque uma chave ou token e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
URL do webhook
O webhook informa sua loja sobre os pagamentos, inclusive os pagamentos konbini e de transferência bancária com atraso. No painel da KOMOJU, em Settings > Webhooks, adicione a URL mostrada nesta seção, tanto para produção quanto para o modo de teste. Com URLs amigáveis ela tem este formato: https://your-shop/module/wcp_komoju_payment/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram. Depois copie o token secreto de cada webhook para Live Webhook Secret Token ou Sandbox Webhook Secret Token.
Selecione estes eventos (eles também estão listados nesta seção):
Eventos de vencimento, cancelamento e falha alteram o pedido somente para o pagamento atual dele, então um pagamento de uma tentativa anterior não pode cancelar um pedido que está sendo pago de outra forma. Webhooks sem assinatura válida são rejeitados. Webhooks assinados com qualquer um dos dois tokens secretos são aceitos, mas somente para pagamentos do mesmo modo. Sem o webhook, pagamentos com cartão continuam sendo confirmados quando o cliente retorna à loja, mas pagamentos konbini e de transferência bancária nunca são confirmados.
Avançado
Invoice Prefix: o prefixo dos números de pedido enviados à KOMOJU, seguido do número do carrinho. Se você usar várias lojas com a mesma conta KOMOJU, torne-o único para cada loja. Padrão: PS-.
Enable Logging: grava eventos da KOMOJU e chamadas de API em logs/komoju_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados de clientes não são registrados. Erros e avisos são sempre gravados. Padrão: desativado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, ao desinstalar o módulo as configurações do gateway e o log são removidos. Pedidos, transações e reembolsos da KOMOJU e os status de pedido sempre permanecem, então pedidos antigos ainda podem ser confirmados e reembolsados após uma reinstalação. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão KOMOJU Payment) e confirma. O módulo cria uma sessão de pagamento KOMOJU para o total do carrinho na moeda do carrinho e envia o cliente à página de pagamento da KOMOJU. E-mail, nome, endereços de cobrança e de entrega e os itens do pedido são transmitidos à KOMOJU. A página é exibida em japonês, inglês ou coreano, conforme o idioma do carrinho (em inglês para os demais idiomas). Lá o cliente escolhe um método de pagamento. Os métodos oferecidos dependem da sua conta KOMOJU e da moeda do carrinho. Neste ponto, ainda não existe pedido.
Após pagar, o cliente retorna à sua loja. O módulo lê a sessão de pagamento pela API da KOMOJU com a chave do modo do pagamento. O pedido só é marcado como pago depois que a KOMOJU confirma: pelo webhook assinado ou pela leitura da sessão quando o cliente volta. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with KOMOJU has been received. Se a KOMOJU não puder ser acessada naquele momento, uma página de Payment confirmation mostra We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. e um botão Check again.
Nos pagamentos konbini e de transferência bancária, o cliente recebe uma guia de pagamento. O pedido é criado em Awaiting KOMOJU payment, e a página de confirmação orienta o cliente a concluir o pagamento conforme as instruções da KOMOJU (por exemplo, em uma loja de conveniência ou por transferência bancária). O pedido passa para Payment accepted quando o cliente paga e a KOMOJU envia o webhook. Se a guia vencer ou o pagamento falhar depois, a página de confirmação mostra Your KOMOJU payment was not completed. Please contact us about this order.
Se o pagamento não foi concluído, 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. Uma nova tentativa reutiliza a sessão KOMOJU aberta se o total não mudou. Uma sessão com total antigo é cancelada na KOMOJU, e uma sessão paga nesse meio-tempo cria o pedido em vez de um novo pagamento.
Se a KOMOJU não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo KOMOJU could not accept this payment: com o motivo, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. ou Payment error: Could not connect to KOMOJU. Please try again in a moment. O motivo técnico é gravado no log.
Se um cupom do carrinho deixar de ser válido entre o pagamento e a sua confirmação, o PrestaShop o remove do pedido. O pedido então vai para KOMOJU payment on hold com uma nota, porque o cliente pagou o preço com o desconto.
O webhook funciona com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo não tem formulário de cartão no seu site, cartões salvos ou assinaturas. Ele não restringe os métodos de pagamento: eles são escolhidos na página da KOMOJU. Não há ação de captura manual: pagamentos autorizados para captura manual devem ser capturados no painel da KOMOJU, e o pedido permanece em Awaiting KOMOJU payment até lá.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à KOMOJU e ainda não pagou, ou a KOMOJU ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted: a KOMOJU confirmou o pagamento. O pagamento é registrado com o ID de pagamento da KOMOJU como ID da transação, e uma nota mostra o ID do pagamento, o método de pagamento e como ele foi confirmado (webhook ou retorno).
Awaiting KOMOJU payment: uma guia konbini ou de transferência bancária foi emitida e aguarda pagamento, ou um pagamento aguarda captura no painel da KOMOJU.
KOMOJU payment on hold: a KOMOJU informou um valor ou moeda diferente do total do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou), um cupom foi removido, ou o pagamento foi capturado depois que o pedido havia sido cancelado. A nota explica. Verifique o pedido e processe-o ou reembolse o pagamento.
Canceled: a guia de pagamento venceu ou o pagamento foi cancelado.
Payment error: um pagamento de um pedido existente falhou.
Refunded: o pagamento foi totalmente reembolsado, pela página do pedido ou no painel da KOMOJU.
Se um segundo pagamento for capturado para um pedido que já está pago, o pedido não muda. Uma nota pede que você o reembolse no painel da KOMOJU se for um duplicado. Pedidos reembolsados nunca são reabertos.
Bloco de pagamento KOMOJU
A página do pedido mostra um bloco KOMOJU payment com o ID do pagamento na KOMOJU (com link para o pagamento no painel da KOMOJU) e o método de pagamento, a sessão, o número do pedido na KOMOJU, o status, o valor pago e o valor reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as KOMOJU notes do pedido.
Reembolsos
No bloco KOMOJU payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via KOMOJU. Confirme a pergunta Refund this amount through KOMOJU? This cannot be undone. Reembolsos totais e parciais são aceitos. Você precisa da permissão para editar pedidos. Os reembolsos são limitados ao valor que a KOMOJU efetivamente cobrou, então, após uma divergência de valor, você pode reembolsar até o que o cliente pagou, e não o total do pedido. O reembolso é enviado com a chave do modo em que o pagamento foi feito, então a chave secreta desse modo precisa estar configurada. O módulo primeiro verifica o pagamento na KOMOJU e recusa reembolsos acima do valor ainda reembolsável. Se a KOMOJU não puder reembolsar um pagamento automaticamente (alguns métodos, como konbini, precisam dos dados bancários do cliente), a mensagem de erro da KOMOJU é exibida e nada é registrado: faça esses reembolsos no painel da KOMOJU. Um reembolso só é considerado concluído quando a KOMOJU confirma. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a KOMOJU tiver capturado o pagamento.
Para pagamentos que a KOMOJU converteu para outra moeda (por exemplo, konbini em JPY para um carrinho em EUR), só é possível um reembolso total pelo PrestaShop. Faça os reembolsos parciais no painel da KOMOJU.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela KOMOJU.
Os reembolsos feitos no painel da KOMOJU chegam por webhook e são adicionados ao histórico de reembolsos com uma nota. Quando o pagamento inteiro é reembolsado, o pedido passa para Refunded. Reembolsos parciais feitos no painel para pagamentos convertidos em outra moeda são apenas anotados no pedido: registre manualmente no PrestaShop o valor correspondente (nota de crédito).
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 KOMOJU Payment é o primeiro bloco da página Modules > Module Manager > VibeFox KOMOJU Payment > Configure, acima das configurações. Informe 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 de novo, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo aparecem a linha Product: presta-payment-komoju 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 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 ú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 KOMOJU 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 pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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
A KOMOJU não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o modo atual tem uma chave secreta: Sandbox Secret Key no modo de teste, Live Secret Key no modo de produção. A moeda do carrinho precisa ser aceita pela KOMOJU. A página de configurações mostra um aviso quando algo está faltando. 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.
O pagamento foi feito, mas nenhum pedido foi criado: o webhook não está funcionando. No painel da KOMOJU, verifique se o webhook existe para o modo que você usa, se a URL é exatamente a mostrada na seção Webhook URL e se os eventos estão selecionados. Verifique se o token secreto dele está no campo correspondente (Live Webhook Secret Token ou Sandbox Webhook Secret Token) e veja o campo Log na página do módulo. Pagamentos com cartão também são confirmados quando o cliente retorna à sua loja, mas pagamentos konbini e de transferência bancária são confirmados somente pelo webhook.
O webhook responde Failed to verify KOMOJU webhook signature.: o token secreto está ausente ou pertence a outro webhook. A KOMOJU repete a notificação.
O webhook responde Mode mismatch, ignored.: o webhook foi assinado com o token secreto do outro modo, diferente do modo em que o pagamento foi feito. Use webhooks e tokens separados para produção e teste, e verifique se não estão trocados.
O webhook responde Order is busy, retry later. ou Temporary error, retry later.: o pedido estava sendo atualizado por outra requisição, o pedido não pôde ser criado naquele momento (por exemplo, o módulo está desativado) ou o pagamento não pôde ser verificado. A KOMOJU repete a notificação. O motivo está no log.
A URL do webhook mostra um erro no navegador: isso é normal. A URL aceita apenas requisições assinadas pela KOMOJU.
O pedido está em KOMOJU payment on hold ou Awaiting KOMOJU payment: leia as KOMOJU notes no bloco do pedido. Uma guia está aguardando pagamento, um pagamento aguarda captura no painel da KOMOJU, o valor ou a moeda não correspondiam, um cupom foi removido ou o pagamento chegou depois que o pedido foi cancelado.
O reembolso falha: leia a mensagem. A chave secreta do modo em que o pagamento foi feito pode estar ausente, o pagamento pode não ser reembolsável automaticamente (reembolse-o no painel da KOMOJU), a KOMOJU pode não reconhecer o pagamento com a chave configurada, ou só é possível um reembolso total para um pagamento convertido.
Desenvolvedores podem alterar a lista de moedas com o hook actionKomojuPSupportedCurrencies e a sessão de pagamento, por exemplo os métodos de pagamento, com o hook actionKomojuPSessionParams.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox KOMOJU Payment 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 ativado, as configurações do gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos da KOMOJU e os status de pedido Awaiting KOMOJU payment e KOMOJU payment on hold sempre são mantidos, então pedidos antigos ainda podem ser confirmados e reembolsados após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
KOMOJU é uma marca comercial de seu respectivo titular. Este módulo não é afiliado nem endossado pela KOMOJU.