VibeFox PayMongo 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.

Moeda: peso filipino (PHP). A PayMongo só aparece na finalização de compra para carrinhos em PHP. Se a moeda padrão da sua loja não for PHP, a página de configurações avisa, e os clientes precisam mudar para PHP para ver a PayMongo.

Conta PayMongo: você precisa das chaves de API secretas da sua conta PayMongo e de um webhook para cada modo (veja Configuração). Só as chaves secretas (sk_test_..., sk_live_...) e os segredos de assinatura dos webhooks (whsk_...) são usados. As chaves públicas não são necessárias, porque a página de pagamento é hospedada pela PayMongo. Os métodos de pagamento que você oferecer precisam estar ativados na sua conta PayMongo.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No back office, acesse 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 encontre depois VibeFox PayMongo Payment Gateway na lista de módulos e clique em Configure.

3. Insira a 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. Cole as chaves secretas da PayMongo, crie os webhooks na PayMongo e cole os segredos de assinatura deles (veja Configuração).

5. Selecione os métodos de pagamento, ative Enable/Disable e clique em Save. Teste um pagamento com Test mode ativado e depois desative.

Ao instalar, o módulo cria dois status de pedido, Awaiting PayMongo payment e PayMongo payment on hold. Em Payment > Preferences, verifique se o módulo está permitido para o peso filipino, os países dos seus clientes e os grupos de clientes.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a moeda padrão da loja não é PHP, quando o modo atual não tem chave secreta (então a PayMongo não aparece na finalização de compra) ou não tem segredo de webhook (então os pagamentos são confirmados apenas quando o cliente volta à sua loja), e mostra Test mode is on: no real payments are made. enquanto o modo de teste estiver ativo.

PayMongo

Enable/Disable: Enable PayMongo 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 salvo no pedido. Padrão: PayMongo (Card, GCash, GrabPay, Maya). Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: os métodos oferecidos na página de checkout da PayMongo. Selecione apenas os métodos ativados na sua conta PayMongo; do contrário a PayMongo recusa o checkout. Se nenhum for selecionado, são usados os padrões. Padrão: Cards, GCash, GrabPay and Maya.

Chaves de API

Copie as chaves secretas em PayMongo Dashboard > Developers > API keys. As chaves públicas não são necessárias. Cada chave deve começar com o prefixo esperado. Um valor com prefixo errado não é salvo: a página mostra que o campo must start with o prefixo e que The previous value was kept.

Test mode: Enable test mode (no real payments). Os novos pagamentos usam as chaves de teste. Os pagamentos feitos antes mantêm o modo em que foram feitos, então as verificações de status e os reembolsos usam a chave correspondente. Padrão: ativado. Desative para receber pagamentos reais.

Test secret key: a chave secreta do modo de teste. Começa com sk_test_.

Test webhook secret: o segredo de assinatura do webhook do modo de teste. Começa com whsk_.

Live secret key: a chave secreta do modo de produção. Começa com sk_live_.

Live webhook secret: o segredo de assinatura do webhook do modo de produção. Começa com whsk_.

Chaves e segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo.

Clear saved secrets: marque uma chave ou um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Webhook

O webhook informa à sua loja que um pagamento foi feito, também quando o cliente fecha o navegador depois de pagar. Crie um webhook no painel da PayMongo (ou pela API da PayMongo) para cada modo, teste e produção, com a URL mostrada em Webhook URL nesta seção. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_paymongo_payment_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram.

Selecione estes eventos (também listados nesta seção):

Copie o segredo de assinatura (whsk_...) de cada webhook em Test webhook secret ou Live webhook secret. Webhooks sem assinatura válida são rejeitados. A assinatura é verificada com o segredo do próprio modo, e o modo do evento precisa coincidir com ele, de modo que um webhook de teste nunca confirma um pagamento real. Cada evento é verificado novamente pela API da PayMongo com a chave secreta do modo do pagamento antes que um pedido seja criado ou alterado. A PayMongo envia os eventos de toda a conta para cada webhook; eventos de pagamentos que não foram iniciados nesta loja são ignorados. Sem o webhook, um pedido só é criado quando o cliente volta à loja depois de pagar.

Pedidos

Order status after payment: o status do pedido definido após um pagamento bem-sucedido.

Pagamentos ainda em processamento ficam em Awaiting PayMongo payment. Divergências de valor ou moeda e pagamentos de teste em uma loja em produção sempre vão para PayMongo payment on hold.

