VibeFox KOMOJU for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
HTTPS: seu site precisa de HTTPS e a KOMOJU deve conseguir acessar a URL do webhook.
KOMOJU account: você precisa da chave secreta (sk_live_... e, para testes, sk_test_...) e do token secreto de um webhook criado no painel KOMOJU (veja Configuração). A chave publicável não é necessária.
Store currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD ou VND. Para outras moedas, o método fica oculto.
VibeFox license key: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, vá a Plugins > Add New > Upload Plugin, escolha o ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_komoju_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > KOMOJU Payment > Manage, ou clique em Settings sob o nome do plugin na página de plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo e clique em Activate.
5. No painel KOMOJU, adicione um webhook com a URL e os eventos indicados nas configurações e copie seu token secreto (veja Configuração).
6. Insira a chave secreta e o token secreto de webhook de produção, e os de teste para o modo sandbox. Ative Enable/Disable e salve.
Configuração
Todas as configurações estão em uma página: WooCommerce > Settings > Payments > KOMOJU Payment. Acima dos campos, aparece KOMOJU Sandbox Mode is enabled. no modo de teste. Há avisos quando falta chave secreta no modo atual (o método fica oculto na finalização de compra) ou token secreto de webhook (as notificações KOMOJU são rejeitadas, então konbini e transferências nunca são confirmados), e quando a moeda não é aceita. Na lista de métodos, a KOMOJU aparece como precisando de configuração até o modo atual ter uma chave secreta, e exibe um selo de teste enquanto sandbox está ativo.
Geral
Enable/Disable: Enable KOMOJU Payment Gateway ativa ou desativa o método. Padrão: off.
Title: nome do método visto pelo cliente na finalização de compra. Padrão: KOMOJU Payment.
Description: texto sob o método 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 API de produção
Encontre as chaves no painel KOMOJU: a secreta em Settings > API keys, o token secreto de webhook em Settings > Webhooks (adicione primeiro a URL do webhook mostrada abaixo).
Live Secret Key: sua chave secreta KOMOJU de produção. Começa com sk_live_.
Live Webhook Secret Token: token secreto do webhook de produção. Verifica a assinatura de cada notificação.
Modo de teste
A KOMOJU usa o mesmo endereço API para teste e produção: a chave define o modo. Os pedidos guardam o modo em que foram pagos, para que reembolsos e verificações de status sempre usem sua chave.
Sandbox Mode: Enable test mode (use the test keys below, no real payments). Padrão: off. Quando ativo, a finalização de compra mostra Test mode acima da descrição.
Sandbox Secret Key: sua chave secreta KOMOJU de teste. Começa com sk_test_.
Sandbox Webhook Secret Token: token secreto do webhook de teste.
URL do webhook
O webhook informa sua loja sobre pagamentos, incluindo os adiados konbini e por transferência. No painel KOMOJU, em Settings > Webhooks, adicione a URL desta seção das configurações para produção e teste. Ela tem o formato https://your-site/wc-api/komoju_p_webhook/. Se seu site usa prefixo de idioma nas URLs, copie exatamente a das configurações. Depois copie o token secreto de cada webhook para Live Webhook Secret Token ou Sandbox Webhook Secret Token.
Selecione estes eventos:
Eventos de vencimento, cancelamento e falha só alteram o pedido para seu pagamento atual: um pagamento de tentativa anterior não pode cancelar um pedido sendo pago de outra forma. Webhooks sem assinatura válida são rejeitados. Os assinados com qualquer um dos tokens secretos são aceitos apenas para pedidos do mesmo modo. Sem webhook, cartões ainda são confirmados no retorno do cliente, mas konbini e transferências nunca são confirmados.
Avançado
Invoice Prefix: prefixo dos números de pedido enviados à KOMOJU. Se várias lojas usam a mesma conta, torne-o único por loja. Padrão: WC-.
Enable Logging: Log KOMOJU events and API calls em WooCommerce > Status > Logs, origem wcp_komoju_payment, sem chaves ou dados de clientes. Erros são sempre registrados. Padrão: off.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca exclui nada. Dados dos pedidos (IDs de pagamento KOMOJU) são sempre mantidos. Padrão: off.
Finalização de compra
O cliente escolhe o método (padrão KOMOJU Payment) e faz o pedido. O plugin cria uma sessão KOMOJU para o total na moeda do pedido e envia o cliente à página de pagamento KOMOJU. E-mail de cobrança, nome, endereços de cobrança e entrega e itens pedidos são enviados à KOMOJU. A página aparece em japonês, inglês ou coreano conforme o idioma do site (inglês para os demais). Ali o cliente escolhe o método. Os métodos oferecidos dependem da sua conta KOMOJU e da moeda do pedido.
Após pagar, o cliente volta à loja. O plugin lê a sessão pela API KOMOJU com a chave do modo do pedido. O pedido só é marcado como pago após confirmação KOMOJU: webhook assinado ou leitura da sessão no retorno. Se a KOMOJU estiver inacessível, o cliente vai à página de pedido recebido com 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.
Para konbini e transferências, o cliente recebe uma guia. O pedido fica em espera e é concluído quando ele paga e a KOMOJU envia o webhook. Se a guia vencer, o pedido é cancelado.
Se o pagamento não foi concluído, o cliente volta a Pay for order com The payment was not completed. You can try again or choose another payment method. Nova tentativa reutiliza a sessão aberta se o total não mudou. Uma sessão com total antigo é cancelada na KOMOJU; uma paga nesse intervalo confirma o pedido. Ao cancelar um pedido não pago (por você, pelo cliente ou pelo temporizador de reserva de estoque WooCommerce), sua sessão KOMOJU aberta também é cancelada, impedindo o pagamento.
Se a KOMOJU não consegue iniciar o pagamento, o cliente vê uma mensagem curta, como 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. Os detalhes são adicionados às notas do pedido e ao log.
O método funciona na finalização clássica, no bloco de Finalização de compra e em Pay for order. É compatível com WooCommerce High-Performance Order Storage (HPOS).
O plugin não tem formulário de cartão no site, cartões salvos ou assinaturas. Não restringe métodos, escolhidos na página KOMOJU. Não tem captura manual: pagamentos autorizados para ela precisam ser capturados no painel KOMOJU, e o pedido fica em espera até lá.
Pedidos e reembolsos
Status dos pedidos
Pending payment: o cliente foi enviado à KOMOJU e ainda não pagou, ou a KOMOJU ainda não confirmou.
Processing or Completed: a KOMOJU confirmou o pagamento. O WooCommerce define o status habitual de pedido pago. A nota mostra ID de pagamento KOMOJU, método e confirmação (webhook ou retorno). O ID da transação é o ID do pagamento KOMOJU e, na tela do pedido, leva ao pagamento no painel KOMOJU.
On hold: guia konbini ou de transferência emitido aguardando pagamento, ou pagamento aguardando captura no painel KOMOJU. O pedido também fica em espera se valor ou moeda divergirem, ou se a captura ocorreu após o cancelamento. A nota explica. Atenda o pedido ou reembolse o pagamento.
Failed: pagamento falhou. O cliente pode tentar novamente.
Cancelled: guia vencida ou pagamento cancelado.
Refunded: pagamento totalmente reembolsado pelo WooCommerce ou painel KOMOJU.
Se um segundo pagamento é capturado para um pedido já pago, o pedido não muda novamente. Uma nota pede que você reembolse no painel KOMOJU se for duplicado. Pedidos reembolsados nunca são reabertos.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via KOMOJU Payment. Há reembolsos totais e parciais. Usa-se a chave do modo em que o pedido foi pago, então sua chave secreta deve estar configurada. O plugin verifica antes o pagamento na KOMOJU e recusa valores acima do saldo reembolsável. Se a KOMOJU não pode reembolsar automaticamente (alguns métodos, como konbini, precisam dos dados bancários do cliente), mostra seu erro e nada é registrado: faça esses reembolsos no painel KOMOJU. Só se considera realizado após confirmação KOMOJU. Um reembolso bem-sucedido é adicionado às notas.
Para pagamentos convertidos pela KOMOJU para outra moeda (por exemplo konbini em JPY para pedido EUR), só há reembolso total pelo WooCommerce. Faça os parciais no painel KOMOJU.
Reembolsos no painel KOMOJU chegam por webhook e são registrados automaticamente no WooCommerce. Um total define Reembolsado. Os parciais do painel para pagamentos convertidos são apenas anotados: registre o valor correspondente no WooCommerce com "Refund manually".
Chave de licença
O plugin usa uma chave VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > KOMOJU Payment. Cole a chave em License key e clique em Activate. O bloco mostra status, por exemplo validade da licença e domínio. Use Check now para verificar novamente, Change key para outra chave e Remove key para removê-la do site. O link Manage licenses and domains in your account abre sua conta vibefox.net.
Uma chave funciona em um domínio. Removê-la do site não libera a vaga do domínio. Libere-a na sua conta vibefox.net.
Sem chave ativa, clientes não veem KOMOJU na finalização de compra. Se um pagamento iniciar mesmo assim, veem This payment method is not available. Please choose another one. Gerentes conectados ainda veem o método com (unlicensed — visible to admins only), para você configurar e testar antes de comprar a chave. Um lembrete aparece na página de plugins e nas páginas WooCommerce. Pedidos existentes não são afetados: pagamentos iniciados são confirmados e reembolsos funcionam.
Quando a licença vence, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente em segundo plano automaticamente.
Solução de problemas
KOMOJU não aparece na finalização de compra: confira licença ativa, Enable/Disable ligado e chave secreta do modo atual: Sandbox Secret Key no sandbox, Live Secret Key em produção. A moeda precisa ser aceita pela KOMOJU. As configurações avisam se algo falta.
O pagamento passou, mas o pedido continua Pending payment: o webhook não funciona. Confira no painel KOMOJU sua existência para o modo usado, URL exatamente igual às configurações e eventos selecionados. Confira o token no campo correto (Live Webhook Secret Token ou Sandbox Webhook Secret Token) e veja WooCommerce > Status > Logs, origem wcp_komoju_payment. Cartões também são confirmados no retorno do cliente; konbini e transferências só por webhook.
O webhook responde Failed to verify KOMOJU webhook signature: token ausente ou de outro webhook. A KOMOJU tenta notificar novamente.
O webhook responde Mode mismatch, ignored: foi assinado com o token do outro modo em relação ao pagamento. Use webhooks e tokens separados para produção e teste.
O webhook responde Order is busy, retry later ou Temporary error, retry later: outra requisição atualizava o pedido ou não foi possível verificar o pagamento naquele instante. A KOMOJU tenta notificar novamente.
Pedido em On hold: leia a nota. Guia aguardando pagamento, pagamento aguardando captura no painel KOMOJU, valor ou moeda divergentes, ou pagamento recebido após cancelamento.
Reembolso falha: leia a mensagem. Pode faltar a chave do modo original, o pagamento pode não permitir reembolso automático (use o painel KOMOJU), ou uma conversão pode permitir só reembolso total.
O bloco de licença mostra erro: siga a mensagem. Se a chave já está em outro domínio, libere uma vaga na conta vibefox.net e clique em Check now. Se o endereço mudou, clique em Check now para ativar no novo domínio. Se o servidor de licenças estiver inacessível, o plugin mantém o último status conhecido.
Desenvolvedores podem alterar as moedas com o filtro komoju_p_supported_currencies e a sessão, por exemplo os métodos de pagamento, com komoju_p_session_params.
Desinstalação
Desativar mantém todos os dados. Para remover, desative e exclua na página Plugins. Chave e status de licença sempre são removidos. Configurações e logs do gateway só são removidos se Delete data on uninstall estava ativo; caso contrário ficam para reinstalação. Pedidos existentes mantêm notas de pagamento e IDs de transação.
KOMOJU é uma marca de seu respectivo proprietário. Este plugin não é afiliado à KOMOJU nem endossado por ela.