VibeFox GMO for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.

Moeda: iene japonês (JPY). O GMO-PG cobra apenas em ienes, por isso o método de pagamento só é exibido quando a moeda do carrinho é JPY. Adicione o JPY em International > Localization > Currencies se a sua loja ainda não o tiver.

Conta no GMO Payment Gateway: um contrato de comerciante com o GMO-PG com Link Type Plus. Você precisa do Shop ID, da Shop password e do Config ID do Link Type Plus (設定ID) dos ambientes de teste e/ou de produção, e da notificação do resultado (結果通知) ativada no console da loja do GMO-PG (veja Configuração). O Site ID e a Site password não são usados.

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 upload terminar, clique em Configure, ou encontre depois o VibeFox GMO Payment Gateway na lista de módulos e clique em Configure.

3. Informe sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).

4. Informe o Shop ID, a Shop password e o Config ID dos ambientes de teste e/ou de produção e escolha o Environment.

5. No console da loja do GMO-PG, ative 結果通知 (notificação do resultado) e defina a URL de notificação exibida nas configurações (veja Configuração).

6. Ative Enable/Disable e clique em Save. Faça um pagamento de teste no ambiente de teste e depois mude o Environment para produção.

Ao ser instalado, o módulo cria o status de pedido GMO-PG payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; o JPY precisa continuar permitido.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox GMO Payment Gateway > Configure. Cada botão Save salva a página inteira. Acima dos campos, a página avisa quando a moeda padrão da loja não é JPY e quando o Shop ID, a Shop password ou o Config ID do ambiente atual está faltando (nesse caso, o método de pagamento fica oculto na finalização de compra). Ela também mostra qual ambiente está ativo: TEST — payments go to pt01.mul-pay.jp with the test credentials, no real money is charged. ou PRODUCTION — payments go to p01.mul-pay.jp. Os espaços em volta das credenciais são removidos ao salvar.

GMO Payment Gateway — Credit Card

Enable/Disable: Enable GMO Payment Gateway — Credit Card liga ou desliga o método de pagamento. Padrão: desligado.

Title: o nome do método de pagamento exibido na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit card. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: You will be redirected to the secure GMO Payment Gateway page to pay by credit card.

Conta do GMO-PG

O Shop ID e a Shop password ficam no console do GMO-PG em Shop management > Shop information, e o Config ID em Link Type Plus > Settings (設定ID). Os ambientes de teste e de produção têm credenciais diferentes.

Environment: qual ambiente do GMO-PG recebe os novos pagamentos.

Production Shop ID: o Shop ID do ambiente de produção.

Production Shop password: a Shop password do ambiente de produção.

Production Config ID: o config ID do Link Type Plus (設定ID) registrado no console do GMO-PG.

Test Shop ID: o Shop ID do ambiente de teste.

Test Shop password: a Shop password do ambiente de teste.

Test Config ID: o config ID do Link Type Plus (設定ID) do ambiente de teste.

As senhas salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo apenas se quiser alterá-lo.

Clear saved passwords: marque uma senha e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Payment

Capture: quando o cartão é cobrado.

Order status after payment: o status de um pedido pago.

Notificações de pagamento (結果通知)

A notificação do resultado informa à sua loja que um pagamento foi feito. Ela é obrigatória. No console do GMO-PG, ative 結果通知 (notificação do resultado) e defina a URL exibida em Notification URL nesta seção. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_gmo_payment/notify, possivelmente com um código de idioma como /ja/. Copie a URL exatamente como as configurações a mostram. Ela precisa estar acessível pela Internet; o modo de manutenção não a bloqueia.

As notificações do GMO-PG não são assinadas, então o módulo nunca confia no conteúdo delas. A notificação precisa vir de um dos Shop IDs configurados e se referir a um pagamento criado por esta loja, no ambiente em que o pagamento foi feito. Em seguida, o módulo pede ao GMO-PG a transação (SearchTrade) com a sua Shop password e altera o carrinho ou o pedido somente com base nessa resposta. Uma notificação que não corresponde a uma transação real não altera nada. Transações não criadas pela loja, por exemplo as feitas no console do GMO-PG, são confirmadas e ignoradas. Quando o módulo não consegue verificar uma notificação, ele responde de modo que o GMO-PG a envie novamente (o GMO-PG tenta até 5 vezes).

Sem a notificação, o pedido só é criado quando o cliente volta à loja depois de pagar.

Advanced

