VibeFox CCAvenue for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado com 3.0.5.0) ou 4.0.2 e posteriores (testado com 4.1.0.3).

PHP: 8.0 ou posterior, com a extensão OpenSSL (usada para criptografar a requisição e descriptografar a resposta).

Conta CCAvenue: você precisa de uma conta de comerciante CCAvenue com um Merchant ID, um Access Code e uma 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 para o ambiente de teste; o acesso de teste precisa ser habilitado para a sua conta pela CCAvenue. A extensão usa os endpoints da CCAvenue India.

Moeda: a moeda do pedido é enviada à CCAvenue como está. As contas da CCAvenue aceitam INR por padrão; outras moedas exigem o processamento multimoeda na sua conta CCAvenue.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote para OpenCart 3 wcp_ccavenue_payment-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_ccavenue_payment.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_ccavenue_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox CCAvenue Payment e clique em Install (o botão verde +). O seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão de lápis) para abrir a página de configurações. Cole a sua chave de licença VibeFox em License key, no bloco de licença no topo da página, 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, ative Enable/Disable e clique em Save.

5. Mantenha o Test mode ativado durante os testes e depois desative-o para aceitar pagamentos reais. Não é preciso configurar nada no painel da CCAvenue: o endereço de retorno é enviado com cada pagamento.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_ccavenue_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox CCAvenue Payment, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as credenciais da CCAvenue como nas etapas 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de retorno é diferente (veja URL de retorno).

Uma nova instalação começa com o método de pagamento desativado e o modo de teste ativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox CCAvenue Payment > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando a CCAvenue está ativada mas faltam o Merchant ID, o Access Code ou a Working Key (o método de pagamento fica então oculto no checkout 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 método de pagamento estiver ativado em modo de teste, e lembra do processamento multimoeda quando a moeda padrão da loja não é INR. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode ficar vazio (no máximo 128 caracteres), Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0, e a zona geográfica e os status do pedido devem existir; caso contrário, nada é salvo.

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ê no checkout. Também é o nome do método de pagamento armazenado no pedido. Padrão: CCAvenue. Obrigatório.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

Sort Order: a posição da CCAvenue entre os métodos de pagamento no checkout. Deixe vazio ou informe um número inteiro.

Geo Zone: oferecer a CCAvenue somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total do carrinho, na moeda padrão da loja, que um pedido precisa atingir para que a CCAvenue seja oferecida. Deixe vazio para oferecer a CCAvenue para qualquer total.

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. Os espaços nas credenciais são removidos ao salvar.

Merchant ID: o seu Merchant ID numérico da CCAvenue. Se ele contiver algo diferente de dígitos, a mensagem CCAvenue: the Merchant ID must contain digits only — the previous value was kept. aparece ao salvar, o valor salvo anteriormente permanece 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, por isso mantenha-a em sigilo. 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. Para removê-la, marque Clear saved Working Key abaixo do campo e clique em Save.

Test mode: envia os clientes para o 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 etapa Confirm Order mostra TEST MODE: no real transactions will be processed. Padrão: ativado. Desative para pagamentos reais.

URL de retorno

A CCAvenue devolve o cliente ao endereço mostrado nesta seção. No OpenCart 3 ele tem a forma https://your-store/index.php?route=extension/payment/wcp_ccavenue_payment/back; no OpenCart 4, https://your-store/index.php?route=extension/wcp_ccavenue_payment/payment/wcp_ccavenue_payment.back. Ele é montado a partir do endereço da vitrine da sua instalação do OpenCart. A extensão envia essa URL com cada pagamento (como URL de redirecionamento e de cancelamento), portanto não há nada para configurar na CCAvenue. Ela deve pertencer ao domínio registrado na CCAvenue.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido recebe um status somente depois que a resposta criptografada da CCAvenue é verificada. Um pagamento falho ou cancelado deixa o pedido sem status, e o cliente volta ao checkout com o carrinho mantido. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: um pagamento bem-sucedido (status Success da CCAvenue, valor e moeda verificados). Padrão: Processando.

Awaiting Payment Status: Awaited: o banco ainda não confirmou o pagamento. O pedido recebe Order Status After Payment quando a CCAvenue informa Success para o mesmo tracking ID. Padrão: Pendente de pagamento.

On Hold (Review) Status: a CCAvenue informou um valor ou uma moeda diferentes do total do pedido, ou chegou um pagamento para um pedido cancelado. Uma nota explica isso. Padrão: Pendente de pagamento, porque o OpenCart não tem o status Em espera. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled Payment Status: um pagamento aguardado foi depois abortado (Aborted para o mesmo tracking ID). Padrão: Cancelado.

Failed Payment Status: um pagamento aguardado depois falhou (Failure, Invalid ou Timeout para o mesmo tracking ID). Uma falha de uma tentativa anterior não altera o pedido. Padrão: Falhou.

Avançado

Debug log: grava os eventos da CCAvenue em ccavenue_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. São registrados apenas as referências de pedido, os tracking IDs e os status; chaves, dados de cartão, e-mails e endereços não são registrados. Padrão: desativado. Enquanto estiver desativado, nada é gravado, nem mesmo erros.

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

Delete data on uninstall: quando ativado, desinstalar a extensão remove as configurações da extensão e o registro. Os pedidos e as referências de pagamento da CCAvenue permanecem, então um retorno tardio de um pagamento antigo continua sendo tratado após uma reinstalação. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. A Working Key não é exportada.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. A Working Key salva é mantida.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, CCAvenue). Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a etapa mostra Thank you for your order. You are being redirected to CCAvenue to complete the payment. e envia o cliente para a página de pagamento da CCAvenue. Um botão Pay via CCAvenue é exibido enquanto o navegador vai para lá. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra.

