VibeFox PayFast for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 ou superior (testado na 4.1.0.3).
PHP: 8.0 ou posterior.
Currency: rand sul-africano (ZAR). O PayFast liquida apenas em rands, por isso o pedido precisa estar em ZAR. Adicione a moeda em System > Localisation > Currencies se a sua loja ainda não a tiver. O valor mínimo do pedido é R5.00.
PayFast account: o Merchant ID e a Merchant Key da sua conta PayFast, em Settings > Developer Settings no painel do PayFast. Uma passphrase é fortemente recomendada; se você tiver definido uma no PayFast, a mesma passphrase precisa ser informada na extensão. Para os testes, você precisa das credenciais do sandbox do PayFast.
Reachable store: a URL de notificação de pagamento precisa estar acessível pela internet, sem autenticação básica e sem bloqueio por firewall.
VibeFox license key: adquirida em vibefox.net. Uma chave funciona em um único domínio.
Instalação
O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_payfast_pay-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_payfast_pay.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_payfast_pay-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox PayFast Pay Gateway e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja a seção Chave de licença).
4. Informe o Merchant ID, a Merchant Key e a passphrase. Para testar, mantenha Test mode ativado e informe as credenciais do sandbox.
5. Ative Enable/Disable e clique em Save. Faça um pagamento de teste e, em seguida, desative Test mode para receber pagamentos reais.
OpenCart 4
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_payfast_pay.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.
2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.
3. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox PayFast Pay Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Informe a chave de licença e as credenciais do PayFast e teste o pagamento como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de notificação é diferente (veja Notification URL); ela também é enviada ao PayFast com cada pagamento.
Uma nova instalação começa com o método de pagamento desativado e o modo de teste ativado.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando as credenciais do modo atual estão vazias (nesse caso o PayFast fica oculto na finalização de compra), quando a moeda padrão da loja não é ZAR, quando o modo de produção usa o Merchant ID público do sandbox 10000100 e quando nenhuma passphrase está definida. Enquanto o modo de teste estiver ativado, ela mostra Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.
Ao salvar, Title não pode ficar vazio (até 128 caracteres), Sort Order precisa ser um número inteiro (números negativos são permitidos), Total precisa ser um número igual ou maior que 0, e a zona geográfica e os status de pedido selecionados precisam existir; caso contrário, nada é salvo e a página indica o campo. Se você ativar o método de pagamento sem as credenciais do modo atual, as configurações são salvas com um aviso.
PayFast
Enable/Disable: Enable PayFast liga ou desliga o método de pagamento. Padrão: desligado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento gravado no pedido. Padrão: PayFast. Obrigatório.
Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Sort Order: a posição do PayFast entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.
Geo Zone: oferece o PayFast apenas para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones. No OpenCart 4, quando a loja não solicita um endereço de pagamento, é usado o endereço de entrega.
Total: o valor da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que o PayFast seja oferecido. Deixe em branco para oferecer o PayFast para qualquer valor. O próprio PayFast sempre exige pelo menos R5.00.
Conta PayFast (produção)
Você encontra o seu Merchant ID e a sua Merchant Key no painel do PayFast, em Settings > Developer Settings (lá estão os links para a seção). Se você definir uma passphrase lá, informe aqui exatamente a mesma.
Merchant ID: o seu Merchant ID de produção do PayFast.
Merchant Key: a sua Merchant Key de produção do PayFast. Ela é enviada ao PayFast em cada formulário de pagamento, por isso é um campo de texto comum.
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 merchant público de teste é 10000100 / 46f0cd694581a).
Test mode: Use the PayFast sandbox and the sandbox credentials below. Enquanto estiver ativado, o cliente vê TEST MODE: payments go to the PayFast sandbox, no real money is charged. na etapa Confirm Order. Padrão: ativado.
Sandbox Merchant ID: o Merchant ID da sua conta sandbox.
Sandbox Merchant Key: a Merchant Key da sua conta sandbox.
Sandbox Passphrase: somente se houver uma passphrase definida na sua conta sandbox.
As passphrases salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la. Para remover uma passphrase salva, marque Clear the saved passphrase on save abaixo do campo e clique em Save.
Notificações de pagamento (ITN)
Notification URL: o PayFast confirma cada pagamento com uma notificação servidor a servidor enviada para a URL exibida aqui. No OpenCart 3 ela tem a forma https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn, e no OpenCart 4, a forma https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. O endereço é enviado com cada pagamento, por isso nada precisa ser configurado no PayFast, mas ele precisa estar acessível pela internet. Os pedidos só recebem status a partir dessas notificações verificadas; o retorno do cliente à loja não altera o pedido.
Source check: aceita notificações de produção somente dos servidores do PayFast. Os endereços vêm dos registros DNS do PayFast (armazenados em cache por 6 horas; o cache é reiniciado ao salvar as configurações) e das faixas de endereços documentadas pelo PayFast. Desative apenas se a sua loja estiver atrás de um proxy ou CDN que oculte o endereço do visitante. A assinatura e a confirmação no servidor são sempre verificadas. As notificações do sandbox não são verificadas pelo endereço. Padrão: ativado.
Pedidos
O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele só recebe um status a partir de uma notificação verificada do PayFast. Um pagamento cancelado, com falha ou abandonado deixa o pedido sem status, e o cliente pode pagar novamente. Cada campo abaixo lista os seus status de pedido do OpenCart.
Order Status (paid): o status depois que o PayFast confirma o pagamento e o valor e a moeda conferem. Padrão: Processando.
Awaiting PayFast payment: o PayFast informou o pagamento como pendente (por exemplo, Instant EFT). Ele muda para o status de pago quando o PayFast o conclui. Padrão: Pendente.
PayFast payment on hold: um pagamento que precisa da sua análise (veja a seção Status do pedido). Esse pedido não é marcado como pago; uma nota explica o motivo. Padrão: Pendente, porque o OpenCart não tem o status On hold. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.
Payment failed: um pagamento pendente falhou. Se o PayFast concluí-lo depois, o pedido muda para o status de pago. Padrão: Falhou.
Avançado
Debug log: registra as etapas do pagamento em payfast_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para payfast_p_debug.old.log.php. Erros e avisos são sempre registrados, mesmo com a chave desligada. Nenhuma passphrase, chave ou dado do cliente é gravado. Padrão: desligado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.
Uninstall: Delete the gateway settings when the extension is uninstalled (configurações, endereços do PayFast em cache e log). Os registros de pagamento do PayFast e os pedidos são sempre mantidos. Padrão: desligado.
Importar / Exportar
Export: Download JSON salva as configurações em um arquivo JSON. As passphrases não são exportadas.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As passphrases salvas são mantidas.
Finalização de compra
Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, PayFast). Na etapa Confirm Order, o cliente vê a sua descrição e a nota Thank you for your order. You will be redirected to PayFast to complete the payment. O OpenCart cria o pedido nessa etapa, ainda sem status. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização da compra. Quando o cliente clica em Confirm Order, a extensão envia ao PayFast o formulário de pagamento assinado. O formulário traz o valor do pedido em ZAR, Order # com o número do pedido, o nome e o e-mail do cliente, a referência do pagamento (número do pedido e tentativa) e um token aleatório da tentativa. Cada nova tentativa recebe uma nova referência e um novo token.
Na página do PayFast, o cliente paga com cartão, Instant EFT ou outro método da sua conta PayFast. Em seguida, o PayFast envia a notificação de pagamento (ITN) para a sua loja. O pedido só é marcado como pago depois que o PayFast o confirma com uma notificação que passa por todas as verificações:
Depois disso, o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque. As notificações de um mesmo carrinho são processadas uma por vez; se outra notificação do mesmo carrinho estiver sendo processada, o PayFast recebe uma resposta de erro e envia a notificação novamente. A URL de notificação também funciona quando a loja está em modo de manutenção: o OpenCart 3 libera as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma startup action que libera as notificações e o retorno do cliente vindo do PayFast.
Quando o cliente volta e o pedido tem um status, é exibida a página de sucesso do pedido do OpenCart. Se o PayFast informou o pagamento como pendente, também aparece 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, aparece Your payment is being reviewed. We will contact you if anything else is needed. Se um pagamento pendente falhou depois, aparece Your PayFast payment was not completed. Please contact us about this order. (no OpenCart 4 o cliente é enviado de volta à finalização da compra, veja abaixo). Se a notificação ainda não chegou, uma página Payment confirmation informa que o PayFast está confirmando o pagamento, com os botões Check again e Back to checkout.
Se o cliente cancelar na página do PayFast, ele volta à finalização de compra com a mensagem The PayFast payment was cancelled. You can try again or choose another payment method. Se o PayFast informou o pagamento como falho, a mensagem é The payment was not completed. You can try again or choose another payment method. O carrinho é mantido e pode ser pago novamente. No OpenCart 4, essas mensagens são exibidas acima da página de finalização da compra. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 mantém um único pedido para a finalização da compra e o atualiza, assim, após um pagamento cancelado ou com falha, o cliente paga o mesmo pedido com uma nova tentativa. Se outro pedido do mesmo carrinho já tiver sido tratado pelo PayFast (por exemplo, em uma segunda aba do navegador), o cliente é levado à página de sucesso em vez de pagar de novo.
O OpenCart 4 mantém o pedido na finalização da compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, o pagamento pendente falhou ou você o cancelou), o cliente volta à finalização da compra com a mensagem Your previous order was cancelled or its payment failed. Please confirm the order again., e o próximo Confirm Order paga um novo pedido. Se esse pedido já tiver um status e o carrinho agora tiver outros produtos ou quantidades, a mensagem é Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.
O método de pagamento fica oculto quando faltam as credenciais do modo atual, quando a moeda da finalização de compra não é ZAR ou quando o total é inferior a R5.00. Se o cliente chegar ao pagamento mesmo assim, uma mensagem curta acima do botão explica o motivo, por exemplo PayFast accepts payments from R5.00. Please choose another payment method.
A extensão aceita apenas pagamentos únicos em ZAR. Não há reembolsos pela página do pedido, nem assinaturas, nem cartões salvos (tokenizados), nem pagamentos divididos.
Pedidos
Status do pedido
No status (missing order): o cliente foi enviado ao PayFast e a notificação de pagamento ainda não chegou, ou o PayFast informou o pagamento como falho. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.
No OpenCart 4, um pedido não pago da finalização da compra pode receber o status Voided, que o OpenCart 4 define quando o cliente volta à etapa Confirm Order. A extensão trata esse pedido como um pedido sem status, e um pagamento posterior ainda o confirma.
Order Status (paid) (default Processing): o PayFast confirmou o pagamento. Uma nota mostra o ID do pagamento no PayFast. Um pagamento de sandbox recebe a nota de que nenhum dinheiro real foi cobrado.
Awaiting PayFast payment (default Pending): o PayFast informou o pagamento como pendente. O pedido passa ao status de pago quando o PayFast o conclui, ou para Payment failed quando o pagamento falha; o cliente é avisado dessas mudanças por e-mail.
Payment failed (default Failed): um pagamento pendente falhou. Se o PayFast concluí-lo depois, o pedido muda para o status de pago.
PayFast payment on hold (default Pending): o valor pago é diferente do total do pedido, ou o pedido não está em ZAR; chegou um pagamento para um pedido cujo status você alterou nesse meio tempo (por exemplo, cancelado) ou cujo método de pagamento não é mais o PayFast; ou chegou um pagamento de sandbox enquanto o gateway estava em modo de produção. A nota explica o motivo. Confira o pedido e o painel do PayFast e, em seguida, coloque o pedido no status de pago ou cancele-o e reembolse o pagamento no PayFast.
Uma notificação repetida do mesmo pagamento não muda nada. Notificações atrasadas de pagamentos falhos ou pendentes nunca alteram um pedido pago. Se chegar outro pagamento concluído para um pedido já pago, ou para um segundo pedido de um carrinho já pago, uma nota no pedido pago pede que você reembolse a duplicata no PayFast.
As notas são entradas do History do pedido que o cliente não vê.
Aba VibeFox PayFast Pay Gateway
Em Sales > Orders, abra um pedido pago com o PayFast. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox PayFast Pay Gateway mostra a Payment reference (m_payment_id), o PayFast payment ID, o Environment (produção ou sandbox), o valor solicitado, o status, os valores bruto, taxa e líquido em ZAR e as PayFast notes. Para um pedido em espera, ela mostra um lembrete para analisar o pagamento. A aba é exibida para usuários que têm acesso à extensão.
Reembolsos
Reembolsos pela página do pedido não são suportados. Reembolse o pagamento no seu painel do PayFast e, em seguida, atualize o pedido manualmente no OpenCart.
Chave de licença
A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox PayFast Pay Gateway é o primeiro bloco de Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit, acima das configurações. Cole 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 aparecem a linha Product: opencart-payment-payfast e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 de alterar o endereço da loja ou 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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não vê o login no painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado automaticamente quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é preciso nenhum cron job. Ao desinstalar a extensão, a chave de licença e o status da licença são sempre removidos.
Solução de problemas
PayFast does not appear at checkout: verifique 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 finalização de compra é 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. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.
The payment went through, but the order stays without a status: o PayFast não conseguiu entregar a notificação de pagamento, ou ela foi rejeitada. Veja o campo Log na página da extensão; erros e notificações rejeitadas são sempre registrados, e o Debug log acrescenta cada etapa. Motivos comuns: a loja não está acessível pela internet (autenticação básica, firewall), uma passphrase diferente no PayFast e na extensão ou, em modo de produção atrás de um proxy ou CDN, a verificação de origem. Nesse caso, desative Source check.
The notification answers Invalid signature: a passphrase na extensão não é a que está definida no PayFast para o modo em que o pagamento foi feito.
The notification answers 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 a sua loja estiver atrás de um proxy ou CDN.
The notification answers Merchant mismatch or Order mismatch: o pagamento foi feito para outra conta do PayFast ou não pertence a esta tentativa de pagamento. Nada é alterado.
The notification answers Order not found: a referência do pagamento é desconhecida para esta loja. Nada é alterado.
The notification answers Confirmation unavailable, Busy or Temporary error: não foi possível acessar o PayFast para a confirmação no servidor, outra notificação do mesmo carrinho estava sendo processada no mesmo momento, ou não foi possível definir o status do pedido. O PayFast tenta a notificação novamente. O log mostra o motivo.
The notification answers Not configured: faltam as credenciais do modo em que o pagamento foi iniciado. Informe-as novamente, por exemplo as credenciais do sandbox para um pagamento de teste.
The customer sees PayFast accepts payments in South African rand (ZAR) only: o pedido está em outra moeda. Peça que o cliente pague em rands ou que escolha outro método de pagamento.
The customer sees This payment method is not available. Please reload the checkout page. A sessão da finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desligado nesse meio tempo. O cliente deve recarregar a finalização de compra.
Order is in the on-hold status: leia as notas na aba VibeFox PayFast Pay Gateway (veja a seção Status do pedido) e o painel do PayFast e, em seguida, defina o status de pago ou reembolse o pagamento.
A sandbox payment did not pay the order: o gateway está em modo de produção. Pagamentos de sandbox nunca pagam um pedido em modo de produção; uma nota no pedido informa isso.
Para desenvolvedores: antes de o formulário de pagamento ser assinado, a extensão dispara o evento do OpenCart payfast_p_payment_data com os campos do formulário e o pedido. As credenciais do merchant, as URLs, a referência do pagamento, o valor e o token não podem ser alterados por ele.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox PayFast Pay Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos valores padrão em uma nova instalação. O evento do OpenCart da extensão também é removido (no OpenCart 4 também são removidos os seus eventos e a sua startup action, que libera as notificações e o retorno do cliente no modo de manutenção). Se Delete the gateway settings when the extension is uninstalled estiver ligado, são removidas as demais configurações do gateway (título, descrição, credenciais, passphrases, modo de teste, verificação de origem, registro de log), os endereços do PayFast em cache e o log. Se estiver desligado, elas são mantidas para uma reinstalação futura. Os registros de pagamento do PayFast e os pedidos são sempre mantidos. Os pedidos existentes preservam as suas notas de pagamento.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox PayFast Pay Gateway na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
O PayFast é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pelo PayFast.