VibeFox PayMongo for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Moeda: peso filipino (PHP). O método de pagamento fica oculto quando a moeda da loja, ou a moeda do pedido na página Pay for order, não é PHP.

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 WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_paymongo_payment_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > PayMongo > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Cole as suas chaves secretas da PayMongo, crie os webhooks e cole os segredos de assinatura deles (veja Configuração).

6. Selecione os métodos de pagamento, ative Enable/Disable e salve. Teste um pagamento com Test mode ligado e depois desligue-o.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > PayMongo. Acima dos campos, a página avisa quando a moeda 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ó são confirmados quando o cliente retorna), e mostra Test mode is on: no real payments are made. enquanto o modo de teste estiver ligado. Na lista de métodos de pagamento, a PayMongo aparece marcada como precisando de configuração até que o modo atual tenha uma chave secreta.

Geral

Enable/Disable: Enable PayMongo ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: PayMongo (Card, GCash, GrabPay, Maya).

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 pagamento da PayMongo. Selecione apenas os métodos ativados na sua conta PayMongo; do contrário, a PayMongo recusa a finalização de compra. 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). Novos pagamentos usam as chaves de teste. 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: ligado. Desligue 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_.

Webhook

O webhook informa à sua loja que um pagamento foi feito, inclusive quando o cliente fecha o navegador depois de pagar. Crie um webhook no painel da PayMongo (ou pela API da PayMongo) para cada modo, de teste e de produção, com a URL exibida nesta seção das configurações. Ela tem este formato: https://your-site/?wc-api=paymongo_p_webhook.

Selecione estes eventos:

Copie o segredo de assinatura (whsk_...) de cada webhook para Test webhook secret ou Live webhook secret. Webhooks sem assinatura válida são recusados, e o modo do evento precisa corresponder ao modo da assinatura. Cada evento é verificado novamente pela API da PayMongo antes de o pedido ser alterado. A PayMongo envia os eventos de toda a conta para cada webhook; eventos de pagamentos que não foram criados por esta loja são ignorados. Sem o webhook, os pagamentos só são confirmados quando o cliente volta à sua loja.

Pedidos

Status do pedido após o pagamento: o status do pedido definido após um pagamento bem-sucedido. O status é definido de imediato, sem uma segunda mudança de status.

Avançado

Debug log: Log API calls and webhook events grava esses eventos em WooCommerce > Status > Logs, origem wcp_paymongo_payment_gateway. Erros são sempre registrados. Chaves e dados dos clientes nunca são registrados. Padrão: desativado.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. Os IDs da PayMongo salvos nos pedidos são mantidos, porque são necessários para reembolsos e contabilidade. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão, PayMongo (Card, GCash, GrabPay, Maya)) e faz o pedido. No modo de teste, a finalização de compra mostra Test mode: no real payment will be made. O plugin cria uma sessão de checkout da PayMongo pelo total do pedido em PHP, com uma linha Order # e o número do pedido, e envia o cliente à página de pagamento da PayMongo. Nome, e-mail, telefone e endereço de cobrança do cliente são repassados à PayMongo. Lá, o cliente escolhe um dos métodos selecionados e paga.

O método de pagamento só é exibido para pedidos de pelo menos ₱100,00. Um total menor não pode ser pago com a PayMongo.

Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago quando a PayMongo confirma: o plugin consulta a API da PayMongo sobre o pagamento quando o cliente retorna e quando o webhook chega. Se a PayMongo ainda estiver processando o pagamento ou não puder ser acessada, o cliente chega mesmo assim à página de pedido recebido, e o webhook concluirá o pedido depois.

Se o cliente cancelar na página da PayMongo ou não concluir o pagamento, ele chega à página Pay for order com a mensagem 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 pedido continua sem pagamento. Uma nova tentativa verifica primeiro a anterior: se ela tiver sido paga nesse meio tempo, o pedido é concluído sem um novo pagamento; caso contrário, o link de checkout PayMongo anterior expira, então o cliente não consegue pagar duas vezes. Enquanto o pagamento anterior ainda estiver sendo processado, 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 vê 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 é adicionado às notas do pedido.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin 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, nem parcelamentos, nem autorização e captura separadas.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado à PayMongo e ainda não pagou, ou a PayMongo ainda não confirmou o pagamento. Uma nota registra cada sessão de checkout da PayMongo criada para o pedido. Enquanto a PayMongo processa um pagamento, uma nota informa isso.

Processing ou Completed: o pagamento foi confirmado. O status segue Order status after payment. A nota do pedido mostra o pagamento da PayMongo, o valor, o método e o modo. O ID da transação é o ID de pagamento da PayMongo (pay_...). A tela do pedido mostra a sessão de checkout, a intenção de pagamento e o modo da PayMongo abaixo do endereço de cobrança.

On hold: o valor ou a moeda pagos diferem do pedido (nota amount/currency mismatch); ou um pagamento foi feito em modo de teste enquanto a loja está em produção, então nenhum dinheiro foi recebido; ou o pagamento chegou depois que o pedido foi cancelado, por exemplo pelo tempo limite de reserva de estoque. A nota do pedido explica. Verifique o pedido e processe-o ou reembolse o pagamento.

Failed: um webhook payment.failed assinado informou que a última tentativa de pagamento de um pedido pendente falhou. A nota mostra o código e a mensagem de falha da PayMongo. O cliente pode pagar de novo.

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 cancelado ou reembolsado que já tinha sido pago nunca é reaberto.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via PayMongo (Card, GCash, GrabPay, Maya) (o botão mostra o título do seu método de pagamento). Reembolsos totais e parciais são suportados. O reembolso é enviado com a chave secreta do modo em que o pagamento foi feito (teste ou produção), então essa chave precisa estar configurada. Se a PayMongo não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID e o status do reembolso da PayMongo.

Reembolsos feitos no painel da PayMongo não são copiados para o WooCommerce. Reembolse a partir do pedido no WooCommerce ou crie um reembolso manual no WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > PayMongo. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status de novo, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a 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. Os gerentes da loja que estiverem conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

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á ligado, se o modo atual tem uma chave secreta (Test secret key no modo de teste, Live secret key no modo de produção), se a moeda da loja é PHP e se o total do pedido é de pelo menos ₱100,00. Desenvolvedores podem alterar o mínimo com o filtro paymongo_p_minimum_amount.

O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não está funcionando e o cliente não voltou à loja. No painel da PayMongo, confira se existe um webhook no modo que você usa, se a URL dele é exatamente a exibida nas configurações e se os três eventos estão selecionados. Confira se o segredo de assinatura 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. Confira se cada webhook pertence ao modo correto.

O webhook responde Temporary error: o pagamento não pôde ser verificado pela API da PayMongo, ou o pedido estava sendo processado por outra requisição ao mesmo tempo. A PayMongo repete o webhook automaticamente.

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

O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou consulte WooCommerce > Status > Logs, origem wcp_paymongo_payment_gateway. Uma chave secreta incorreta resulta na 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 a finalização de compra; 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 deixa o pedido em espera 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.

O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos diferiam do pedido, o pagamento era de teste ou chegou depois de o pedido ser cancelado. Processe o pedido ou reembolse o pagamento.

O reembolso falha com uma 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. Informe-a e tente novamente.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway, os dados temporários e os logs só são removidos se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e IDs da PayMongo.

A PayMongo é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela PayMongo.