VibeFox Razorpay for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

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

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 sua conta for ativada. Um webhook com um secret de sua escolha é fortemente recomendado (veja Configuração). Pagamentos em moedas diferentes de INR exigem que International Payments esteja ativado na sua conta Razorpay.

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

3. Digite 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. Digite seu Test Key ID e seu Test Key Secret, configure o webhook no Razorpay Dashboard e digite o secret dele (veja Configuração).

5. Ative Enable/Disable e clique em Save. Faça um pagamento de teste com Test mode ativado. Quando estiver pronto, digite as chaves Live e desative Test mode.

Na instalação, o módulo cria dois status de pedido, Razorpay payment authorized e Razorpay 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 Razorpay Payment > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra avisos: faltam as chaves do modo atual (nesse caso a Razorpay não aparece 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 webhook secret está vazio, ou a moeda padrão da loja não é INR e exige International Payments na sua conta Razorpay. Espaços colados junto com os Key IDs são removidos ao salvar.

Razorpay

Enable/Disable: Enable Razorpay Payment Gateway ativa ou desativa a forma de pagamento. Padrão: desativado.

Title: o nome da forma de pagamento que o cliente vê na finalização de compra. Também é o nome da forma de pagamento salvo no pedido. Padrão: UPI, Cards, NetBanking. Obrigatório: um título vazio gera o erro Enter a title for the payment method.

Description: o texto exibido abaixo da forma 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 suas chaves no Razorpay Dashboard, em Account & Settings > API Keys. Mude o Dashboard para o modo de teste para gerar as chaves de teste (rzp_test_...). As chaves Live (rzp_live_...) ficam disponíveis depois que sua conta for ativada.

Test mode: usa as chaves do modo de teste, então nenhum dinheiro real é cobrado. Padrão: ativado. Desative-o 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 Live. Ele começa com rzp_live_.

Live Key Secret: o Key Secret do Razorpay Dashboard no modo Live.

Os secrets salvos nunca são exibidos de novo. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.

Limpar secrets salvos: marque Test Key Secret, Live Key Secret ou Webhook Secret e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

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, vá em Account & Settings > Webhooks e adicione um webhook no modo de teste e outro no modo Live. Use a URL exibida em Webhook URL nesta seção. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_razorpay_payment/webhook, possivelmente com um código de idioma como /en/. Copie-a exatamente como as configurações mostram. Digite na Razorpay um secret de sua escolha e selecione estes eventos (eles também estão listados nesta seção):

Webhook Secret: o secret que você digitou ao criar o webhook. Use o mesmo secret para o webhook de teste e o webhook Live, porque o módulo 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 do pop-up, ou quando o cliente inicia o pagamento do mesmo carrinho novamente depois.

Avançado

Enable Logging: o log é gravado em logs/razorpay_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; esta opção acrescenta os detalhes de depuração. Chaves, assinaturas e dados de contato do cliente nunca são registrados. Padrão: desativado.

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 do módulo e o log. Pedidos, transações e reembolsos da Razorpay e os status de pedido do módulo sempre permanecem. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe a forma de pagamento (por padrão, UPI, Cards, NetBanking) e confirma. O módulo cria um pedido na Razorpay pelo valor exato do carrinho e na moeda do carrinho, e abre a página Razorpay payment da sua loja. A janela pop-up do Razorpay Checkout abre automaticamente nessa página, com o nome, o e-mail e o telefone do cliente já preenchidos. O pagamento aparece na Razorpay como Cart e com o número do carrinho. Nesse momento ainda não existe nenhum pedido no PrestaShop. Se a janela for fechada, o cliente pode clicar em Pay Now para abri-la de novo, ou em Choose another payment method para voltar à finalização de compra. O carrinho é mantido. No modo de teste, a página mostra Razorpay Test mode: no real money will be charged.

Depois de um pagamento bem-sucedido, o cliente vê Please wait while we process your payment... O módulo verifica a assinatura da Razorpay, busca o pagamento pela API da Razorpay e compara o valor e a moeda com o carrinho. O pedido só é marcado como pago depois que a Razorpay confirma. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Se a assinatura for válida, mas o pagamento não puder ser buscado naquele momento, o pedido é criado em Razorpay payment on hold e o webhook o confirma depois.

Se o cliente iniciar o pagamento de novo para o mesmo carrinho, o módulo reutiliza o pedido da Razorpay quando o valor, a moeda e o modo não mudaram. Se esse pedido da Razorpay já tiver sido pago, por exemplo porque o cliente fechou o navegador e não há webhook, o módulo cria o pedido a partir desse pagamento em vez de pedir um segundo. Se o total do carrinho tiver mudado, um novo pedido da Razorpay é criado.

Mensagens que o cliente pode ver:

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 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 financeira.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente não pagou, ou a Razorpay ainda não confirmou o pagamento. Existe apenas o carrinho. Uma tentativa de pagamento que falha não cria um pedido; o cliente pode pagar de novo.

Payment accepted: o pagamento foi capturado e confirmado. O pagamento é registrado com o ID de pagamento da Razorpay (pay_...) como ID da transação, e uma nota mostra o ID do pagamento, o valor e como ele foi confirmado (callback, webhook, sync ou admin).

Razorpay payment authorized: o pagamento foi apenas autorizado (Authorize Only). Capture-o para concluir o pedido.

Razorpay payment on hold: é definido nestes casos, cada um com uma nota: o valor ou a moeda pagos não coincidiram com o carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), o pagamento foi capturado para um pedido cancelado, ou o pagamento não pôde ser verificado pela API da Razorpay naquele momento. Um valor pago na moeda do pedido fica registrado no pedido. Verifique o pedido e atenda-o ou reembolse o pagamento.

