VibeFox Paystack for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou posterior. O módulo se recusa a ser instalado em versões anteriores do PHP.

Moeda: o carrinho deve estar em uma moeda aceita pela Paystack: 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, pois 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). Sua loja precisa estar acessível pela internet para receber os webhooks.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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, mais tarde, localize VibeFox Paystack Payment 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. Cole as suas chaves secretas do painel da Paystack e defina a URL do webhook no painel da Paystack (veja Configuração).

5. Ative Enable/Disable e clique em Save. Mantenha Test Mode ativado até fazer um pagamento de teste e depois desative-o para aceitar pagamentos reais.

Ao instalar, o módulo cria dois status de pedido, Awaiting Paystack payment e Paystack payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Paystack Payment > Configure. Cada seção com campos tem o seu próprio botão Save, que salva a página inteira. 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 inserida 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 padrão da sua loja. Enquanto houver um problema com a chave, o método de pagamento fica oculto na finalização de compra.

Paystack

A primeira seção tem o título Paystack com um selo TEST ou LIVE do modo atual.

Enable/Disable: Enable Paystack Payment 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. É também o nome do método de pagamento salvo no pedido. Padrão: Paystack. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de 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, página Settings > API Keys & Webhooks. A seção traz um link para ela.

Test Mode: usa a chave secreta de teste para os novos pagamentos, e nenhum dinheiro real é cobrado. Desative-o 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. Enquanto estiver ativado, os clientes veem MODO DE TESTE ATIVADO. Nenhuma cobrança real será feita. abaixo do método de pagamento.

Test Secret Key: a sua chave secreta de teste da Paystack. Começa com sk_test_.

Live Secret Key: a sua chave secreta de produção da Paystack. Começa com sk_live_.

As chaves salvas nunca são mostradas novamente. O campo fica vazio e exibe Salva — deixe vazio para mantê-la. Digite um novo valor somente se quiser alterá-la.

Clear saved secrets: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Webhook

O webhook informa à sua loja que um pagamento foi feito, mesmo quando o cliente não volta à loja. No painel da Paystack, página Settings > API Keys & Webhooks, defina a URL exibida em Webhook URL desta seção tanto como Test Webhook URL quanto como Live Webhook URL. Com URLs amigáveis ela fica assim: https://your-shop/module/wcp_paystack_payment/webhook, possivelmente com um código de idioma como /en/. 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. Webhooks sem assinatura válida são rejeitados. O módulo usa o evento charge.success:

Os outros eventos recebem a resposta OK e são ignorados. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja após pagar. Transferências bancárias e pagamentos USSD que são concluídos depois são confirmados apenas pelo webhook.

Pedidos

Autocomplete Order: quando ativado, os pedidos pagos recebem o status Delivered em vez de Payment accepted, com uma única mudança de status. Padrão: desativado.

Avançado

Debug log: registra os eventos da Paystack e as chamadas à API em logs/paystack_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. Chaves e dados de clientes nunca são registrados. Padrão: desativado.

Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para limpá-lo.

Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações do módulo e o registro. Os dados de pagamento salvos nos pedidos 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 Paystack) e confirma o pedido. O módulo inicia uma transação na Paystack pelo total do carrinho na moeda do carrinho, com o e-mail do cliente, 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. O pagamento mostra o número do carrinho e o nome do cliente. Neste ponto, ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Paystack confirma: quando o cliente volta e quando o webhook chega, o módulo lê a transação pela API da Paystack e verifica a referência, o status, o valor e a moeda. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido.

Se o pagamento ainda estiver em processamento, por exemplo uma transferência bancária, o pedido é criado em Awaiting Paystack payment quando o cliente volta, e a página de confirmação mostra Seu pagamento está sendo confirmado pela Paystack. Você receberá um e-mail assim que ele for confirmado. O webhook conclui o pedido mais tarde. Se a Paystack não puder ser contatada quando o cliente voltar, uma página Payment confirmation pede ao cliente que não pague novamente e oferece Check again e Back to checkout; o webhook cria o pedido assim que chegar. Para um pedido em análise, a página de confirmação mostra Seu pagamento foi recebido e o seu pedido está em análise. Entraremos em contato se for necessário algo.

Se o cliente cancelar na página da Paystack ou sair dela sem pagar, nenhum pedido é criado e o carrinho é mantido. O cliente volta à finalização de compra 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. Cada nova tentativa inicia uma nova transação na Paystack. Uma página de pagamento anterior do carrinho continua válida: se for paga depois, o pagamento ainda é aceito.

A página de confirmação do pedido só abre no próprio navegador do cliente. Se o link de retorno for aberto em outro lugar, o pagamento continua sendo verificado, mas o pedido não é mostrado: o visitante vê uma mensagem neutra na finalização de compra.

Se a Paystack não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com 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 carrinho deve ser maior que zero, e o cliente precisa de um endereço de e-mail válido.

O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

