VibeFox Peach Payments for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior com a extensão OpenSSL (usada para descriptografar os webhooks). O módulo não instala sem elas.
Moeda: a moeda do carrinho deve ser ZAR, KES ou MUR. Para carrinhos em outras moedas, o método de pagamento fica oculto. A página de configurações avisa quando a moeda padrão da loja não é uma delas.
Conta Peach Payments: você precisa das credenciais da Card API da sua conta Peach Payments: o Entity ID e o Access Token. As credenciais de teste vêm do painel sandbox da Peach Payments, e as de produção, do painel da Peach Payments; elas são diferentes. Para os webhooks, você também precisa da chave de descriptografia dos webhooks, que a Peach Payments envia quando ativa os webhooks Card para a sua loja (veja Configuração). Sua loja precisa estar acessível pela internet para receber 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 upload terminar, clique em Configure ou, depois, encontre VibeFox Peach Payments Pay Gateway na lista de módulos e clique em Configure.
3. Informe 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 Entity ID e o Access Token de teste do painel sandbox da Peach Payments e peça à Peach Payments que ative os webhooks Card para a URL do webhook exibida na página de configurações (veja Configuração).
5. Ative Enable/Disable e clique em Save. Mantenha Test mode ativado e faça um pagamento com um cartão de teste do sandbox da Peach Payments. Depois, desative Test mode, informe as credenciais de produção e a chave de webhook de produção e clique em Save.
Na instalação, o módulo cria dois status de pedido: Awaiting Peach Payments payment e Peach Payments payment on hold. O PrestaShop oferece um novo módulo de pagamento para as moedas, países e grupos de clientes ativos naquele momento. Países adicionados depois precisam ser habilitados para o módulo em Payment > Preferences, onde você também pode limitá-los.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Peach Payments 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 mostra avisos: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; um erro quando o Entity ID ou o Access Token do modo atual está ausente (até lá, o método de pagamento não aparece na finalização de compra); um aviso quando a chave de descriptografia dos webhooks do modo atual está ausente (nesse caso, os pagamentos só são confirmados quando o cliente retorna à loja); e um erro quando a moeda padrão da loja não é suportada. Ao salvar, os espaços são removidos das credenciais, e uma chave de webhook que não seja um valor hexadecimal de 64 caracteres é informada com um aviso.
Peach Payments
Enable/Disable: Enable Peach Payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento mostrado ao cliente na finalização de compra. É também o nome do método de pagamento salvo no pedido. Padrão: Credit / Debit Card (Peach Payments). Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
API credentials
O Access Token e o Entity ID da Card API são exibidos no painel da Peach Payments (as credenciais de teste, no painel sandbox). A seção traz links para os dois painéis e para a documentação para desenvolvedores da Peach Payments.
Test mode: envia os novos pagamentos para o sandbox da Peach Payments com as credenciais de teste, e nenhum dinheiro real é cobrado. Desative para aceitar pagamentos reais com as credenciais de produção. Um pagamento iniciado em um modo é sempre verificado nesse modo, mesmo depois que você troca. Padrão: ativado.
Test Entity ID: o Entity ID (canal 3-D Secure) da sua conta sandbox.
Test Access Token: o access token bearer da sua conta sandbox.
Test Webhook Decryption Key: a chave hexadecimal de 64 caracteres usada para descriptografar os webhooks Card do sandbox.
Live Entity ID: o Entity ID (canal 3-D Secure) da sua conta de produção.
Live Access Token: o access token bearer da sua conta de produção.
Live Webhook Decryption Key: a chave hexadecimal de 64 caracteres usada para descriptografar os webhooks Card da sua conta de produção.
Access tokens e chaves de webhook salvos nunca mais são exibidos. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Clear saved secrets: marque um access token ou uma chave de webhook e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Webhook
Os webhooks confirmam os pagamentos mesmo quando o cliente fecha o navegador antes de voltar à loja. O campo Webhook URL mostra a URL do webhook da sua loja. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_peach_pay/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como aparece nas configurações. Peça à Peach Payments (support@peachpayments.com) que ative os webhooks Card para a sua conta com essa URL e, em seguida, informe a chave de descriptografia recebida no campo Webhook Decryption Key do mesmo modo.
A Peach Payments criptografa cada webhook (AES-256-GCM). Um webhook que não pode ser descriptografado com a chave de teste ou de produção é rejeitado, então só a Peach Payments pode alterar os seus pedidos. Um webhook descriptografado com a chave de um modo se aplica apenas aos pagamentos iniciados nesse modo. O módulo usa as notificações de pagamento a seguir:
Outras notificações, por exemplo a notificação de teste enviada quando o webhook é ativado, recebem a resposta ignored. Sem a chave de webhook, um pedido só é criado quando o cliente volta à loja depois de pagar.
Payment form
Card brands: as bandeiras exibidas no formulário da Peach Payments: Visa, Mastercard, American Express, Diners Club. Selecione apenas as bandeiras habilitadas para o seu Entity ID. Padrão: Visa e Mastercard. Se nenhuma bandeira for selecionada, ao salvar aparece um aviso e o formulário mostra Visa e Mastercard.
Advanced
Logging: registra as requisições à API e os resultados dos pagamentos em logs/peach_p_debug.log.php, na pasta do módulo. O arquivo não pode ser lido pela web. Erros e avisos são sempre registrados. Os logs não contêm dados de cartão, chaves ou dados do cliente. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, ao desinstalar o módulo, as configurações e os logs dele são excluídos. Os dados da Peach Payments dos pedidos (tentativas de pagamento, IDs de pagamento) e os status dos pedidos são mantidos, porque pertencem aos pedidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Credit / Debit Card (Peach Payments)) e confirma o pedido. No modo de teste, o método de pagamento mostra Test mode: no real payment will be made. O módulo prepara uma finalização de compra da Peach Payments pelo total do carrinho, na moeda do carrinho, e exibe a página Peach Payments payment da sua loja com o formulário de cartão da Peach Payments e as bandeiras de cartão selecionadas, no idioma do cliente quando a Peach Payments o suporta. No modo de teste, a página mostra Test mode: use a Peach Payments test card, no real payment will be made. Os dados do cartão são informados no formulário da Peach Payments, e o script do formulário é carregado com um hash de Subresource Integrity. O link Choose another payment method volta para a finalização de compra. Nesse ponto, ainda não existe nenhum pedido. Recarregar a página reutiliza a mesma finalização de compra por até 25 minutos, a menos que o carrinho tenha mudado.
Após o pagamento, o cliente retorna à sua loja. O pedido só é marcado como pago depois que a Peach Payments confirma: a loja consulta o resultado da finalização de compra desse carrinho na API da Peach Payments, no modo em que a finalização foi criada, e verifica se o pagamento pertence a esse carrinho. O webhook faz o mesmo de forma independente, então quem chegar primeiro cria o pedido, e o outro não altera nada. Em seguida, o cliente vê a página padrão de confirmação do pedido.
Se o pagamento não for concluído, o cliente volta à finalização de compra com uma mensagem e pode tentar novamente: Payment failed: seguido do motivo informado pela Peach Payments e de Please try again or use another card., ou The payment was not completed. Please try again. O carrinho é mantido. Se o resultado ainda não puder ser confirmado (por exemplo, a Peach Payments não respondeu ou o webhook está processando exatamente o mesmo carrinho naquele momento), a mensagem é We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Quando não há chave de webhook definida para o modo do pagamento, o cliente é orientado a entrar em contato com você.
Se o formulário de pagamento não puder ser preparado, o cliente permanece na finalização de compra com uma mensagem curta: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (credenciais ausentes ou incorretas), uma mensagem informando que alguns dados de cobrança não foram aceitos pelo provedor de pagamento, ou The payment form could not be loaded. Please try again in a moment. O motivo técnico é gravado no log.
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 cartão na própria etapa de finalização de compra, nem cartões salvos, assinaturas, pré-autorização e captura, nem EFT, BNPL, QR ou outros métodos sem cartão.
Pedidos
Status do pedido
No order yet: o cliente não pagou, o pagamento foi recusado ou não foi concluído, ou a Peach Payments ainda não o confirmou. Existe apenas o carrinho, e o cliente pode pagar novamente.
Payment accepted: o pagamento foi confirmado, e o valor e a moeda correspondem ao carrinho. O pagamento é registrado com o ID do pagamento da Peach Payments como ID da transação, e uma nota mostra o código de resultado, a descrição e o ID do pagamento da Peach Payments. Se a Peach Payments sinalizou o pagamento para análise manual, a nota pede que você o verifique no painel da Peach Payments antes de enviar o pedido.
Awaiting Peach Payments payment: a Peach Payments informou um pagamento que aguarda confirmação. Depois, o webhook move o pedido para Payment accepted ou o marca como falho.
Peach Payments payment on hold: o valor ou a moeda pagos diferem do carrinho (nota amount/currency mismatch — manual review required), ou o pagamento chegou depois que o pedido foi cancelado. A nota explica o que verificar. Confira o pagamento no painel da Peach Payments e, em seguida, processe o pedido ou reembolse o pagamento.
Payment error: a Peach Payments recusou o pagamento que o pedido aguardando estava esperando. Uma tentativa recusada nunca altera um pedido pago, em espera ou cancelado.
Se um segundo pagamento de um pedido já pago for aprovado, o pedido não é alterado. Uma nota informa que se trata de um pagamento duplicado e pede que você o reembolse no painel da Peach Payments. Um pagamento recebido para um pedido reembolsado é apenas anotado no pedido.
Bloco de pagamento da Peach Payments
A página do pedido mostra um bloco Peach Payments payment com o ID do pagamento, o ID do checkout, o ID da transação do lojista, o valor enviado à Peach Payments, o resultado e o código de resultado, um selo Test mode para pagamentos de teste e as Peach Payments notes do pedido.
Reembolsos
Reembolsos pela página de pedidos do PrestaShop não estão disponíveis. Reembolse o pagamento no painel da Peach Payments e registre-o no PrestaShop (reembolso parcial ou nota de crédito), se necessário. Com o webhook configurado, reembolsos, estornos e contestações feitos na Peach Payments são adicionados às notas do pedido com o valor e o ID; o status do pedido não muda.
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 Peach Payments Pay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Peach Payments 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-peach e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Apenas 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 de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Peach Payments não é exibida 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 loja do 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. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados pelo retorno do cliente e pelo webhook.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 e depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Peach Payments não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o Entity ID e o Access Token do modo atual foram informados (Test Entity ID e Test Access Token no modo de teste, Live Entity ID e Live Access Token no modo de produção) e se a moeda do carrinho é ZAR, KES ou MUR. Os avisos no topo das configurações indicam 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 aprovado, mas nenhum pedido foi criado: o cliente não voltou à loja e o webhook não chegou. Verifique se a Peach Payments ativou os webhooks Card exatamente para a URL exibida nas configurações, se a Webhook Decryption Key do modo em que o pagamento foi feito está informada e se nenhum firewall ou proteção por senha bloqueia a URL. Ative o Logging e consulte o campo Log para ver os webhooks rejeitados.
O webhook responde Decryption failed: o webhook não pôde ser descriptografado com a chave de teste nem com a de produção. A chave está errada ou pertence a outra conta ou modo. Informe a chave que a Peach Payments enviou para esta URL de webhook.
O webhook responde Webhook key not configured: nenhuma das chaves de webhook (de teste ou de produção) está definida ou é válida. Informe a chave de 64 caracteres. A Peach Payments enviará o webhook novamente mais tarde.
O webhook responde Busy, retry later: o carrinho estava sendo processado pelo retorno do cliente naquele mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). Nada foi alterado, e a Peach Payments envia o webhook novamente. O log mostra o motivo.
O webhook responde Missing or malformed data: a requisição não tinha corpo criptografado nem os cabeçalhos X-Initialization-Vector / X-Authentication-Tag, por exemplo porque um proxy a alterou. Nada foi alterado.
O webhook responde ignored: a notificação é autêntica, mas não pertence a uma finalização de compra desta loja (outra loja com o mesmo Entity ID, um carrinho excluído) ou veio de um modo diferente do pagamento. Nada foi alterado.
A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da Peach Payments.
O cliente vê The payment form is not available right now: o Access Token ou o Entity ID do modo atual está incorreto. Verifique as credenciais e o modo e consulte o log para ver o código da Peach Payments.
O pedido está em Peach Payments payment on hold após o pagamento: leia as notas no bloco Peach Payments payment. O valor ou a moeda pagos eram diferentes do carrinho, ou o pagamento chegou depois que o pedido foi cancelado. Verifique o pagamento no painel da Peach Payments e, em seguida, processe o pedido ou reembolse o pagamento.
Ao salvar, aparece a mensagem de que a chave do webhook deve ser a chave hexadecimal de 64 caracteres: o valor não é a chave fornecida pela Peach Payments. Os webhooks não podem ser descriptografados até que ela seja corrigida.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Peach Payments 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 data on uninstall estiver ativado, as configurações e os logs do módulo são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As tentativas de finalização de compra, os IDs de pagamento e os status de pedido Awaiting Peach Payments payment e Peach Payments payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e dados de finalização de compra da Peach Payments.
A Peach Payments é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Peach Payments.