VibeFox Cashfree for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 6.0 ou superior, instalado e ativo. O plugin se recusa a ser ativado sem ele.
PHP: 8.0 ou superior.
HTTPS: a Cashfree entrega webhooks apenas a 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, então não há um segredo de webhook separado. A moeda do pedido 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 WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_cashfree_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Cashfree Payments > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira o Sandbox App ID e a Sandbox Secret Key, adicione o webhook no Cashfree Merchant Dashboard (veja Configuração), ative Enable/Disable e teste um pagamento.
6. Quando estiver pronto, insira o App ID e a Secret Key de produção e desmarque Sandbox Mode.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Cashfree Payments. Quando o método de pagamento está ativado, a página avisa se as chaves de API do modo selecionado estão ausentes (o método de pagamento fica então oculto na finalização de compra) e mostra Sandbox mode is on: customers see a test checkout and no real money is charged. enquanto o modo de teste estiver ativado. Ao salvar um gateway ativado sem as chaves do modo selecionado, uma mensagem de erro informa que o método de pagamento continua oculto na finalização de compra até que sejam definidas.
Geral
Enable/Disable: Enable Cashfree Payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Cashfree Payments.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.
Modo e chaves de API
Obtenha o App ID e a Secret Key no Cashfree Merchant Dashboard, em Developers > API Keys. As chaves de teste e de produção são diferentes; informe cada uma na sua seção.
Sandbox Mode: Enable Sandbox (test) mode usa o sandbox da Cashfree para testes. Nenhum dinheiro real é cobrado, e o checkout mostra SANDBOX MODE - no real payments will be processed. Padrão: ativado. Desmarque para pagamentos reais.
Credenciais de teste
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.
Credenciais de produção
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.
Os pedidos mantêm o ambiente em que foram criados. Os webhooks deles são verificados e os reembolsos são enviados com as chaves desse ambiente; por isso, mantenha as chaves de teste preenchidas até que os pedidos de teste estejam concluídos depois da mudança para a produção.
Webhook
O webhook informa à sua loja que um pagamento foi feito, falhou ou foi reembolsado. No Cashfree Merchant Dashboard, acesse Developers > Webhooks e adicione a URL exibida nesta seção, com os eventos Payment e Refund. Ela tem a forma https://your-site/wc-api/cashfree_p/?action=webhook. Em um site com HTTPS, o plugin também envia esta URL à Cashfree em cada pedido. Se o seu site não usa HTTPS, esta seção mostra um aviso.
O plugin trata estes eventos:
A Cashfree assina cada webhook com a sua Secret Key. Webhooks sem assinatura válida são rejeitados. Webhooks assinados de pedidos que não foram criados por esta loja (por exemplo, de outra loja na mesma conta Cashfree) são confirmados e ignorados. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja depois de pagar. Se o cliente fechar o navegador depois de pagar, somente o webhook pode confirmar o pedido.
Avançado
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 pedido no WooCommerce; uma tentativa repetida recebe um número no final. Deixe em branco para usar o prefixo automático deste site, exibido na descrição do campo. Use um prefixo diferente para cada loja conectada à mesma conta Cashfree. Somente letras, dígitos, "_" e "-", até 20 caracteres. Outros caracteres são removidos ao salvar, com uma mensagem.
Debug log: Log Cashfree API events for debugging. Erros são sempre registrados. Quando ativado, as chamadas de API e os webhooks também são gravados em WooCommerce > Status > Logs, origem wcp_cashfree_payment. Chaves e dados do cliente nunca são registrados. Padrão: desativado.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Quando ativado, excluir o plugin remove as configurações da Cashfree, os logs do plugin e as referências da Cashfree armazenadas nos pedidos. Os pedidos em si são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Cashfree Payments) e faz o pedido. O plugin cria um pedido Cashfree para o total do pedido na moeda do pedido e abre a página Pay for order, 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.
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 requisição de servidor para servidor à Cashfree quando o cliente volta. Se o banco ainda não tiver confirmado o pagamento, a página de pedido recebido mostra Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.
Se o pagamento falhar ou o cliente sair da página da Cashfree sem pagar, ele volta à página Pay for order com The Cashfree payment was not completed. Please try again or choose another payment method. Um pagamento aberto na Cashfree é reaproveitado quando o cliente tenta de novo. Se o total do pedido mudou ou a sessão está prestes a expirar, o pedido antigo na Cashfree é encerrado e um novo é criado, então o pedido não pode ser pago duas vezes. Se o pedido já tiver sido pago na Cashfree, mas não registrado, a próxima tentativa registra o pagamento em vez de cobrar de novo.
Se a Cashfree não conseguir iniciar o pagamento, o cliente vê 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 pedido 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.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS). Os textos exibidos ao cliente são traduzidos para o hindi.
O plugin aceita pagamentos únicos somente 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, COD pela Cashfree ou links de pagamento, e não há conversão de moeda: o pedido é cobrado na moeda do pedido.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Cashfree e ainda não pagou, ou o pagamento ainda está pendente no banco. Quando o cliente volta com um pagamento pendente, uma nota informa que o plugin está aguardando o webhook da Cashfree.
Processing: o pagamento foi confirmado (pedidos apenas com produtos virtuais para download passam a Concluído, o padrão do WooCommerce). A nota do pedido mostra o ID da transação na Cashfree e o grupo do método de pagamento. O ID da transação do pedido é o ID do pagamento na Cashfree. Um pagamento que chega depois de o pedido ter sido cancelado ainda é registrado, porque o dinheiro foi cobrado.
On hold: a Cashfree informou um valor ou uma moeda pagos diferentes do total do pedido. A nota do pedido mostra o valor esperado e o recebido, e o ID da transação. Verifique o pagamento no painel da Cashfree e conclua ou reembolse o pedido manualmente.
Failed: o pagamento falhou ou foi cancelado na Cashfree. A nota mostra o status e o motivo da Cashfree. Cada nova tentativa falha adiciona uma nota.
Um pedido pago nunca volta a ser alterado por um webhook ou retorno posterior.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Cashfree Payments (o botão mostra o título do método de pagamento). São compatíveis reembolsos totais e parciais. O reembolso é enviado ao pedido Cashfree que foi pago, no ambiente (teste ou produção) em que ele foi pago, por isso as chaves desse ambiente precisam estar definidas. Se a Cashfree não aceitar o reembolso, ou o informar como cancelado ou rejeitado, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso iniciado é adicionado às notas do pedido com o seu ID, valor e status. O status final chega pelo webhook de reembolso, como outra nota do pedido.
Os webhooks de status de reembolso são adicionados apenas como notas. Eles não são registrados automaticamente como reembolsos do WooCommerce.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Cashfree Payments. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Cashfree não é mostrada 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. Gerentes da loja logados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente automaticamente, em segundo plano.
Solução de problemas
A Cashfree não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem as suas chaves: Sandbox App ID e Sandbox Secret Key no modo de teste, App ID e Secret Key no modo de produção. O método de pagamento também fica oculto quando o total do pedido está abaixo do mínimo da Cashfree. A página de configurações mostra um aviso quando as chaves estão ausentes.
O pagamento foi feito, mas o pedido continua com o status Pending payment: o webhook não está funcionando. Verifique se o seu site usa HTTPS, se a URL em Developers > Webhooks é exatamente a exibida nas configurações e se os eventos de pagamento estão selecionados. Confira se a Secret Key nas configurações pertence ao ambiente em que o pedido foi pago. O pedido também é confirmado quando o cliente volta à loja depois de pagar, e na próxima tentativa de pagamento.
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 pedido foi criado. A Cashfree tenta reenviar o webhook.
O webhook responde Ignored: o webhook está assinado corretamente, mas pertence a um pedido que não foi criado 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 processado por outra requisição no mesmo momento. A Cashfree tenta reenviar o webhook.
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 em Pay Now de novo ou em Choose another payment method.
O cliente vê We could not start the Cashfree payment: ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_cashfree_payment. Os motivos mais comuns são chaves erradas para o modo selecionado ou uma moeda que não está habilitada na sua conta Cashfree.
O cliente vê The minimum amount for a Cashfree payment is …: o total do pedido está abaixo do mínimo da Cashfree para a moeda.
O cliente vê We could not verify the payment: o link de retorno não correspondeu ao pedido. Se o dinheiro foi cobrado, o webhook ainda confirma o pedido. Verifique o pagamento no painel da Cashfree antes de o cliente pagar novamente.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido. Conclua o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre modo de teste ou de produção: o pedido foi pago nesse ambiente, e as chaves da API dele não estão definidas. Informe-as e tente de novo.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway, os dados da Cashfree armazenados nos pedidos e os logs são removidos somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Cashfree é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Cashfree.