VibeFox Cashfree for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.

HTTPS: a Cashfree envia webhooks apenas para URLs https://. Sem HTTPS os pagamentos ainda são confirmados quando o cliente volta à loja, mas ative o HTTPS antes de entrar em produção.

Conta Cashfree: você precisa do App ID e da Secret Key da sua conta Cashfree, separadamente para o ambiente de teste (sandbox) e para o de produção, e de um webhook no Cashfree Merchant Dashboard (veja Configuração). A Secret Key também é usada para verificar os webhooks, por isso não existe um segredo de webhook separado. A moeda do carrinho precisa estar habilitada na sua conta Cashfree.

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 Cashfree Payments na lista de módulos e clique em Configure.

3. Informe 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 Sandbox App ID e a Sandbox Secret Key, adicione o webhook no Cashfree Merchant Dashboard (veja Configuração), ative o Enable/Disable, clique em Save e teste um pagamento.

5. Quando estiver pronto, informe o App ID e a Secret Key de produção, desative o Sandbox Mode e clique em Save.

Ao ser instalado, o módulo cria o status de pedido Cashfree 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á-los em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Cashfree Payments > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página explica que o pedido só é criado depois que a Cashfree confirma o pagamento. Quando o método de pagamento está ativado, a página avisa se as chaves de API do modo selecionado estão faltando (nesse caso o método fica oculto na finalização da compra) e mostra Sandbox mode is on: customers see a test checkout and no real money is charged. enquanto o modo sandbox estiver ativo. Se você salvar um método de pagamento ativado sem as chaves do modo selecionado, um aviso informa que ele continuará oculto na finalização da compra até que as chaves sejam preenchidas.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments liga ou desliga o método de pagamento. Padrão: off.

Title: o nome do método de pagamento que o cliente vê na finalização da compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Cashfree Payments. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização da compra. Padrão: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

Obtenha o App ID e a Secret Key no Cashfree Merchant Dashboard, em Developers > API Keys. As chaves de teste e as de produção são diferentes.

Sandbox Mode: usa o sandbox da Cashfree para testes. Nenhum dinheiro real é cobrado, e a finalização da compra exibe SANDBOX MODE - no real payments will be processed. abaixo do método de pagamento. Padrão: on. Desative para pagamentos reais.

Sandbox App ID: o App ID do seu ambiente de teste da Cashfree.

Sandbox Secret Key: a Secret Key do seu ambiente de teste da Cashfree.

App ID: o App ID do seu ambiente de produção da Cashfree.

Secret Key: a Secret Key do seu ambiente de produção da Cashfree.

As Secret Keys salvas nunca são exibidas novamente. 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 uma Secret Key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Os pagamentos mantêm o ambiente em que foram criados. Seus webhooks são verificados, o status é consultado e os reembolsos são enviados com as chaves desse ambiente. Por isso, mantenha as chaves de sandbox preenchidas até que os pagamentos de sandbox sejam liquidados após a mudança para produção.

Webhook

O webhook informa à sua loja que um pagamento foi feito, falhou ou foi reembolsado. No Cashfree Merchant Dashboard, vá em Developers > Webhooks e adicione a URL exibida em Webhook URL nesta seção, com os eventos Payment e Refund. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_cashfree_payment/webhook. Copie a URL exatamente como as configurações a mostram. Em uma loja com HTTPS, o módulo também envia esta URL à Cashfree em cada pagamento. Se a sua loja não usar HTTPS, esta seção exibe um aviso.

O módulo trata estes eventos (eles também estão listados nesta seção):

A Cashfree assina cada webhook com a sua Secret Key. Webhooks sem assinatura válida são rejeitados. Um webhook precisa ser assinado com a Secret Key do ambiente em que o pagamento foi feito, então uma chave de sandbox nunca confirma um pagamento real. Webhooks assinados de pagamentos que não foram iniciados por esta loja (por exemplo, outra loja na mesma conta Cashfree) são reconhecidos e ignorados. Sem o webhook, um pedido só é criado quando o cliente volta à loja depois de pagar. Se o cliente fechar o navegador depois de pagar, apenas o webhook (ou a próxima tentativa de pagamento do mesmo carrinho) pode criar o pedido.

Advanced

API Version: a versão da API da Cashfree a ser usada.

