VibeFox Paystack for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou posterior.
WooCommerce: 7.0 ou posterior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou posterior.
Moeda: o pedido precisa estar em uma moeda que a Paystack aceita: NGN, USD, GHS, ZAR, KES, XOF, EGP ou RWF, conforme ativado na sua conta Paystack. Em outras moedas, o método de pagamento fica oculto. Em XOF e RWF, a Paystack aceita apenas valores inteiros.
Conta Paystack: você precisa das chaves secretas da sua conta Paystack: a chave secreta de teste (sk_test_...) e/ou a chave secreta de produção (sk_live_...). As chaves públicas (pk_...) não são necessárias, porque o pagamento é feito na página hospedada pela Paystack. No painel da Paystack, você também define a URL de webhook da sua loja (veja Configuração). O seu site precisa estar acessível pela internet para receber os webhooks.
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_paystack_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Paystack > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Informe 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 do painel da Paystack e defina a URL de webhook no painel da Paystack (veja Configuração).
6. Ative Enable/Disable e salve. Mantenha Test Mode ativo até fazer um pagamento de teste e, depois, desmarque-o para aceitar pagamentos reais.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Paystack. Acima dos campos, uma caixa de status mostra o modo: Modo de teste: nenhum dinheiro real é cobrado. ou Modo de produção: pagamentos reais são aceitos. Ela também avisa quando a chave secreta do modo atual está vazia, quando uma chave pública (pk_...) foi informada em um campo de chave secreta, quando o modo de produção tem uma chave de teste (sk_test_...) ou o modo de teste tem uma chave de produção (sk_live_...), e quando a Paystack não aceita a moeda da sua loja. Enquanto houver um problema com a chave, o método de pagamento fica oculto na finalização da compra. Na lista de métodos de pagamento, a Paystack aparece como pendente de configuração até que o modo atual tenha uma chave secreta.
Finalização da compra
Enable/Disable: Enable Paystack Payment 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 da compra. Padrão: Paystack.
Description: o texto exibido abaixo do método de pagamento na finalização da compra. Padrão: Pay securely using your debit card, credit card, or bank account via Paystack.
Chaves de API
Copie as chaves secretas do painel da Paystack, na página Settings > API Keys & Webhooks. A seção traz um link para ela.
Test Mode: Enable Test Mode usa a chave secreta de teste para os novos pagamentos, e nenhum dinheiro real é cobrado. Desmarque para aceitar pagamentos reais com a chave secreta de produção. Pagamentos feitos no outro modo continuam usando a chave do próprio modo para verificação e reembolsos. Padrão: ativado.
Test Secret Key: a sua chave secreta de teste da Paystack. Ela começa com sk_test_.
Live Secret Key: a sua chave secreta de produção da Paystack. Ela começa com sk_live_.
Webhook
O webhook informa à sua loja que um pagamento foi feito, mesmo quando o cliente não volta para a loja. No painel da Paystack, na página Settings > API Keys & Webhooks, defina a URL mostrada nesta seção tanto como Test Webhook URL quanto como Live Webhook URL. Ela tem este formato: https://your-site/wc-api/paystack_p_webhook/. Copie a URL exatamente como as configurações a mostram.
A Paystack assina cada webhook com a sua chave secreta, então nada mais precisa ser configurado. Os webhooks de teste são verificados com a chave secreta de teste, e os de produção com a chave secreta de produção. Webhooks sem assinatura válida são rejeitados. O plugin usa o evento charge.success:
Os demais eventos recebem a resposta OK e são ignorados. Sem o webhook, um pedido só é confirmado quando o cliente volta para a loja depois de pagar. Transferências bancárias e pagamentos USSD concluídos depois são confirmados apenas pelo webhook.
Pedidos
Autocomplete Order: Automatically mark orders as completed after successful payment. Quando marcada, os pedidos pagos passam a Concluído em vez de Processing, com uma única mudança de status e um único e-mail ao cliente. Padrão: desativado.
Avançado
Debug log: Log Paystack events and API calls for debugging grava os detalhes em WooCommerce > Status > Logs, origem wcp_paystack_payment. Erros são sempre registrados. Chaves e dados de clientes nunca são registrados. Padrão: desativado.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados de pagamento salvos nos pedidos são sempre mantidos. Padrão: desativado.
Finalização da compra
O cliente escolhe o método de pagamento (por padrão Paystack) e faz o pedido. No modo de teste, a finalização da compra mostra MODO DE TESTE ATIVADO. Nenhuma cobrança real será feita. O plugin inicia uma transação na Paystack pelo total do pedido, na moeda do pedido, com o e-mail de cobrança do pedido, e envia o cliente para a página de pagamento hospedada pela Paystack. Lá o cliente paga com um dos canais ativados na sua conta Paystack.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Paystack confirma: quando o cliente retorna e quando o webhook chega, o plugin lê a transação pela API da Paystack com a chave secreta do modo em que o pagamento foi iniciado, e verifica a referência, o status, o valor e a moeda. Se o pagamento ainda estiver em processamento, por exemplo uma transferência bancária, a página de pedido recebido mostra Seu pagamento está sendo confirmado pela Paystack. Você receberá um e-mail assim que ele for confirmado. O webhook concluirá o pedido depois.
Se o cliente cancelar na página da Paystack ou sair dela sem pagar, o pedido continua aguardando o pagamento. O cliente volta para a finalização da compra ou para a página Pay for order com uma mensagem, por exemplo O pagamento foi cancelado. Você pode tentar novamente ou escolher outro método de pagamento., O pagamento não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. ou Seu pagamento foi recusado. Você pode tentar novamente ou escolher outro método de pagamento. O cliente pode pagar o mesmo pedido novamente. Uma página de pagamento anterior do pedido continua válida: se for paga depois, o pagamento ainda é aceito.
A página de pedido recebido só abre para o cliente do pedido: pelo link de retorno assinado, pela sessão de finalização da compra que criou o pedido ou pela conta do cliente. Qualquer outra pessoa é enviada à finalização da compra com uma mensagem neutra, e a página do pedido não é mostrada.
Se a Paystack não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo A Paystack não conseguiu iniciar o pagamento: seguida do motivo informado pela Paystack, ou A Paystack está temporariamente indisponível. Tente novamente em instantes ou escolha outro método de pagamento. O total do pedido precisa ser maior que zero, e o pedido precisa ter um e-mail válido.
O método de pagamento funciona na finalização de compra clássica, no bloco Finalizar compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin não tem formulário de pagamento embutido nem em pop-up, cartões salvos, assinaturas, pagamentos divididos ou subcontas, nem escolha de canais de pagamento no WooCommerce.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado para a Paystack e ainda não pagou, saiu da página da Paystack sem pagar, ou o pagamento ainda está sendo processado pela Paystack. Quando o cliente volta sem pagar, uma nota informa que o pedido continua aguardando o pagamento.
Processing or Completed: o pagamento foi confirmado. O status é Concluído quando Autocomplete Order está ativo. A nota do pedido mostra o valor, a referência da Paystack, o número da transação, o modo (teste ou produção), o canal de pagamento, o tipo de cartão e os últimos dígitos em pagamentos com cartão, além de quaisquer taxas da Paystack pagas pelo cliente. O ID da transação do pedido é a referência da Paystack (order_...).
On hold: o valor ou a moeda pagos diferem do pedido (nota Paystack amount or currency mismatch), ou o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica o que verificar. Processe o pedido ou reembolse o pagamento.
Failed: a Paystack informa que a tentativa de pagamento mais recente de um pedido pendente falhou ou foi revertida. A falha de uma tentativa mais antiga não altera o pedido. O cliente pode pagar novamente.
Se uma segunda tentativa de pagamento de um pedido que já está pago também for paga, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no painel da Paystack. Um pagamento que chega para um pedido em outro status, por exemplo Refunded, é apenas registrado no pedido.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Paystack. Reembolsos totais e parciais são suportados. O botão de reembolso só é oferecido para pedidos pagos por meio de uma transação Paystack verificada. O reembolso vai para a transação que pagou o pedido, com a chave secreta do modo (teste ou produção) em que ela foi feita, por isso essa chave precisa estar configurada. Em XOF e RWF, os reembolsos precisam ser valores inteiros. A Paystack coloca os reembolsos em fila: a nota do pedido mostra o status retornado pela Paystack, por exemplo pending, e o ID do reembolso. Se a Paystack não aceitar o reembolso, o WooCommerce mostra Paystack refund failed: com o motivo, e nenhum reembolso é registrado.
Reembolsos feitos no painel da Paystack, e o status final dos reembolsos colocados em fila pela Paystack, não são sincronizados de volta ao WooCommerce. Se necessário, registre-os manualmente.
Chave de licença
O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Paystack. 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 novamente, 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 vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Paystack não é exibida aos clientes na finalização da 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 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 de 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 Paystack não aparece na finalização da compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o modo atual tem uma chave secreta correta (Test Secret Key com sk_test_... no modo de teste, Live Secret Key com sk_live_... no modo de produção) e se a moeda do pedido é uma que a Paystack aceita. A caixa de status no topo das configurações indica o problema.
O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não chegou à sua loja e o cliente não voltou. No painel da Paystack, verifique se a Test Webhook URL e a Live Webhook URL são exatamente a URL mostrada nas configurações e se nenhum modo de manutenção, firewall ou proteção por senha as bloqueia. Consulte WooCommerce > Status > Logs, origem wcp_paystack_payment, para ver webhooks rejeitados.
O webhook responde Invalid signature: o webhook não foi assinado com a chave secreta de teste ou de produção informada nas configurações, por exemplo porque as chaves pertencem a outra conta Paystack. Informe as chaves da conta que envia o webhook.
O webhook responde Secret key not configured: nenhuma chave secreta está definida. Informe as chaves secretas nas configurações.
O webhook responde Verification failed ou Busy, retry later: a transação não pôde ser lida pela API da Paystack naquele momento, ou o pedido estava sendo atualizado pelo retorno do cliente ao mesmo tempo. O pedido não é alterado, e a Paystack envia o webhook novamente.
O webhook responde OK - unknown reference: o pagamento não foi feito para um pedido desta loja, por exemplo uma página de pagamento da Paystack ou outra integração na mesma conta. Ele é ignorado.
O cliente vê Payment gateway is not properly configured: a chave secreta do modo atual está ausente ou incorreta. Corrija-a seguindo a caixa de status no topo das configurações.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos diferiam do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Processe o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está configurada. Informe-a e tente novamente. A mensagem No verified Paystack payment was found for this order significa que o pedido não foi pago por meio de uma transação Paystack verificada. Reembolse-o no painel da Paystack.
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 de licença deste plugin são sempre removidos. As configurações do gateway e os registros só são removidos se Delete data on uninstall estava ativado. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e referências da Paystack.
Paystack é uma marca comercial de seu respectivo titular. Este plugin não é afiliado nem endossado pela Paystack.