VibeFox PayFast for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Moeda: rand sul-africano (ZAR). O PayFast liquida apenas em rand, por isso o carrinho precisa estar em ZAR. Adicione a moeda em International > Localization > Currencies se a sua loja ainda não a tiver. 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 houver uma definida no PayFast, a mesma passphrase precisa ser informada no módulo. Para testes, você precisa das credenciais do sandbox do PayFast.
Loja acessível: a URL de notificação de pagamento precisa ser acessível pela internet, sem autenticação básica nem bloqueio de firewall.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, vá em 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 PayFast Pay Gateway na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Informe o Merchant ID, a Merchant Key e a passphrase. Para testar, mantenha Test mode ativado e informe as suas credenciais do sandbox.
5. Ative Enable/Disable e clique em Save. Faça um pagamento de teste e depois desative Test mode para receber pagamentos reais.
Ao ser instalado, o módulo cria dois status de pedido: Awaiting PayFast payment e PayFast payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-lo em Payment > Preferences; certifique-se de que o módulo continue permitido para o rand.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando as credenciais do modo atual estão vazias (nesse caso o PayFast fica oculto no checkout), quando a moeda padrão da loja não é ZAR, quando o modo live usa o Merchant ID público do sandbox 10000100 e quando nenhuma passphrase está definida. Enquanto o modo de teste estiver ativo e o módulo habilitado, aparece: O modo de teste está ativo: os pedidos são pagos no sandbox do PayFast, nenhum dinheiro real é cobrado. Um campo Title vazio é recusado com Informe um título para o método de pagamento.
PayFast
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 no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: PayFast. Obrigatório.
Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Conta do PayFast (live)
Encontre o seu Merchant ID e a sua Merchant Key no painel do PayFast, em Settings > Developer Settings. Se você definiu uma passphrase lá, informe aqui exatamente a mesma.
Merchant ID: o seu Merchant ID live do PayFast.
Merchant Key: a sua Merchant Key live do PayFast. Ela é enviada ao PayFast com cada formulário de pagamento, por isso é um campo de texto comum.
Passphrase: a salt passphrase do PayFast, em Settings > Developer Settings. Fortemente recomendada: ela assina pagamentos e 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. Enquanto estiver ativo, o cliente vê abaixo do método de pagamento: MODO DE TESTE: os pagamentos vão para o sandbox do PayFast, nenhum dinheiro real é cobrado. 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.
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.
Clear saved passphrases: marque Passphrase ou Sandbox Passphrase e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Notificações de pagamento (ITN)
Notification URL: o PayFast confirma cada pagamento com uma notificação servidor a servidor para a URL exibida aqui. Com URLs amigáveis, ela fica assim: https://your-shop/module/wcp_payfast_pay/itn, possivelmente com o código do idioma padrão. O endereço é enviado com cada pagamento, então nada precisa ser configurado no PayFast, mas ele precisa ser acessível pela internet. Os pedidos são criados somente por essas notificações verificadas; o cliente que volta à loja não cria nem paga um pedido.
Source check: aceite notificações do modo live somente dos servidores do PayFast. Os endereços vêm dos registros DNS do PayFast (em cache por 6 horas) e das faixas de endereços documentadas pelo PayFast. Desative apenas se a loja estiver atrás de um proxy ou CDN que oculte o endereço do visitante. Assinatura e confirmação do servidor são sempre verificadas. Notificações do sandbox não são verificadas por endereço. Padrão: ativado.
Avançado
Debug log: registra as etapas do pagamento em logs/payfast_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. Nenhuma passphrase nem dado de cliente é gravado. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Uninstall: Delete the gateway settings when the module is uninstalled (configurações, endereços do PayFast em cache e log). Os registros de pagamento do PayFast, os pedidos e os status de pedido são sempre mantidos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão PayFast) e confirma. Uma página com Obrigado pelo seu pedido. Você está sendo redirecionado para o PayFast para concluir o pagamento. 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 volta à finalização de compra. O formulário leva o total do carrinho em ZAR, Cart # com o número do carrinho, o nome e o e-mail do cliente, a referência do pagamento (número do carrinho e tentativa) e um token aleatório da tentativa. Nesse ponto ainda não existe pedido. 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 do PayFast. Depois, 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:
As notificações de um mesmo carrinho são processadas uma por vez. Se outra notificação do mesmo carrinho estiver em processamento, o PayFast recebe uma resposta de erro e envia a notificação novamente. A URL de notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de país da sua loja.
Quando o cliente volta e o pedido existe, é mostrada a página padrão de confirmação do pedido. Se o PayFast informou que o pagamento está pendente, aparece: O PayFast está confirmando o seu pagamento. Você receberá um e-mail assim que ele for confirmado — não é preciso pagar novamente. Se o pedido estiver em análise, aparece: Seu pagamento está em análise. Entraremos em contato se for necessário algo mais. Se um pagamento pendente falhou depois, aparece: Seu pagamento no PayFast não foi concluído. Entre em contato conosco sobre este pedido. Se a notificação ainda não chegou, uma página Payment confirmation informa que o PayFast está confirmando o pagamento e que o pedido será criado assim que o PayFast confirmar, 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 O pagamento no PayFast foi cancelado. Você pode tentar novamente ou escolher outro método de pagamento. Se o PayFast informou que o pagamento falhou, a mensagem é O pagamento não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. O carrinho é mantido e pode ser pago novamente.
O método de pagamento fica oculto quando faltam as credenciais do modo atual, quando a moeda do carrinho não é ZAR ou não é permitida para o módulo, ou quando o total está abaixo de R5,00. Se o cliente chegar ao pagamento mesmo assim, uma mensagem curta explica, por exemplo O PayFast aceita pagamentos a partir de R5,00. Escolha outro método de pagamento.
O módulo 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 order yet: o cliente foi enviado ao PayFast e a notificação de pagamento ainda não chegou, ou o PayFast informou que o pagamento falhou. Existe apenas o carrinho.
Payment accepted: o PayFast confirmou o pagamento. O pagamento é registrado com o ID do pagamento no PayFast como ID da transação, e uma nota mostra o ID do pagamento. Um pagamento no sandbox recebe a nota de que nenhum dinheiro real foi cobrado.
Awaiting PayFast payment: o PayFast informou que o pagamento está pendente. O pedido passa para Payment accepted quando o PayFast concluir o pagamento.
Payment error: um pagamento pendente falhou. Se o PayFast concluí-lo depois, o pedido passa a Payment accepted.
PayFast payment on hold: o valor pago é diferente do total do carrinho, ou o carrinho não está em ZAR; um pagamento chegou para um pedido que foi cancelado ou cujo método de pagamento não é mais o PayFast; ou um pagamento no sandbox chegou enquanto o gateway está no modo live. O valor recebido pelo PayFast é registrado no pedido (não no caso de pagamento no sandbox), e a nota explica. Confira o pedido e o painel do PayFast e, em seguida, coloque o pedido em Payment accepted ou cancele-o e reembolse o pagamento no PayFast.
Uma notificação repetida do mesmo pagamento não altera nada. Notificações atrasadas de falha ou pendência nunca alteram um pedido pago. Se chegar outro pagamento concluído para um pedido que já está pago, uma nota pede que você reembolse a duplicata no PayFast. Um pagamento para um pedido reembolsado apenas acrescenta uma nota.
Bloco de pagamento do PayFast
A página do pedido mostra um bloco PayFast payment com a referência do pagamento (m_payment_id), o ID do pagamento no PayFast, o ambiente (live ou sandbox), o status, os valores bruto, taxa e líquido em ZAR e as notas do módulo. Para um pedido em análise, mostra um lembrete para revisar o pagamento.
Reembolsos
Reembolsos pela página do pedido não são suportados. Reembolse o pagamento no seu painel do PayFast e depois atualize o pedido no PrestaShop manualmente.
Chave de licença
O módulo 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 Modules > Module Manager > VibeFox PayFast Pay 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-payfast 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 para o 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 que você 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, o PayFast não é exibido aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, 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 pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 informada, depois uma vez por semana. Não é necessário nenhum 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
O PayFast não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o Merchant ID e a Merchant Key do modo atual estão preenchidos, se o carrinho está em 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. Em Payment > Preferences, confira se o módulo está permitido para o rand, para o país do cliente e para o grupo do cliente.
O pagamento foi aprovado, mas nenhum pedido foi criado: o PayFast não conseguiu entregar a notificação de pagamento, ou ela foi rejeitada. Veja o campo Log na página do módulo; erros e notificações rejeitadas são sempre registrados, e o Debug log acrescenta cada etapa. Motivos comuns: a loja não é acessível pela internet (autenticação básica, firewall), uma passphrase diferente no PayFast e no módulo ou, no modo live atrás de um proxy ou CDN, a verificação de origem. Nesse caso, desative o Source check.
A notificação responde Invalid signature: a passphrase no módulo não é a definida no PayFast para o modo em que o pagamento foi feito.
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 o Source check se a sua loja 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 esta tentativa de pagamento. Nada é alterado.
A notificação responde Order not found: a referência do pagamento é desconhecida para esta loja. Nada é alterado.
A notificação responde Confirmation unavailable, Busy ou Temporary error: não foi possível contatar o PayFast para a confirmação do servidor, outra notificação do mesmo carrinho estava sendo processada naquele momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O PayFast tenta a notificação novamente. O log mostra o motivo.
A notificação responde 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.
O cliente vê a mensagem O PayFast aceita pagamentos somente em rand sul-africano (ZAR): o carrinho está em outra moeda. Peça ao cliente que pague em rand ou que escolha outro método de pagamento.
O pedido está em PayFast payment on hold: leia as notas no bloco PayFast payment (veja Status do pedido) e o painel do PayFast e, em seguida, aceite o pedido ou reembolse o pagamento.
Um pagamento no sandbox não pagou o pedido: o gateway está no modo live. Pagamentos no sandbox nunca pagam um pedido no modo live; uma nota no pedido informa isso.
Para desenvolvedores: o hook actionPayfastPPaymentData pode alterar os campos do formulário de pagamento antes de serem assinados. As credenciais do comerciante, as URLs, a referência do pagamento, o valor e o token não podem ser alterados por ele.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox PayFast Pay Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete the gateway settings when the module is uninstalled estiver ativado, as configurações do gateway, os endereços do PayFast em cache e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamento do PayFast, os pedidos e os status de pedido Awaiting PayFast payment e PayFast payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
PayFast é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pelo PayFast.