Order ID prefix: os IDs de pedido na Cashfree são formados por prefixo + ID do carrinho do PrestaShop; uma nova tentativa para o mesmo carrinho recebe um número no final (por exemplo, 123-2). Deixe vazio para usar o prefixo automático desta loja, exibido na descrição do campo. Use um prefixo diferente para cada loja conectada à mesma conta Cashfree. Somente letras, números, "_" e "-", até 20 caracteres. Os demais caracteres são removidos ao salvar, com um aviso.

Debug log: os erros são sempre registrados. Quando ativado, as chamadas à API da Cashfree e os webhooks também são gravados em logs/cashfree_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados de clientes nunca são registrados. Padrão: off.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.

Delete Data on Uninstall: quando ativado, desinstalar o módulo remove as configurações da Cashfree e o log do módulo. Pedidos, suas transações e reembolsos na Cashfree e o status de pedido Cashfree payment on hold sempre permanecem, para que os pedidos existentes continuem funcionando. Padrão: off.

Finalização da compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Cashfree Payments) e confirma. O módulo cria um pedido na Cashfree pelo total do carrinho na moeda do carrinho e abre uma página de pagamento que mostra Redirecting to Cashfree for payment... e carrega o checkout da Cashfree. Se ele não abrir sozinho, o cliente pode clicar em Pay Now. No checkout da Cashfree, o cliente paga com qualquer método ativado na sua conta Cashfree, por exemplo cartão, UPI, Net Banking ou carteira. O e-mail e o telefone de cobrança do cliente são enviados à Cashfree. Neste ponto, ainda não existe nenhum pedido.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Cashfree confirma: pelo webhook assinado ou por uma solicitação do servidor à Cashfree quando o cliente retorna. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. O retorno também funciona em outro navegador, por exemplo quando o cliente volta de um aplicativo UPI. Se o banco ainda não tiver confirmado o pagamento, uma página Payment confirmation exibe Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. e um botão Check again; o webhook cria o pedido assim que o banco confirma o pagamento.

Se o pagamento falhar ou o cliente sair da página da Cashfree sem pagar, ele volta à finalização da compra com The Cashfree payment was not completed. Please try again or choose another payment method. O carrinho é mantido. Um pagamento aberto na Cashfree é reaproveitado quando o cliente tenta de novo. Se o total do carrinho mudou ou a sessão está prestes a expirar, o pedido antigo na Cashfree é encerrado e um novo é criado, para que o carrinho não possa ser pago duas vezes. Se o carrinho já foi pago na Cashfree, mas não foi registrado, a próxima tentativa cria o pedido em vez de cobrar de novo.

Se a Cashfree não conseguir iniciar o pagamento, o cliente permanece na finalização da compra com We could not start the Cashfree payment. Please try again or choose another payment method. O motivo técnico é gravado no log. Um total de carrinho abaixo do mínimo da Cashfree (1 unidade da moeda; 0,01 para BHD, JOD, KWD e OMR, e 0,1 para TND) não pode ser pago com a Cashfree, e o método de pagamento não é exibido para esse carrinho.

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

O módulo aceita somente pagamentos únicos no checkout da Cashfree. Não há cartões salvos, assinaturas ou pagamentos recorrentes, nem autorização e captura separadas, nem widget de ofertas da Cashfree, nem COD ou links de pagamento pela Cashfree, e não há conversão de moeda: o carrinho é cobrado na moeda do carrinho.

Pedidos e reembolsos

Order statuses

No order yet: o cliente foi enviado à Cashfree e não pagou, o pagamento falhou ou o pagamento ainda está pendente no banco. Existe apenas o carrinho.

Payment accepted: o pagamento foi confirmado. O pagamento é registrado com o ID de pagamento da Cashfree como ID de transação, e uma nota mostra o ID da transação e o grupo do método de pagamento (por exemplo, upi ou credit_card).

Cashfree payment on hold: a Cashfree informou um valor ou uma moeda pagos que diferem do total do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou). A nota mostra o valor esperado e o recebido e o ID da transação. Verifique o pagamento no Cashfree Dashboard e depois atenda o pedido ou reembolse o pagamento.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Um pagamento que chega depois que o pedido foi cancelado continua sendo registrado, e o pedido volta a ficar pago, porque o dinheiro foi cobrado. Um pedido pago nunca é revertido por um pagamento posterior que falhou.