Cancelled: um pagamento que chega depois para um pedido cancelado não reabre o pedido automaticamente: um pagamento autorizado não é capturado e recebe apenas uma nota, e um pagamento capturado coloca o pedido em Razorpay payment on hold. Uma notificação repetida do pagamento que já pagou o pedido não altera nada, mesmo que você tenha cancelado o pedido depois.

Refunded: o pagamento foi totalmente reembolsado.

Se chegar um pagamento adicional para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você o reembolse no Razorpay Dashboard, caso não tenha sido intencional. Um payment.failed tardio para um pedido pago apenas acrescenta uma nota.

Bloco de pagamento da Razorpay

A página do pedido mostra um bloco Razorpay payment com o ID do pagamento na Razorpay, o pedido da Razorpay, o status do pagamento, Paid / refunded (o valor cobrado pela Razorpay e o valor reembolsado), um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Razorpay notes do pedido. Captura e reembolsos exigem a permissão para editar pedidos; o acesso à configuração do módulo não é necessário.

Captura (Authorize Only)

Abra o pedido no status Razorpay payment authorized, clique em Capture Razorpay payment no bloco da Razorpay e confirme. O pagamento é capturado no modo em que foi autorizado, e o pedido passa para Payment accepted. Se a Razorpay recusar, o bloco e as notas mostram Razorpay capture failed: com o motivo. Uma captura feita no Razorpay Dashboard conclui o pedido pelo webhook.

Reembolsos

No bloco da Razorpay, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Razorpay. Confirme a pergunta Refund this amount through Razorpay? This cannot be undone. Reembolsos totais e parciais são aceitos. Os reembolsos são feitos no valor e na moeda que a Razorpay cobrou, então, depois de uma divergência de valor, você pode reembolsar até o que o cliente efetivamente pagou, e não até o total do pedido. Um valor maior mostra Invalid refund amount: at most seguido do valor. O reembolso é enviado com as chaves do modo em que o pagamento foi feito. Se a Razorpay não aceitar o reembolso, o bloco mostra Razorpay refund failed: com o motivo, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso na Razorpay, o valor e o status. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que o pagamento é capturado.

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 Razorpay.

Reembolsos feitos no Razorpay Dashboard chegam pelo webhook e são registrados uma única vez no histórico de reembolsos e nas notas. Quando o pedido é totalmente reembolsado, seu status passa para Refunded. Um reembolso do 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 módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Razorpay Payment é o primeiro bloco da página Modules > Module Manager > VibeFox Razorpay Payment > Configure, acima das configurações. Digite 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 digitar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-razorpay 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 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 for alterado, 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 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 dela. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a Razorpay 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 vitrine do PrestaShop não sabe que você está logado no back office, então a forma de pagamento fica oculta para você também: você pode configurar o módulo antes de comprar uma chave, mas não pode 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 capturas e reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 digitada, 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 Razorpay 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 duas chaves: Test Key ID e Test Key Secret no modo de teste, Live Key ID e Live Key Secret no modo Live. A página de configurações mostra um aviso quando elas faltam. 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. No Razorpay Dashboard, verifique se o webhook existe no modo que você usa (Test ou Live), se a URL é exatamente a exibida em Webhook URL e se os cinco eventos estão selecionados. Verifique se Webhook Secret é o mesmo secret da Razorpay. O pedido também é criado quando o cliente volta do pop-up ou inicia o pagamento do mesmo carrinho novamente.

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

O webhook responde Invalid signature ou Missing signature: o secret nas configurações é diferente do secret do webhook da Razorpay. Digite o mesmo secret nos dois lugares, para o webhook de teste e o webhook Live.

O webhook responde Retry later: o módulo não conseguiu confirmar uma captura pela API da Razorpay, o pedido não pôde ser criado (por exemplo, o módulo está desativado), ou o carrinho estava sendo atualizado por outra requisição no mesmo momento. A Razorpay reenvia o evento automaticamente. O motivo está no Log.

A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da Razorpay.

Um pedido está em Razorpay payment on hold: leia as notas no bloco da Razorpay. O valor ou a moeda não coincidiram com o carrinho, o pagamento chegou para um pedido cancelado, ou ele não pôde ser verificado pela API da Razorpay naquele momento e aguarda o webhook.

O cliente vê um erro ao pagar: veja o campo Log na página do módulo. Os erros são registrados mesmo com Enable Logging desativado. Chaves erradas mostram a mensagem de que a forma de pagamento não está disponível no momento. Outros motivos da Razorpay são exibidos após Razorpay could not accept this payment:.

O 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.

A captura ou o reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo Test ou no modo Live, e as chaves desse modo não estão preenchidas. Digite-as e tente novamente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Razorpay 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 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 da Razorpay e os status de pedido Razorpay payment authorized e Razorpay payment on hold sempre são mantidos, para que pedidos pagos antes ainda possam ser capturados e reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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