Avançado

Debug log: registra as chamadas à API da PayMongo e os eventos de webhook em logs/paymongo_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo com a chave desligada. Chaves e dados de clientes nunca são registrados. Padrão: desativado.

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

Delete data on uninstall: quando ativado, desinstalar o módulo exclui as configurações e o log. Os IDs da PayMongo salvos nos pedidos, os reembolsos e os status de pedido do módulo são sempre mantidos, porque são necessários para reembolsos e contabilidade. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão PayMongo (Card, GCash, GrabPay, Maya)) e vê a descrição dele. No modo de teste, a finalização de compra também mostra Test mode: no real payment will be made. A PayMongo só é oferecida para carrinhos em PHP com total de pelo menos ₱100,00.

Depois de confirmar, o módulo cria uma Checkout Session da PayMongo pelo total do carrinho em PHP, com uma linha Cart # e o número do carrinho, e envia o cliente à página de checkout da PayMongo. Nome, e-mail, telefone e endereço de cobrança do cliente são passados à PayMongo. Lá, o cliente escolhe um dos métodos selecionados e paga. Neste momento ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a PayMongo confirma: o módulo consulta a API da PayMongo sobre o pagamento quando o cliente retorna e quando o webhook chega. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your PayMongo payment has been received. Se a PayMongo ainda estiver processando o pagamento quando o cliente retorna, o pedido é criado em Awaiting PayMongo payment e a página mostra PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Se esse pagamento falhar depois, a página mostra Your PayMongo payment was not completed. Please contact us about this order. Se a PayMongo não puder ser acessada quando o cliente retorna, uma página Payment confirmation pede que ele não pague novamente e mostra um botão Check again; o webhook cria o pedido assim que chegar.

Se o cliente cancelar na página da PayMongo ou não concluir o pagamento, ele volta à finalização de compra com You cancelled the PayMongo payment. You can try again or choose another payment method. ou Your PayMongo payment was not completed. You can try again or choose another payment method. O carrinho é mantido. Uma nova tentativa verifica primeiro a anterior: se ela tiver sido paga nesse meio tempo, o pedido é criado sem um novo pagamento; caso contrário, o link de checkout anterior da PayMongo expira, de modo que o carrinho não pode ser pago duas vezes. Enquanto o pagamento anterior ainda estiver em processamento, o cliente vê Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.

Se a PayMongo não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo The payment could not be started. Please try again or choose another payment method. ou PayMongo could not be reached. Please try again in a moment. O motivo técnico é gravado no log.

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 pagamentos únicos na página da PayMongo. Não há campos de cartão na sua própria página de finalização de compra, nem cartões salvos, assinaturas ou pagamentos recorrentes, parcelamentos, nem autorização e captura separadas.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado à PayMongo e ainda não pagou, ou a PayMongo ainda não confirmou o pagamento. Só existe o carrinho.

Payment accepted or Delivered: o pagamento foi confirmado. O status segue Order status after payment. O pagamento é registrado com o ID de pagamento da PayMongo (pay_...) como ID da transação, e uma nota mostra o pagamento, o valor, o método, o modo e como foi confirmado (webhook ou retorno).

Awaiting PayMongo payment: o cliente voltou enquanto a PayMongo ainda processava o pagamento. O pedido passa ao status de pago quando a PayMongo confirma.

PayMongo payment on hold: o valor ou a moeda pagos diferem do total do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou); ou um pagamento foi feito em modo de teste enquanto a loja estava em modo de produção, então nenhum dinheiro foi recebido e nenhum pagamento é registrado; ou o pagamento chegou depois que o pedido havia sido cancelado. A nota explica. Verifique o pedido e processe-o ou reembolse o pagamento.

Payment error: um webhook payment.failed assinado informou que a última tentativa de pagamento de um pedido em Awaiting PayMongo payment falhou. A nota mostra o código e a mensagem de falha da PayMongo. Se o mesmo pagamento for bem-sucedido depois, o pedido passa ao status de pago.

Refunded: o pagamento foi reembolsado integralmente pelo módulo.

Se chegar um segundo pagamento para um pedido que já está pago, por exemplo por um link de checkout antigo, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no painel da PayMongo. Um pedido que foi pago e depois cancelado ou reembolsado nunca é reaberto.

Bloco PayMongo payment