Cada tentativa recebe uma nova referência de pedido da CCAvenue, formada pelo número do pedido do OpenCart e pelo horário. O total e a moeda do pedido, os dados de cobrança, o endereço de entrega (quando o pedido é enviado e o endereço de entrega é diferente do de cobrança) e um token secreto da tentativa são enviados na requisição criptografada. Nomes e endereços são limpos para os caracteres e tamanhos que a CCAvenue aceita; país e estado são enviados como nomes e o telefone como dígitos. O cliente escolhe cartão, Net Banking, UPI, carteira ou EMI na página da CCAvenue. O OpenCart 4 não pede um endereço de pagamento por padrão; nesse caso, os dados de cobrança são tirados do endereço de entrega.

Depois do pagamento, a CCAvenue devolve o cliente com uma resposta criptografada. O pedido só é marcado como pago depois que a CCAvenue confirma: a resposta precisa ser descriptografada com a sua Working Key, pertencer a uma tentativa desta loja e ter o mesmo valor e a mesma moeda enviados e do total do pedido. Em seguida, o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart 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, ela mostra Your payment was received and is being reviewed by the store. No OpenCart 4, o navegador não envia a sessão da loja quando a CCAvenue devolve o cliente; por isso, depois de aplicar a resposta, a extensão mostra uma página curta que reabre o endereço de retorno da sua loja: o cliente mantém o carrinho e o login.

Se o pagamento falhar, o cliente volta ao checkout 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. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. Nesses casos, o pedido permanece sem status e o carrinho é mantido, para que o cliente possa pagar novamente. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza. Cada tentativa recebe a sua própria referência de pedido da CCAvenue. A CCAvenue não pode cancelar um pagamento já iniciado, então um pagamento bem-sucedido e tardio de uma tentativa anterior ainda é aplicado ao próprio pedido. Um carrinho é pago uma única vez: um carrinho já pago por outro pedido não é enviado novamente à CCAvenue (o cliente vai para a página de sucesso), e se o mesmo carrinho ainda assim for pago duas vezes (por exemplo, em duas abas do navegador), o segundo pedido fica sem status e o pedido pago recebe uma nota informando que o cliente pode ter sido cobrado duas vezes, para que você possa estorná-lo no painel da CCAvenue.

O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado nesse meio tempo, Confirm Order envia o cliente de volta à finalização de compra, e o próximo Confirm Order paga um novo pedido do carrinho. A mensagem é Payment was cancelled. You may try again. quando um pagamento aguardado foi abortado, Payment was not completed. Please try again or choose a different payment method. quando ele falhou, e This order can no longer be paid (it was closed by the store). Please confirm your order again. quando você fechou um pedido que tinha um pagamento. Se o pedido já tiver um status e o carrinho tiver mudado desde então (outros produtos ou quantidades), a mensagem é Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order.

O resultado é obtido somente pelo retorno do cliente da CCAvenue: não há notificações servidor a servidor nem consultas de status. Se o cliente fechar o navegador antes de voltar, o pedido permanece sem status; verifique o pagamento no painel da CCAvenue. A extensão não oferece reembolsos a partir do OpenCart, cartões salvos, assinaturas ou pagamentos recorrentes, formulário de cartão no site, nem suporte à CCAvenue UAE ou outras plataformas regionais.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado à CCAvenue e não voltou, ou o pagamento falhou ou foi cancelado. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders. Verifique o pagamento no painel da CCAvenue se o cliente não voltar.