O módulo não tem formulário de pagamento embutido nem em pop-up, nem cartões salvos, assinaturas, pagamentos divididos ou subcontas, nem escolha de canais de pagamento no PrestaShop.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado para a Paystack e não pagou, saiu da página da Paystack ou a Paystack ainda não confirmou o pagamento. Só existe o carrinho.

Awaiting Paystack payment: o cliente voltou enquanto a Paystack ainda processava o pagamento, por exemplo uma transferência bancária ou USSD. O pedido passa para o status de pago quando a Paystack confirma o pagamento. Se esse pagamento nunca for concluído, o pedido permanece neste status até que você o altere.

Payment accepted ou Delivered: o pagamento foi confirmado. O status é Entregue quando Autocomplete Order está ativado. O pagamento é registrado com a referência da Paystack (pscart_...) como ID da transação. Uma nota mostra o valor, a referência, 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 nos pagamentos com cartão, e as taxas da Paystack pagas pelo cliente, se houver.

Paystack payment on hold: o valor ou a moeda pagos não correspondem ao pedido (nota Divergência de valor ou moeda da Paystack), por exemplo porque o carrinho foi alterado depois que o pagamento começou, ou porque o pagamento chegou depois que o pedido foi cancelado. A nota explica o que verificar. Atenda o pedido ou reembolse o pagamento.

Erro de pagamento: a Paystack informa que a última tentativa de pagamento de um pedido em Awaiting Paystack payment falhou ou foi estornada. A falha de uma tentativa mais antiga não altera o pedido.

Se chegar um segundo pagamento de um carrinho cujo pedido já está pago, 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 Enviado, fica apenas registrado no pedido.

Bloco Paystack payment

A página do pedido mostra um bloco Paystack payment com a referência, o ID da transação, o modo com um selo Test mode para pagamentos de teste, o status do pagamento, o canal e o cartão, a data do pagamento, os valores pagos e reembolsados, o histórico de reembolsos e as Payment notes do pedido.

Reembolsos

No bloco Paystack payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Paystack. Confirme a pergunta Reembolsar este valor pela Paystack? Esta ação não pode ser desfeita. Reembolsos totais e parciais são suportados. Você precisa da permissão para editar pedidos; o acesso às páginas de módulos não é necessário. 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. Os reembolsos são feitos no valor e na moeda que a Paystack cobrou, então, para um pedido em análise após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. Em XOF e RWF os reembolsos devem ser valores inteiros. A Paystack coloca os reembolsos em fila: a nota e o histórico de reembolsos mostram o status retornado pela Paystack, por exemplo pending, e o ID do reembolso. Se a Paystack não aceitar o reembolso, o bloco mostra Falha no reembolso pela Paystack: com o motivo, e nenhum reembolso é registrado. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a Paystack confirma o pagamento.

O módulo não gera notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Paystack.

Os reembolsos feitos no painel da Paystack e o status final dos reembolsos que a Paystack coloca em fila não são sincronizados de volta com o PrestaShop. Se necessário, registre-os manualmente.

Chave de licença

O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Paystack Payment é o primeiro bloco da página Modules > Module Manager > VibeFox Paystack Payment > 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-paystack 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 do 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 único 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 do domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a Paystack 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. A loja PrestaShop não sabe que você está conectado ao 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 testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de uma 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 inserção da chave, 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

A Paystack 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 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 carrinho é aceita pela Paystack. A caixa de status no topo das configurações indica o problema. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.

O pagamento foi feito, mas nenhum pedido foi criado: 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 exibida em Webhook URL, e se nenhum firewall ou proteção por senha as bloqueia. Ative o Debug log e veja o campo Log para 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, Busy, retry later ou Order could not be created, retry later: a transação não pôde ser lida pela API da Paystack naquele momento, o carrinho estava sendo processado ao mesmo tempo pelo retorno do cliente, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Paystack envia o webhook novamente. O registro mostra o motivo.

O webhook responde OK - unknown reference: o pagamento não foi feito para um carrinho desta loja, por exemplo uma página de pagamento da Paystack ou outra integração na mesma conta. Ele é ignorado.

A URL do webhook mostra Empty body no navegador: isso é normal. A URL aceita apenas requisições da Paystack.

O cliente vê a mensagem «O gateway de pagamento não está configurado corretamente»: a chave secreta do modo atual está ausente ou incorreta. Corrija seguindo a caixa de status no topo das configurações.

O pedido está em Paystack payment on hold após o pagamento: leia as notas de pagamento no bloco Paystack payment (veja Status do pedido) e, em seguida, atenda o pedido ou reembolse o pagamento.

O pedido continua em Awaiting Paystack payment: a Paystack ainda não confirmou o pagamento. Verifique a transação no painel da Paystack e as configurações do webhook. Se o cliente nunca concluiu o pagamento, altere o status manualmente.

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.

Desenvolvedores podem alterar a requisição de transação e a lista de moedas com os hooks do módulo actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies e actionWcpPaystackCurrencyDecimals.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Paystack Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações do módulo e o registro são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento da Paystack dos pedidos, os reembolsos e os status de pedido Awaiting Paystack payment e Paystack payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Paystack é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Paystack.