Cashfree payment block

A página do pedido mostra um bloco Cashfree payment com o ID da transação, o pedido na Cashfree, o status do pagamento, o valor pago e reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as Cashfree notes do pedido.

Refunds

No bloco Cashfree payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Cashfree. Confirme a pergunta Refund this amount through Cashfree? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa da permissão para editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são feitos no valor e na moeda que a Cashfree cobrou, então, depois de uma divergência de valor, você pode reembolsar até o que o cliente efetivamente pagou, não o total do pedido. O reembolso é enviado ao pedido pago na Cashfree, no ambiente (sandbox ou produção) em que foi pago, por isso as chaves desse ambiente precisam estar preenchidas. Se a Cashfree não aceitar o reembolso, ou o informar como cancelado ou recusado, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso iniciado é adicionado ao histórico de reembolsos e às notas com o seu ID, valor e status. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a Cashfree confirma o pagamento.

O status final do reembolso chega pelo webhook de reembolso e é adicionado às notas. O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Cashfree.

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 Cashfree Payments é o primeiro bloco de Modules > Module Manager > VibeFox Cashfree Payments > 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-cashfree e o link Manage licenses and domains in your account, que abre sua conta em vibefox.net. Apenas 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 ú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 em vibefox.net.

Sem uma chave ativa, a Cashfree não é exibida aos clientes na finalização da compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A vitrine 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 da 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 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 chave ser inserida 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 Cashfree não aparece na finalização da compra: verifique se a licença está ativa, se o Enable/Disable está ligado e se o modo atual tem as suas chaves: Sandbox App ID e Sandbox Secret Key no modo sandbox, App ID e Secret Key no modo de produção. A página de configurações exibe um aviso quando as chaves estão faltando. O método de pagamento também fica oculto quando o total do carrinho está abaixo do mínimo da Cashfree. 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 está funcionando. Verifique se a sua loja usa HTTPS, se a URL em Developers > Webhooks é exatamente a exibida em Webhook URL e se os eventos Payment estão selecionados. Verifique se a Secret Key nas configurações pertence ao ambiente em que o pagamento foi feito. O Cashfree Dashboard mostra a resposta da sua loja para cada webhook. O pedido também é criado quando o cliente volta à loja depois de pagar, e na próxima tentativa de pagamento do mesmo carrinho.

O webhook responde Missing signature ou Invalid signature: a chamada não trouxe uma assinatura válida da Cashfree, ou a Secret Key nas configurações não corresponde ao ambiente em que o pagamento foi feito. Verifique se as chaves de sandbox e de produção não estão trocadas.

O webhook responde Ignored: o webhook está assinado corretamente, mas pertence a um pagamento que não foi iniciado por esta loja, por exemplo outra loja na mesma conta Cashfree. Dê a cada loja o seu próprio Order ID prefix.

O webhook responde Busy, retry later: o pedido estava sendo criado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Cashfree tenta o webhook novamente. Ative o Debug log para ver o motivo.

O cliente vê The Cashfree payment page could not be loaded: o script da Cashfree não pôde ser carregado no navegador, por exemplo por causa de um bloqueador. O cliente pode clicar novamente em Pay Now ou em Choose another payment method.

O cliente vê We could not start the Cashfree payment: veja o campo Log na página do módulo. Os motivos típicos são chaves erradas para o modo selecionado ou uma moeda que não está habilitada na sua conta Cashfree.

O cliente vê We could not verify the payment: o link de retorno não correspondeu ao carrinho. Se houve cobrança, o webhook ainda cria o pedido. Verifique o pagamento no Cashfree Dashboard antes de o cliente pagar de novo.

O pedido está em Cashfree payment on hold após o pagamento: leia as notas no bloco Cashfree payment (veja Order statuses) e depois atenda o pedido ou reembolse o pagamento.

O reembolso falha com uma mensagem sobre modo sandbox ou produção: o pagamento foi feito nesse ambiente, e as chaves de API dele não estão preenchidas. Informe-as e tente novamente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Cashfree Payments 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 da Cashfree e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos na Cashfree e o status de pedido Cashfree 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.

Cashfree é uma marca de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Cashfree.