VibeFox CCAvenue for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior, com a extensão OpenSSL (usada para criptografar a requisição e descriptografar a resposta). O módulo não é instalado em versões anteriores do PHP nem sem o OpenSSL.
Conta CCAvenue: você precisa de uma conta de comerciante na CCAvenue com Merchant ID, Access Code e Working Key. O Access Code e a Working Key são emitidos para um domínio de site, então gere-os para o domínio desta loja. A CCAvenue usa as mesmas credenciais no ambiente de teste; o acesso de teste precisa ser habilitado para a sua conta pela CCAvenue. O módulo usa os endpoints da CCAvenue Índia.
Moeda: a moeda do carrinho é enviada à CCAvenue como está. As contas da CCAvenue aceitam INR por padrão; outras moedas exigem processamento multimoeda na sua conta da CCAvenue.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, acesse 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 CCAvenue Payment 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 Merchant ID, o Access Code e a Working Key do seu painel da CCAvenue e ative Enable/Disable.
5. Mantenha Test mode ativado durante os testes e depois desative-o para aceitar pagamentos reais.
Na instalação, o módulo cria dois status de pedido, Awaiting CCAvenue payment e CCAvenue payment on hold. O PrestaShop ativa o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-lo em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox CCAvenue Payment > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a CCAvenue está ativada, mas o Merchant ID, o Access Code ou a Working Key está faltando (nesse caso, o método de pagamento fica oculto na finalização de compra até que os três estejam preenchidos), mostra CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken. enquanto o modo de teste estiver ativo, e lembra do processamento multimoeda quando a moeda padrão da loja não é INR.
CCAvenue
Enable/Disable: Enable CCAvenue 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. Também é o nome do método de pagamento salvo no pedido. Padrão: CCAvenue.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.
Credenciais de API
Faça login no seu painel de comerciante da CCAvenue (M.A.R.S.) e abra Settings > API Keys. Gere o Access Code e a Working Key para o domínio desta loja. Espaços nas credenciais são removidos ao salvar.
Merchant ID: o seu Merchant ID numérico da CCAvenue. Se ele contiver algo além de dígitos, ao salvar aparece a mensagem CCAvenue: the Merchant ID must contain digits only — the previous value was kept., o valor salvo anteriormente é mantido e as demais configurações são salvas.
Access Code: o Access Code deste site (Settings > API Keys).
Working Key: a Working Key (chave de criptografia) deste site. Ela criptografa a requisição de pagamento e é a única forma de verificar a resposta da CCAvenue, então mantenha-a em segredo. Uma Working Key salva nunca é exibida novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la.
Clear saved Working Key: marque a caixa e clique em Save para remover a Working Key salva. Um campo vazio mantém o valor salvo.
Test mode: envia os clientes ao ambiente de teste da CCAvenue (test.ccavenue.com). A CCAvenue usa o mesmo Merchant ID, Access Code e Working Key para teste e produção; o acesso de teste precisa ser habilitado para a sua conta pela CCAvenue. No modo de teste, a finalização de compra mostra TEST MODE: no real transactions will be processed. abaixo do método de pagamento. Padrão: ativado. Desative para pagamentos reais.
URL de retorno
A CCAvenue devolve o cliente ao endereço exibido nesta seção. Com URLs amigáveis, ele tem a forma https://your-shop/module/wcp_ccavenue_payment/return, possivelmente com um código de idioma como /en/. O módulo envia esta URL em cada pagamento (como URL de redirecionamento e de cancelamento), então não há nada a configurar na CCAvenue. Ela precisa pertencer ao domínio registrado na CCAvenue.
Avançado
Debug log: grava os eventos da CCAvenue em logs/ccavenue_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Apenas referências de pedido, IDs de rastreamento e status são registrados; chaves, dados de cartão, e-mails e endereços não são registrados. Padrão: desativado. Enquanto estiver desativado, nada é gravado, inclusive erros.
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, o log e as referências de pedido da CCAvenue. Os pedidos e os status de pedido do módulo são mantidos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, CCAvenue) e confirma. Uma página exibe Thank you for your order. You are being redirected to CCAvenue to complete the payment. e envia o cliente à página de pagamento da CCAvenue. Sem JavaScript, o cliente clica em Pay via CCAvenue ou em Back to checkout. Nesse momento ainda não existe nenhum pedido.
Cada tentativa recebe uma nova referência de pedido da CCAvenue, formada pelo número do carrinho e pela hora. O total e a moeda do carrinho, os dados de cobrança, o endereço de entrega (quando diferente do endereço de cobrança) e um token secreto da tentativa são enviados na requisição criptografada. Nomes e endereços são ajustados para os caracteres e tamanhos que a CCAvenue aceita; país e estado são enviados como nomes e o telefone apenas como dígitos. O cliente escolhe o cartão, o Net Banking, o UPI, a carteira ou o EMI na página da CCAvenue.
Após o pagamento, a CCAvenue devolve o cliente com uma resposta criptografada. O pedido só é marcado como pago depois que a CCAvenue confirma: a resposta precisa descriptografar com a sua Working Key, pertencer a uma tentativa desta loja e ter o mesmo valor e a mesma moeda que foram enviados e que o total do carrinho. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your CCAvenue payment has been received. Para um pagamento Awaited, a página mostra Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. Após uma divergência de valor ou moeda, mostra Your payment was received and is being reviewed by the shop. Se um pedido em espera for depois cancelado ou falhar sem pagamento, a página de confirmação mostra Your CCAvenue payment was not completed. Please contact us about this order.
Se o pagamento falhar, o cliente volta à finalização de compra com Payment was not completed. Please try again or choose a different payment method. Se o cliente cancelar na página da CCAvenue, a mensagem é Payment was cancelled. You may try again. Se a resposta não puder ser verificada, a mensagem é We could not confirm the payment result. If your account was charged, please contact us before paying again. Nesses casos, nenhum pedido é criado e o carrinho é mantido, para que o cliente possa pagar novamente. Se o carrinho já tiver um pedido, uma nova tentativa vai direto para a página de confirmação desse pedido, em vez de um segundo pagamento.
O resultado é obtido somente do retorno do cliente vindo da CCAvenue: não há notificações de servidor para servidor nem consultas de status. Se o cliente fechar o navegador antes de voltar, nenhum pedido é criado; verifique o pagamento no painel da CCAvenue. O módulo não oferece reembolsos pelo PrestaShop, cartões salvos, assinaturas ou pagamentos recorrentes, nem formulário de cartão no site, e não oferece suporte à CCAvenue UAE nem a outras plataformas regionais.
Pedidos
Status do pedido
No order yet: o cliente foi enviado à CCAvenue e não voltou, ou o pagamento falhou ou foi cancelado. Só existe o carrinho. Verifique o pagamento no painel da CCAvenue se o cliente não voltar.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o ID de rastreamento da CCAvenue como ID da transação, e uma nota mostra a referência bancária, o ID de rastreamento e o modo de pagamento.
Awaiting CCAvenue payment: a CCAvenue informou o pagamento como Awaited (o banco ainda não o confirmou). O pedido nunca é marcado como falho enquanto o dinheiro ainda puder ser capturado. Verifique-o no painel da CCAvenue antes de processar o pedido. Uma resposta posterior com o mesmo ID de rastreamento ainda é aplicada: Success define Payment accepted, Failure define Payment error e Aborted define Canceled.
CCAvenue payment on hold: a CCAvenue confirmou um pagamento cujo valor ou moeda difere do carrinho ou do que foi enviado (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou), ou o cliente pagou depois que o pedido já tinha sido cancelado. A nota mostra o valor recebido e o esperado. O valor informado pela CCAvenue é registrado como pagamento do pedido quando a moeda coincide. Verifique o pagamento no painel da CCAvenue e depois processe o pedido ou reembolse o pagamento.
Uma falha tardia nunca altera um pedido pago. Se chegar outro pagamento bem-sucedido para um pedido que já está pago (por exemplo, de duas abas do navegador), o pedido não é alterado. Uma nota pede que você reembolse a duplicata no painel da CCAvenue.
Bloco de pagamento da CCAvenue
A página do pedido mostra um bloco CCAvenue payment com o ID do pedido na CCAvenue, o ID de rastreamento, o status, a referência bancária, o modo de pagamento e o nome do cartão, o valor enviado e o valor recebido, a data e a mensagem da CCAvenue, além de um selo Test mode para pagamentos de teste. As notas da CCAvenue são mensagens privadas do pedido, visíveis apenas no back office.
Reembolsos
Reembolsos pelo PrestaShop não são suportados. Reembolse o pagamento no painel da CCAvenue e depois registre o reembolso manualmente no PrestaShop.
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 CCAvenue Payment é o primeiro bloco em Modules > Module Manager > VibeFox CCAvenue Payment > Configure, acima das configurações. Informe 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-ccavenue e o link Manage licenses and domains in your account, que abre a sua conta em 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 com 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, inclusive em uma configuração multiloja. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a CCAvenue não é exibida 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. 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 de compra. Um aviso aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados quando o cliente volta da CCAvenue.
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 informada e, depois, uma vez por semana. Não é preciso nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A CCAvenue não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se as três credenciais estão preenchidas: Merchant ID, Access Code e Working Key. A página de configurações mostra um aviso quando alguma está faltando. 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 cliente não voltou da CCAvenue para a sua loja, por exemplo porque fechou o navegador. O módulo não tem notificações de servidor para servidor. Verifique o pagamento no painel da CCAvenue e crie ou atualize o pedido manualmente.
Todos os pagamentos terminam com We could not confirm the payment result: a resposta não pode ser descriptografada. A Working Key está errada, pertence a outro domínio ou foi copiada com caracteres extras. Gere as chaves para o domínio desta loja e cole-as novamente. Ative Debug log e veja o campo Log na página do módulo.
A CCAvenue mostra um erro antes da página de pagamento: verifique se o Access Code e a Working Key foram gerados para este domínio, se a URL de retorno pertence ao domínio registrado na CCAvenue e, no modo de teste, se a CCAvenue habilitou o acesso de teste para a sua conta. Para uma moeda diferente de INR, o processamento multimoeda precisa estar ativado na sua conta da CCAvenue.
O cliente vê This payment method is temporarily unavailable: uma das credenciais está faltando, ou o total do carrinho é zero. Debug log mostra o motivo.
O cliente vê This payment method is not available: o módulo está desativado ou não é permitido para a moeda do carrinho, o país ou o grupo de clientes em Payment > Preferences.
O cliente vê Payment gateway error: encryption failed: a requisição não pôde ser criptografada. Verifique se a extensão OpenSSL do PHP está instalada.
O Merchant ID não muda ao salvar: o valor contém algo além de dígitos. Informe apenas os números do seu Merchant ID.
O pedido está como CCAvenue payment on hold ou Awaiting CCAvenue payment: leia a nota do pedido (veja Status do pedido). Verifique o pagamento no painel da CCAvenue e depois processe o pedido ou reembolse o pagamento.
Para desenvolvedores, o módulo oferece o hook actionCcavenueRequestParams (altera os dados enviados à CCAvenue antes da criptografia, por exemplo de merchant_param2 a merchant_param5; os valores não podem conter &; não altere amount, currency, order_id nem merchant_param1).
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox CCAvenue Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. A confirmação lembra que as configurações e as referências da CCAvenue são mantidas, a menos que Delete data on uninstall esteja ativado. Se estiver ativado, são removidas as configurações do módulo, o log e as referências de pedido da CCAvenue. Se estiver desativado, tudo é mantido para uma reinstalação posterior. Os status de pedido Awaiting CCAvenue payment e CCAvenue payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
CCAvenue é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela CCAvenue.