Debug log: grava as requisições à API e as notificações em logs/gmo_pg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com a chave desligada. Senhas e dados dos clientes são mascarados. Padrão: desligado.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ligada, ao desinstalar o módulo as configurações do gateway e o log são removidos. Os dados dos pedidos (GMO OrderID, IDs de transação) são sempre mantidos. Padrão: desligado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Credit card) e vê a sua descrição. No ambiente de teste, o selo TEST — GMO-PG test environment, no real charges. aparece acima dele. Depois da confirmação, o módulo cria um pagamento GMO-PG Link Type Plus para o total do carrinho, arredondado para ienes inteiros, e envia o cliente à página de pagamento do GMO-PG. Lá o cliente paga com cartão de crédito. O 3-D Secure 2.0 é gerenciado pelo GMO-PG, e o e-mail do cliente é repassado ao GMO-PG para o 3-D Secure. A página de pagamento abre em japonês, chinês ou inglês, conforme o idioma do cliente. O pagamento aparece no GMO-PG com PS- e o número do carrinho. Nenhum outro dado do cliente é enviado. Neste ponto, ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O resultado assinado é verificado com a Shop password do ambiente do pagamento, e o pedido só é marcado como pago depois que o GMO-PG confirma: por uma solicitação SearchTrade do servidor quando o cliente retorna, ou pela notificação do resultado. Os dois usam a mesma lógica, então o pedido nunca é criado duas vezes. Em seguida, o cliente vê a página padrão de confirmação do pedido. Se o GMO-PG ainda não tiver confirmado o pagamento, aparece uma página Payment confirmation com a mensagem Your card payment is being confirmed by GMO Payment Gateway. You will receive an e-mail as soon as it is confirmed. e um botão Check again; a notificação cria o pedido assim que chegar.

Se o cartão for recusado ou o pagamento falhar na página do GMO-PG, o cliente volta à finalização de compra com a mensagem The card payment was declined or could not be completed. Please try again or use another card.. Se o cliente sair da página do GMO-PG sem pagar, a mensagem é The payment was not completed. You can try again or choose another payment method.. O carrinho é mantido. Cada nova tentativa cancela o link de pagamento anterior não pago. Se, nesse meio-tempo, o link anterior já tiver sido pago, o pedido é criado a partir desse pagamento e nenhum novo link é gerado.

Totais de carrinho de 1 a 9.999.999 JPY podem ser pagos. Totais maiores ocultam o método de pagamento. Se o pagamento não puder ser iniciado, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Card payment could not be started. Please try again or choose another payment method., e o motivo é registrado no log.

A notificação e o retorno funcionam mesmo com a loja em modo de manutenção e não são bloqueados pela restrição de países da sua loja.

O módulo aceita pagamentos com cartão de crédito somente em JPY, sempre na página do GMO-PG. Não oferece outros métodos de pagamento do GMO-PG, várias moedas, cartões salvos ou cadastro de membro no GMO-PG, assinaturas ou cobranças recorrentes nem formulário de cartão no seu site.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado ao GMO-PG e não pagou, ou o GMO-PG ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted ou Delivered: o pagamento foi confirmado. O status segue Order status after payment. O pagamento é registrado com o TranID do GMO-PG como ID da transação, e uma nota mostra o valor, o status do GMO-PG, a transação e como foi confirmado (notificação ou retorno).

GMO-PG payment on hold (autorizado): com Authorize only (仮売上), o valor foi autorizado. Capture-o com Capture payment (GMO-PG) ou no console do GMO-PG antes que a autorização expire. Depois da captura, o pedido passa a Payment accepted ou Delivered. Se a autorização for cancelada no GMO-PG, o pedido passa a Canceled.

GMO-PG payment on hold após o pagamento: o GMO-PG informou um valor diferente do total do carrinho, ou o carrinho não estava em JPY. A nota explica isso, e o pagamento é registrado pelo valor que o GMO-PG de fato cobrou. Verifique o pedido e atenda-o ou reembolse o pagamento.

Refunded: o pagamento foi totalmente reembolsado pelo módulo. O reembolso total de uma autorização que nunca foi capturada define o pedido como Canceled.

Se chegar um segundo pagamento para um carrinho cujo pedido já está pago ou fechado, o pedido não é alterado. Uma nota pede que você reembolse o duplicado no console do GMO-PG.

Bloco GMO Payment Gateway

A página do pedido mostra um bloco GMO Payment Gateway com o GMO OrderID, o Transaction ID, o status (com o status do GMO-PG), Paid / refunded, um selo TEST para pagamentos de teste, o histórico de reembolsos e as GMO-PG notes do pedido. A captura e os reembolsos exigem a permissão para editar pedidos; o acesso às páginas de Módulos não é necessário.

Captura

