VibeFox Razorpay for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Conta Razorpay: você precisa do Key ID e do Key Secret da sua conta Razorpay para o modo de teste e, para o modo de produção, depois que a sua conta for ativada. Recomenda-se muito um webhook com um segredo de sua escolha (veja Configuração). Pagamentos em moedas diferentes de INR exigem que International Payments esteja ativado na sua conta Razorpay.

Chave de licença VibeFox: adquirida 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_razorpay_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Razorpay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite o seu Test Key ID e o seu Test Key Secret, configure o webhook no Razorpay Dashboard e digite o segredo dele (veja Configuração).

6. Ative Enable/Disable e faça um pagamento de teste com Test mode ligado. Quando estiver pronto, digite as chaves Live e desmarque Test mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Razorpay. Acima dos campos, a página mostra avisos: faltam as chaves do modo atual (o método de pagamento fica oculto na finalização de compra), o Key ID não começa com rzp_test_ no modo de teste ou com rzp_live_ no modo de produção, o modo de teste está ativado, o segredo do webhook está vazio, ou a moeda da loja não é INR e exige que International Payments esteja ativado na sua conta Razorpay. Na lista de métodos de pagamento, a Razorpay aparece como precisando de configuração até que o modo atual tenha suas chaves, e um selo Test mode aparece enquanto o modo de teste estiver ativado. Espaços colados junto com as chaves são removidos ao salvar.

Geral

Enable/Disable: Enable Razorpay Payment Gateway 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: UPI, Cards, NetBanking.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

Chaves de API

Obtenha as suas chaves no Razorpay Dashboard, em Account & Settings > API Keys. Mude o Dashboard para o modo de teste para gerar chaves de teste (rzp_test_...). As chaves de produção (rzp_live_...) ficam disponíveis depois que a sua conta for ativada.

Test mode: Use the Test mode keys (no real money is charged). Padrão: ligado. Desmarque para receber pagamentos reais. Pagamentos, capturas e reembolsos de um pedido sempre usam as chaves do modo em que o pedido foi pago, então trocar o modo depois não afeta os pedidos existentes.

Test Key ID: o Key ID do Razorpay Dashboard no modo de teste. Ele começa com rzp_test_.

Test Key Secret: o Key Secret do Razorpay Dashboard no modo de teste.

Live Key ID: o Key ID do Razorpay Dashboard no modo de produção. Ele começa com rzp_live_.

Live Key Secret: o Key Secret do Razorpay Dashboard no modo de produção.

Pagamento

Payment Action: quando o dinheiro é cobrado. Padrão: Authorize & Capture.

Webhook

O webhook confirma os pagamentos mesmo quando o cliente fecha o navegador logo após pagar, e registra os reembolsos feitos no Razorpay Dashboard. No Razorpay Dashboard, acesse Account & Settings > Webhooks e adicione um webhook no modo de teste e outro no modo de produção. Use a URL exibida nesta seção das configurações. Ela tem a forma https://your-site/wc-api/razorpay_p_webhook/. Copie-a exatamente como as configurações a mostram. Informe na Razorpay um segredo de sua escolha e selecione estes eventos:

Webhook Secret: o segredo que você informou ao criar o webhook. Use o mesmo segredo para o webhook de teste e o de produção, porque o plugin tem um único campo para os dois. Webhooks sem uma assinatura válida são rejeitados. Sem o webhook, um pagamento só é confirmado quando o cliente volta da janela pop-up ou reabre mais tarde a página de pagamento do pedido.

Avançado

Enable Logging: Save debug logs. O log fica em WooCommerce > Status > Logs, origem wcp_razorpay_payment. Erros e avisos são sempre registrados; esta opção acrescenta os detalhes de depuração. Chaves, assinaturas e dados de contato do cliente nunca são registrados. Padrão: desativado.

Delete Data on Uninstall: Remove the plugin settings and logs when the plugin is deleted (orders are never touched). Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão, UPI, Cards, NetBanking) e faz o pedido. O plugin cria um pedido na Razorpay com o valor total exato e a moeda do pedido, e abre a página de pagamento do pedido. A janela pop-up do Razorpay Checkout abre automaticamente ali, com nome, e-mail e telefone do cliente já preenchidos. Se a janela for fechada, o cliente pode clicar em Pay Now para abri-la novamente ou em Cancel order. No modo de teste, a página mostra Razorpay Test mode: no real money will be charged.

Após um pagamento bem-sucedido, o plugin verifica a assinatura da Razorpay, busca o pagamento pela API da Razorpay e compara o valor e a moeda com os do pedido. O pedido só é marcado como pago depois que a Razorpay confirma. Em seguida, o cliente vê a página de pedido recebido. Se a assinatura for válida, mas o pagamento não puder ser buscado naquele momento, o pedido é colocado em «Em espera» e o webhook o confirma mais tarde.

Se o cliente voltar a um pedido não pago, o plugin reutiliza o pedido correspondente na Razorpay. Se esse pedido da Razorpay já tiver sido pago, por exemplo porque o cliente fechou o navegador e não há webhook, o plugin aplica o pagamento em vez de pedir um segundo.

Mensagens que o cliente pode ver:

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. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita apenas pagamentos únicos. Não há assinaturas nem pagamentos recorrentes, cartões salvos, Razorpay Magic Checkout, Payment Links ou Route (pagamentos divididos), nem widgets de oferta ou de acessibilidade de pagamento.