A página do pedido mostra um bloco PayMongo payment com o ID e o método do pagamento da PayMongo, o payment intent, o checkout, o modo, o status, o valor pago e o valor reembolsado, um selo Test mode para pagamentos de teste, as notas da PayMongo do pedido e o histórico de reembolsos.

Reembolsos

No bloco PayMongo payment, informe o valor (é preenchido o valor ainda não reembolsado), opcionalmente um motivo, e clique em Refund via PayMongo. Confirme a pergunta Refund this amount through PayMongo? This cannot be undone. São aceitos reembolsos totais e parciais, com no máximo duas casas decimais. Você precisa do direito de editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são limitados ao valor que a PayMongo efetivamente cobrou, então, depois de 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 secreta do modo em que o pagamento foi feito (teste ou produção), por isso essa chave precisa estar configurada. O motivo que você informar é enviado à PayMongo como nota do reembolso. Se a PayMongo não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID e o status do reembolso na PayMongo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.

O módulo não cria notas de crédito. Os botões padrão de reembolso da PrestaShop na página do pedido não devolvem dinheiro pela PayMongo. Reembolsos feitos no painel da PayMongo não são copiados para a PrestaShop. Faça o reembolso pelo bloco do pedido ou atualize o pedido manualmente.

Chave de licença

O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox PayMongo Payment Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox PayMongo Payment Gateway > 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 deles ficam a linha Product: presta-payment-paymongo e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do 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 de 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 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 vibefox.net.

Sem uma chave ativa, a PayMongo 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á logado no 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 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 os reembolsos funcionam.

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 inserida e depois uma vez por semana. Não é necessário 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 PayMongo não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o modo atual tem uma chave secreta (Test secret key no modo de teste, Live secret key no modo de produção), se o carrinho está em PHP e se o total é de pelo menos ₱100,00. 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 e o cliente não voltou à loja. No painel da PayMongo, verifique se existe um webhook no modo que você usa, se a URL dele é exatamente a mostrada em Webhook URL e se os três eventos estão selecionados. Verifique se o segredo de assinatura dele está no campo correspondente (Test webhook secret ou Live webhook secret).

O webhook responde Invalid signature: o segredo de assinatura desse modo está ausente ou pertence a outro webhook. Cole o segredo de assinatura do webhook no campo do seu modo.

O webhook responde Mode mismatch: um evento de teste foi assinado como produção, ou o contrário. Verifique se cada webhook pertence ao modo certo.

O webhook responde Temporary error: não foi possível verificar o pagamento pela API da PayMongo, por exemplo porque a chave secreta do modo do pagamento está ausente. A PayMongo repete o webhook automaticamente.

O webhook responde Busy, retry: o pedido estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A PayMongo repete o webhook automaticamente. O motivo está no Log.

O webhook responde Ignored: o evento pertence a um pagamento que não foi iniciado nesta loja, ou a outro modo. Nada é alterado.

A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da PayMongo.

O valor não foi salvo: uma chave foi colada no campo errado. Chaves secretas começam com sk_test_ ou sk_live_, segredos de webhook com whsk_.

O cliente vê um erro ao escolher a PayMongo: veja o campo Log na página do módulo. Uma chave secreta errada gera a mensagem de que o método de pagamento está temporariamente indisponível. Um método de pagamento não ativado na sua conta PayMongo faz a PayMongo recusar o checkout; remova-o de Payment methods.

Pagamentos de teste em uma loja em produção: um pagamento de teste recebido enquanto a loja está em modo de produção coloca o pedido em PayMongo payment on hold com uma nota informando que nenhum dinheiro foi recebido. Pagamentos reais são sempre reconhecidos, inclusive depois de voltar ao modo de teste, e são reembolsados com a chave de produção.

Pedido em PayMongo payment on hold após o pagamento: leia as notas no bloco PayMongo payment (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.

Reembolso falha com mensagem sobre o modo: o pagamento foi feito em modo de teste ou de produção, e a chave secreta desse modo não está configurada. Insira-a e tente novamente.

Desenvolvedores podem alterar os dados da Checkout Session com o hook actionPaymongoPCheckoutSessionData.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox PayMongo 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 ativado, as configurações e o log são excluídos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os IDs da PayMongo dos pedidos, os reembolsos e os status de pedido Awaiting PayMongo payment e PayMongo payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

PayMongo é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela PayMongo.