Capture payment (GMO-PG) aparece no bloco de um pedido em espera que foi apenas autorizado. Confirme Capture the authorized GMO-PG payment?. O módulo verifica a transação no GMO-PG e cobra o valor autorizado. Se a transação não estiver mais autorizada, por exemplo porque já foi capturada no console do GMO-PG, uma nota mostra o status atual e o pedido o acompanha.

Reembolsos

No bloco, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via GMO-PG. Confirme Refund this amount through GMO-PG?. Há suporte a reembolsos totais e parciais, em ienes inteiros. O limite é o valor que o GMO-PG efetivamente cobrou e ainda retém, não o total do pedido. Reembolsar todo o valor restante cancela a transação no GMO-PG, e cabe ao GMO-PG decidir se é um cancelamento (void) ou uma devolução. Um reembolso parcial reduz o valor da transação. O reembolso é enviado ao ambiente em que o pagamento foi feito, por isso o Shop ID e a Shop password desse ambiente precisam estar configurados. Se o GMO-PG não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é incluído no histórico de reembolsos e nas notas. Um reembolso total define o pedido como Refunded; um reembolso parcial não altera o status.

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 pelo GMO-PG.

Reembolsos e cancelamentos feitos no console do GMO-PG chegam pela notificação do resultado e são incluídos nas notas. O status do pedido e as notas de crédito não são alterados automaticamente, exceto no caso de uma autorização cancelada no GMO-PG. Atualize-os manualmente, se necessário.

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 GMO Payment Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox GMO Payment Gateway > 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 novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-gmo 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 do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o pagamento com cartão GMO-PG não é exibido 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. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e capturas e 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 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

O cartão de crédito não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se a moeda do carrinho é JPY e se o ambiente atual tem Shop ID, Shop password e Config ID preenchidos. Totais de carrinho acima de 9.999.999 JPY não podem ser pagos com cartão. A página de configurações mostra um aviso quando a moeda ou as credenciais estão erradas. Em Payment > Preferences, verifique se o módulo está permitido para JPY, para o país do cliente e para o grupo do cliente.

O pagamento foi aprovado, mas nenhum pedido foi criado: a notificação do resultado não está funcionando. No console da loja do GMO-PG do ambiente que você usa, verifique se 結果通知 está ativada e se a URL é exatamente a exibida em Notification URL. Verifique se o Shop ID e a Shop password desse ambiente estão preenchidos, porque o módulo verifica cada notificação com eles. Ative o Debug log e veja o campo Log na página do módulo. O pedido também é criado quando o cliente volta à loja depois de pagar.

O log mostra Notification rejected: unknown ShopID: a notificação veio de uma loja cujo Shop ID não está nas configurações. Informe o Shop ID desse ambiente.

O log mostra Notification ignored: OrderID is not a payment of this store: a transação não foi criada por esta loja, por exemplo foi feita no console do GMO-PG. Nada precisa ser feito.

O log mostra que o carrinho foi pago em outro ambiente: pagamentos de teste e de produção são mantidos separados. Uma notificação de teste nunca confirma um pagamento de produção, e vice-versa.

O log mostra Cannot create the order: the module is disabled: o módulo foi desativado enquanto um pagamento estava sendo confirmado. Ative-o; o GMO-PG enviará a notificação novamente.

O cliente vê um erro ao escolher o pagamento com cartão: ative o Debug log e veja o campo Log. O log mostra o código de erro do GMO-PG (ErrCode, ErrInfo). Um Shop ID, uma Shop password ou um Config ID errados são o motivo mais comum. GMO Payment Gateway accepts payments in Japanese Yen (JPY) only. significa que o carrinho não está em JPY.

O pedido está em GMO-PG payment on hold: leia as notas no bloco GMO Payment Gateway. O pedido foi apenas autorizado e aguarda a captura, ou o valor pago era diferente do carrinho.

O reembolso ou a captura falha: leia a mensagem no bloco. O pedido pode ter sido pago no outro ambiente, cujo Shop ID e senha não estão configurados; a transação pode já ter sido cancelada no GMO-PG; ou o valor pode exceder o saldo restante da transação. The order is being updated by GMO-PG right now. Try again in a moment. significa que uma notificação estava sendo processada ao mesmo tempo.

O bloco mostra You do not have permission to refund orders.: o seu perfil de funcionário não tem permissão para editar pedidos. Peça a um administrador que a conceda.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox GMO Payment Gateway 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 ligada, as configurações do gateway e o log são removidos. Se estiver desligada, todas as configurações são mantidas para uma reinstalação futura. As transações e os reembolsos do GMO-PG e o status de pedido GMO-PG payment on hold são sempre mantidos, portanto pedidos pagos antes podem ser capturados e reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

GMO Payment Gateway é uma marca de seu respectivo titular. Este módulo não é afiliado nem endossado pelo GMO Payment Gateway.