Order Status After Payment (default Processing): o pagamento foi confirmado. Uma nota mostra a referência bancária, o tracking ID e o modo de pagamento.

Awaiting Payment Status (default Pending): 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, e uma nota pede que você verifique o pagamento no painel da CCAvenue antes de concluir o pedido. Uma resposta posterior com o mesmo tracking ID ainda é aplicada: Success define Order Status After Payment, Failure define Failed Payment Status e Aborted define Cancelled Payment Status. O OpenCart notifica o cliente sobre essas mudanças.

On Hold (Review) Status (default Pending): a CCAvenue confirmou um pagamento cujo valor ou moeda difere do total do pedido ou do que foi enviado, ou o cliente pagou depois que o pedido foi cancelado ou falhou. A nota mostra o valor recebido e o esperado. Verifique o pagamento no painel da CCAvenue e, em seguida, conclua o pedido ou estorne o pagamento.

Uma falha tardia nunca altera um pedido pago, e um pedido que você concluiu manualmente não é alterado. Se chegar outro pagamento bem-sucedido para um pedido já pago (por exemplo, de duas abas do navegador), o pedido não é alterado. Uma nota pede que você estorne a duplicata no painel da CCAvenue.

As notas são registros do History do pedido que o cliente não vê.

VibeFox CCAvenue Payment tab

Em Sales > Orders, abra um pedido pago com a CCAvenue. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox CCAvenue Payment mostra o CCAvenue order ID com a etiqueta Test mode para pagamentos de teste, o Tracking ID, o Status, a Bank reference, o Payment mode e o nome do cartão, o Amount sent e o Amount received, a Date, a Message da CCAvenue e as CCAvenue notes do pedido. A aba é mostrada aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos a partir do OpenCart não são suportados. Estorne o pagamento no painel da CCAvenue e, em seguida, registre o reembolso no OpenCart manualmente, por exemplo alterando o status do pedido.

Chave de licença

A extensão 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 Extensions > Extensions > Payments > VibeFox CCAvenue Payment > Edit, acima das configurações. Cole 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 ficam a linha Product: opencart-payment-ccavenue e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 de mudar o endereço da loja, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a CCAvenue não é mostrada aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa visualização não está disponível: a loja não enxerga o login do administrador, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados quando o cliente volta da CCAvenue.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, e depois uma vez por semana. Não é necessário um cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

CCAvenue does not appear at checkout: 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. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

The payment went through, but the order stays without a status: o cliente não voltou da CCAvenue para a sua loja, por exemplo porque fechou o navegador. A extensão não tem notificações servidor a servidor. Verifique o pagamento no painel da CCAvenue e atualize o pedido manualmente.

Every payment ends with 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 o Debug log e veja o campo Log na página da extensão.

CCAvenue shows an error before the payment page: 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 se, no modo de teste, a CCAvenue habilitou o acesso de teste para a sua conta. Para uma moeda diferente de INR, o processamento multimoeda precisa estar habilitado na sua conta CCAvenue.

The customer sees This payment method is temporarily unavailable: falta uma das credenciais, ou o total do pedido é zero. O Debug log mostra o motivo.

The customer sees This payment method is not available. Please reload the checkout page.: a sessão do checkout não corresponde mais ao pedido, ou o método de pagamento foi desativado nesse meio tempo. O cliente recarrega o checkout.

The customer sees Payment gateway error: encryption failed: a requisição não pôde ser criptografada. Verifique se a extensão OpenSSL do PHP está instalada.

The Merchant ID does not change on save: o valor contém algo diferente de dígitos. Digite somente os números do seu Merchant ID.

Order is in the review or awaiting status: leia as notas na aba VibeFox CCAvenue Payment (veja Status do pedido). Verifique o pagamento no painel da CCAvenue e, em seguida, conclua o pedido ou estorne o pagamento.

Para desenvolvedores: antes de a requisição ser criptografada, a extensão dispara o evento do OpenCart ccavenue_p_request_params com os parâmetros da requisição e o pedido (por exemplo, para definir merchant_param2 até merchant_param5; não altere amount, currency, order_id nem merchant_param1).

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox CCAvenue Payment. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixa passar o retorno do cliente no modo de manutenção). Se Delete data on uninstall estiver ativado, as demais configurações da extensão (título, descrição, credenciais, modo de teste, registro) e o registro são removidos. Se estiver desativado, são mantidos para uma reinstalação posterior. As referências de pagamento da CCAvenue são sempre mantidas. Os pedidos existentes mantêm as suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox CCAvenue Payment na lista de extensões instaladas; em seguida, clique em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

CCAvenue é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela CCAvenue.