Pedidos e reembolsos

Order statuses

Pending payment: o pedido na Razorpay foi criado e o cliente ainda não pagou. Cada pedido da Razorpay é adicionado às notas do pedido com o seu valor e o seu modo.

Processing or Completed: o pagamento foi capturado e confirmado; é o status padrão do WooCommerce após o pagamento. A nota do pedido mostra o ID do pagamento na Razorpay, o valor e como ele foi confirmado (retorno, webhook ou verificação ao voltar). O ID da transação é o ID do pagamento na Razorpay (pay_...).

On hold: definido nestes casos, cada um com uma nota do pedido: o pagamento foi apenas autorizado (Authorize Only), o valor ou a moeda pagos não correspondem ao pedido, o pagamento foi capturado para um pedido cancelado, ou o pagamento não pôde ser verificado pela API da Razorpay naquele momento. Um pedido que já está em «Em espera» também recebe a nota.

Failed: o webhook payment.failed chegou para um pedido pendente. A nota mostra o erro da Razorpay. O cliente ainda pode pagar novamente; um pedido que já tenha um pagamento autorizado ou capturado não é alterado.

Cancelled: o cliente clicou em Cancel order, ou o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce. Um pagamento que chegue depois não o reabre automaticamente: um pagamento autorizado não é capturado, e um pagamento capturado coloca o pedido em «Em espera» para a sua análise.

Se chegar um pagamento adicional para um pedido que já está pago, o pedido não muda. Uma nota pede que você o reembolse no Razorpay Dashboard, caso não seja intencional.

Captura (Authorize Only)

Abra o pedido em «Em espera», escolha Capture Razorpay payment em Order actions e clique no botão de atualizar. O pagamento é capturado no modo em que foi autorizado, e o pedido passa a pago. Se a Razorpay recusar, a nota do pedido mostra Razorpay capture failed: com o motivo. Uma captura feita no Razorpay Dashboard conclui o pedido pelo webhook.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via, seguido do título do método de pagamento. São aceitos reembolsos totais e parciais. O reembolso é enviado com as chaves do modo em que o pagamento foi feito. Se a Razorpay não aceitar o reembolso, o WooCommerce mostra Razorpay refund failed: com o motivo, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso na Razorpay, o valor e o status.

Reembolsos feitos no Razorpay Dashboard chegam pelo webhook e são registrados no pedido como reembolsos do WooCommerce, uma única vez e sem devolver itens ao estoque. Um reembolso feito no Dashboard em outra moeda ou acima do valor reembolsável não é registrado automaticamente; uma nota pede que você o registre manualmente.

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 > Razorpay. 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 digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na 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 na vibefox.net.

Sem uma chave ativa, a Razorpay 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. Os gerentes da loja que estiverem conectados continuam vendo 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. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente, automaticamente, em segundo plano.

Solução de problemas

A Razorpay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o modo atual tem as duas chaves: Test Key ID e Test Key Secret no modo de teste, Live Key ID e Live Key Secret no modo de produção. A página de configurações mostra um aviso quando elas estão faltando.

O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não está funcionando. No Razorpay Dashboard, verifique se o webhook existe no modo que você usa (teste ou produção), se a URL dele é exatamente a exibida nas configurações e se os cinco eventos estão selecionados. Confira se o Webhook Secret é o mesmo segredo informado na Razorpay. O pedido também é confirmado quando o cliente reabre a página de pagamento do pedido.

O webhook responde Webhook secret not configured: o Webhook Secret está vazio. Informe o segredo do webhook da Razorpay. A Razorpay reenviará o evento mais tarde.

O webhook responde Invalid signature ou Missing signature: o segredo nas configurações é diferente do segredo do webhook na Razorpay. Informe o mesmo segredo nos dois lugares.

O webhook responde Retry later: o plugin não conseguiu confirmar uma captura pela API da Razorpay, ou o pedido estava sendo atualizado por outra solicitação naquele momento. A Razorpay reenviará o evento automaticamente.

Um pedido está On hold: leia a nota do pedido. O pagamento foi apenas autorizado (use Capture Razorpay payment), o valor ou a moeda não correspondiam ao pedido, o pagamento chegou para um pedido cancelado, ou não pôde ser verificado pela API da Razorpay naquele momento e aguarda o webhook.

O cliente vê um erro ao pagar: abra as notas do pedido ou veja WooCommerce > Status > Logs, origem wcp_razorpay_payment. Os erros são registrados mesmo com Enable Logging desativado. Chaves incorretas mostram a mensagem de que o método de pagamento não está disponível no momento. Outros motivos da Razorpay aparecem depois de Razorpay could not accept this payment:.

A janela pop-up não abre: o script do Razorpay Checkout foi bloqueado por um bloqueador de conteúdo ou pela conexão. O cliente vê uma mensagem e pode recarregar a página.

O reembolso falha: o reembolso usa as chaves do modo em que o pagamento foi feito. Verifique se as chaves desse modo estão preenchidas e leia o motivo na mensagem de erro.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na 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 da licença deste plugin são sempre removidos. As configurações do gateway e os logs (arquivos de log, inclusive os rotacionados, e entradas de log no banco de dados) só são removidos se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos e os dados deles na Razorpay nunca são excluídos. Os pedidos existentes mantêm as notas de pagamento e os IDs de transação.

A Razorpay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Razorpay.