VibeFox PayFast for WooCommerce — Ajuda
Requisitos
WordPress: 6.2 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda: rand sul-africano (ZAR), definido em WooCommerce > Settings > General. O PayFast liquida somente em rand. O valor mínimo do pedido é R5.00.
Conta do PayFast: o Merchant ID e a Merchant Key da sua conta do PayFast, em Settings > Developer Settings no painel do PayFast. Uma passphrase é fortemente recomendada; se estiver definida no PayFast, a mesma passphrase precisa ser informada no plugin. Para testes, você precisa das credenciais do sandbox do PayFast.
Site acessível: a URL de notificação de pagamento precisa ser acessível pela internet, sem modo de manutenção, autenticação básica ou bloqueio por firewall.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona para um domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_payfast_pay para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Defina a moeda da loja como rand sul-africano em WooCommerce > Settings > General.
4. Abra as configurações: WooCommerce > Settings > Payments > PayFast > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
5. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
6. Informe o Merchant ID, a Merchant Key e a passphrase. Para testes, mantenha Test mode ativado e informe suas credenciais do sandbox.
7. Ative Enable/Disable e salve. Faça um pagamento de teste e depois desative o modo de teste para receber pagamentos reais.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > PayFast. Acima dos campos, a página avisa quando as credenciais do modo atual estão vazias (o PayFast fica oculto na finalização de compra), quando a moeda da loja não é ZAR, quando o modo live usa o Merchant ID público de sandbox 10000100 e quando nenhuma passphrase está definida; e mostra Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. enquanto o modo de teste estiver ativado. Na lista de métodos de pagamento, o PayFast aparece como pendente de configuração até que o Merchant ID e a Merchant Key do modo atual sejam informados.
Geral
Enable/Disable: Enable PayFast ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento exibido ao cliente na finalização de compra. Padrão: PayFast.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Conta do PayFast (live)
Encontre seu Merchant ID e sua Merchant Key no painel do PayFast, em Settings > Developer Settings. Se você definiu uma passphrase ali, informe exatamente a mesma aqui.
Merchant ID: seu Merchant ID live do PayFast.
Merchant Key: sua Merchant Key live do PayFast. Ela é enviada ao PayFast com cada formulário de pagamento.
Passphrase: a passphrase de salt do PayFast, em Settings > Developer Settings. Fortemente recomendada: ela assina os pagamentos e as notificações.
Sandbox (modo de teste)
No modo de teste, os pagamentos vão para o sandbox do PayFast e nenhum dinheiro real é cobrado. As credenciais do sandbox aparecem depois que você faz login no sandbox do PayFast (o comerciante de teste público é 10000100 / 46f0cd694581a).
Test mode: Use the PayFast sandbox and the sandbox credentials below. Na finalização de compra, o cliente vê TEST MODE: payments go to the PayFast sandbox, no real money is charged. Padrão: ativado.
Sandbox Merchant ID: o Merchant ID da sua conta de sandbox.
Sandbox Merchant Key: a Merchant Key da sua conta de sandbox.
Sandbox Passphrase: somente se uma passphrase estiver definida na sua conta de sandbox.
Ao atualizar a partir da versão 1.0 no modo de teste, suas credenciais existentes são copiadas para os campos do sandbox. Confira as credenciais live antes de desativar o modo de teste.
Notificações de pagamento (ITN)
O PayFast confirma cada pagamento com uma notificação servidor a servidor enviada para a URL exibida nesta seção. Ela tem este formato: https://your-site/wc-api/payfast_pay/. O endereço é enviado com cada pagamento, então não há nada a configurar no PayFast, mas ele precisa ser acessível pela internet.
Verificação de origem: Accept live notifications only from PayFast servers. Os endereços vêm dos registros DNS do PayFast. Desative esta opção somente se o seu site estiver atrás de um proxy ou CDN que oculte o endereço do visitante. A assinatura e a confirmação pelo servidor são sempre verificadas. As notificações do sandbox não são verificadas pelo endereço. Padrão: ativado.
Avançado
Debug log: Log payment steps grava as etapas em WooCommerce > Status > Logs, origem wcp_payfast_pay. Erros são sempre registrados. Nenhuma passphrase nem dado de cliente é gravado. Padrão: desativado.
Uninstall: Delete the gateway settings and logs when the plugin is deleted. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão PayFast) e faz o pedido. Ele vai para a página Pay for order do pedido, que mostra Thank you for your order. You are being redirected to PayFast to complete the payment. e envia automaticamente o formulário de pagamento assinado ao PayFast. Se o navegador não continuar sozinho, o cliente clica em Pay with PayFast; Cancel order cancela o pedido. O formulário traz o total do pedido em ZAR, Order # com o número do pedido, o nome e o e-mail do cliente e a chave do pedido. Ele é gerado novamente sempre que a página é aberta, então o cliente pode reabri-lo ao voltar do PayFast.
Na página do PayFast, o cliente paga com cartão, Instant EFT ou outro método da sua conta do PayFast. Depois, o PayFast envia a notificação de pagamento (ITN) para a sua loja. O pedido só é marcado como pago quando a notificação passa por todas as verificações:
O retorno do cliente à página de pedido recebido não altera o pedido. Enquanto a notificação não chega, a página diz PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se o pedido estiver em espera, diz Your payment is being reviewed. We will contact you if anything else is needed.
Se o cliente cancelar na página do PayFast, o pedido é cancelado da forma padrão do WooCommerce. Se o cliente sair sem pagar, o pedido continua não pago e pode ser pago novamente pela página Pay for order.
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. Ele fica oculto quando as credenciais do modo atual estão ausentes, quando a moeda da loja ou do pedido não é ZAR, ou quando o total é inferior a R5.00. É compatível com o HPOS (armazenamento de pedidos de alto desempenho) do WooCommerce.
O plugin aceita apenas pagamentos únicos em ZAR. Não há reembolsos pelo WooCommerce, assinaturas, cartões salvos (tokenizados), pré-vendas nem pagamentos divididos.
Pedidos
Status do pedido
Pending payment: o cliente foi enviado ao PayFast e a notificação de pagamento ainda não chegou.
Processing: o PayFast confirmou o pagamento. Este é o status padrão do WooCommerce após o pagamento; pedidos que contêm apenas produtos virtuais para download passam para Concluído. A nota do pedido mostra o ID do pagamento no PayFast, que também é o ID de transação do pedido. Um pagamento no sandbox recebe a nota de que nenhum dinheiro real foi cobrado. A taxa do PayFast e o valor líquido ficam armazenados no pedido.
On hold: o PayFast informou o pagamento como pendente; ou o valor pago difere do total do pedido, ou o pedido não está em ZAR; ou chegou um pagamento para um pedido que já estava cancelado. A nota do pedido explica o motivo. Confira o pedido e o painel do PayFast e, em seguida, envie o pedido ou reembolse o pagamento no PayFast.
Failed: o PayFast informou o pagamento como falho enquanto o pedido estava sem pagamento. O cliente pode pagar novamente.
Cancelled: o cliente cancelou na página do PayFast, ou o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce.
Uma notificação repetida do mesmo pagamento não altera nada. Se chegar outro pagamento concluído para um pedido já pago, uma nota pede que você reembolse o duplicado no PayFast. Um pagamento para um pedido reembolsado apenas adiciona uma nota. Um pagamento no sandbox recebido enquanto o gateway está em modo live adiciona uma nota e não marca o pedido como pago.
Reembolsos
Reembolsos pelo WooCommerce não são compatíveis. Reembolse o pagamento no seu painel do PayFast e, depois, 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 > PayFast. 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 sua conta em vibefox.net.
Uma chave funciona para um domínio. Remover a chave de um site não libera a vaga de domínio; libere-a na sua conta em vibefox.net.
Sem uma chave ativa, o PayFast 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. Os gerentes da loja que estiverem logados continuam vendo 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: pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente em segundo plano.
Solução de problemas
O PayFast não aparece na finalização de compra: confira se a licença está ativa, se Enable/Disable está ligado, se o Merchant ID e a Merchant Key do modo atual estão preenchidos, se a moeda da loja é ZAR e se o total do pedido é de pelo menos R5.00. A página de configurações mostra um aviso quando algo está faltando.
O pagamento foi feito, mas o pedido continua em «Aguardando pagamento»: o PayFast não conseguiu entregar a notificação de pagamento, ou ela foi rejeitada. Ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_payfast_pay. Motivos comuns: o site não está acessível pela internet (modo de manutenção, autenticação básica, firewall), uma passphrase diferente no PayFast e no plugin, ou, no modo live atrás de um proxy ou CDN, a verificação de origem. Nesse caso, desative Source check.
A notificação responde Invalid signature: a passphrase no plugin não é a definida no PayFast para este modo.
A notificação responde Invalid source: a notificação não veio de um endereço do PayFast, ou um proxy ou CDN oculta o endereço real. Desative Source check se o seu site estiver atrás de um proxy ou CDN.
A notificação responde Merchant mismatch ou Order mismatch: o pagamento foi feito para outra conta do PayFast ou não pertence a este pedido. Nada é alterado.
A notificação responde Confirmation unavailable ou Busy: o PayFast não pôde ser acessado para a confirmação pelo servidor, ou outra notificação do mesmo pedido estava sendo processada no mesmo momento. O PayFast tenta a notificação novamente.
A notificação responde Not configured: as credenciais do modo em que o pedido foi pago estão ausentes.
O cliente vê PayFast accepts payments from R5.00: o total do pedido está abaixo do mínimo do PayFast.
O pedido está On hold: o PayFast confirmou um pagamento que não corresponde ao pedido (valor diferente, ou moeda diferente de ZAR), ou o pagamento chegou para um pedido já cancelado. Confira as notas do pedido e o painel do PayFast.
Um pagamento no sandbox não pagou o pedido: o gateway está em modo live. Pagamentos no sandbox nunca pagam um pedido em modo live; uma nota no pedido informa isso.
O bloco de licença exibe 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 em 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, as demais opções do plugin, os endereços do PayFast em cache e os logs só são removidos se Delete the gateway settings and logs when the plugin is deleted estiver ativado. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
PayFast é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo PayFast.