VibeFox CorvusPay for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado com a versão 3.0.5.0) ou 4.0.2 e superior (testado com a versão 4.1.0.3).
PHP: 8.0 ou superior.
Moeda: AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK ou USD. Em qualquer outra moeda da finalização de compra, o método de pagamento fica oculto na finalização. Os valores são enviados com 2 casas decimais; um total com mais casas decimais (por exemplo, em uma moeda com 3 casas, como BHD) é recusado em vez de arredondado.
Conta CorvusPay: você precisa de uma conta de comerciante na CorvusPay. A CorvusPay emite um Store ID e uma Secret Key para cada loja, separadamente para a loja de teste e para a de produção; eles são exibidos no CorvusPay Merchant Center. A Success URL e a Cancel URL da extensão devem ser informadas lá (veja Configuration).
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_corvuspay_gateway-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_corvuspay_gateway.ocmod.zip. Instale apenas 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, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_corvuspay_gateway-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ê também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox CorvusPay Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para 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 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 Store ID e a Secret Key da sua loja de teste na CorvusPay (e da loja de produção, para pagamentos reais). Copie a Success URL e a Cancel URL exibidas na página de configurações para o CorvusPay Merchant Center, tanto para a loja de teste quanto para a de produção.
5. Ative Enable/Disable e clique em Save. Faça um pedido de teste e depois desative Test Mode para entrar em produção.
OpenCart 4
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_corvuspay_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox CorvusPay Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).
4. Informe a chave de licença, os dados das lojas da CorvusPay e as URLs do Merchant Center como nos passos 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a Success URL e a Cancel URL são diferentes (veja URLs de sucesso e de cancelamento).
Uma nova instalação começa com o método de pagamento desativado e o modo de teste ativado.
Configuration
Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > 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 mostra Test mode is on. Payments go to the CorvusPay test environment — no real money is taken. enquanto o modo de teste estiver ativado, avisa quando o gateway está ativado mas o Store ID ou a Secret Key do modo atual estão vazios (nesse caso, o método fica oculto na finalização de compra até que sejam preenchidos) e quando a moeda padrão da sua loja não é suportada pela CorvusPay. Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.
Ao salvar, Title não pode ter mais de 128 caracteres, Sort Order precisa ser um número inteiro, Minimum Total precisa ser um número não negativo, e a zona geográfica e os status de pedido selecionados precisam existir; caso contrário, nada é salvo e a página lista os erros.
CorvusPay
Enable/Disable: Enable CorvusPay Gateway. ativa ou desativa o método de pagamento. Default: off.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Default: Credit/Debit Card (CorvusPay). Até 128 caracteres; se deixar em branco, o nome padrão é exibido.
Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Default: Pay securely with your credit or debit card via CorvusPay. No modo de teste, é acrescentado (Test mode — no real payment is taken.)
Sort Order: a posição da CorvusPay entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.
Geo Zone: ofereça a CorvusPay somente para endereços de pagamento na zona geográfica selecionada. Default: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.
Minimum Total: o total do pedido, na moeda padrão da loja, que um pedido precisa atingir antes que a CorvusPay seja oferecida. Deixe em branco se não houver mínimo.
Credenciais da loja
O Store ID e a Secret Key são emitidos pela CorvusPay para cada loja (teste e produção separadamente) e são exibidos no CorvusPay Merchant Center.
Test Mode: usa o ambiente de teste da CorvusPay (wallet.test.corvuspay.com) e o Store ID e a Secret Key de teste. Default: on. Desative para receber pagamentos reais em wallet.corvuspay.com.
Test Store ID: o Store ID numérico da sua loja de teste na CorvusPay.
Test Secret Key: a Secret Key da sua loja de teste na CorvusPay, usada nas assinaturas HMAC-SHA256.
Live Store ID: o Store ID numérico da sua loja de produção na CorvusPay.
Live Secret Key: a Secret Key da sua loja de produção na CorvusPay, usada nas assinaturas HMAC-SHA256.
O Store ID deve conter apenas dígitos. Se você digitar qualquer outra coisa, a página mostra … must contain digits only — the previous value was kept. e os demais campos são salvos mesmo assim. As Secret Keys salvas nunca são exibidas novamente: o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo. Para remover uma chave salva, marque Clear the saved value on save abaixo do campo e clique em Save. Um pagamento é sempre verificado com a Secret Key da loja em que foi iniciado; por isso, mantenha a chave de teste preenchida enquanto ainda puderem chegar pagamentos de teste.
URLs de sucesso e de cancelamento
Copie os dois endereços exibidos em Merchant Center URLs para o CorvusPay Merchant Center, tanto para a loja de teste quanto para a de produção. A CorvusPay devolve o cliente a esses endereços após o pagamento. Eles são montados a partir do endereço da vitrine da sua instalação do OpenCart; copie-os exatamente como a página os mostra.
Pagamento
Transaction Type: como o cartão é cobrado.
Payment Page Language: o idioma da página de pagamento da CorvusPay. Site language (padrão) usa o idioma atual da sua loja quando a CorvusPay o suporta; caso contrário, usa o inglês. Você também pode escolher Hrvatski, English, Deutsch, Italiano, Srpski ou Slovenščina.
Order Status After Payment: o status do pedido após um pagamento Sale bem-sucedido. As opções apontam para os status do OpenCart escolhidos na seção Order statuses.
Status de pedido
O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Estes são os status do OpenCart que o gateway define; cada campo lista os seus status de pedido do OpenCart. O OpenCart não tem o status On hold, por isso o status de revisão é usado para Authorize only, para divergências de valor ou de moeda e para pagamentos feitos após um cancelamento; uma nota no pedido explica o motivo.
Processing status: usado quando Order Status After Payment é Processing. Default: Processing.
Completed status: usado quando Order Status After Payment é Completed. Default: Complete.
On hold (review) status: Authorize only, divergência de valor ou de moeda, pagamento após um cancelamento, ou Order Status After Payment definido como On hold. Default: Pending. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.
Avançado
Logging: grava informações de depuração em corvuspay_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros são sempre registrados, mesmo quando esta opção está desativada; segredos, assinaturas e dados de clientes nunca são registrados. Default: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete Data: quando ativada, desinstalar a extensão remove as configurações do gateway e os arquivos de log. Os pedidos e os dados de transação da CorvusPay são sempre mantidos. Default: off.
Importar / Exportar
Export: Download JSON salva as configurações em um arquivo JSON. As Secret Keys não são exportadas.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As Secret Keys salvas são mantidas.
Finalização de compra
Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Credit/Debit Card (CorvusPay)). 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 página mostra Redirecting to CorvusPay for payment. Please wait... e envia o formulário assinado para a página de pagamento da CorvusPay. Se o redirecionamento não começar, o cliente clica em Pay via CorvusPay. São enviados o total do pedido na moeda do pedido, uma breve descrição (Order, o número do pedido e o nome da loja) e os dados de endereço e o e-mail do cliente (para preencher previamente a página de pagamento). O mesmo número de pedido da CorvusPay é reutilizado enquanto o valor, a moeda, o modo e o tipo de transação não mudarem, e a CorvusPay não aceita um segundo pagamento para ele. 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. Se a loja não pedir um endereço de pagamento (padrão do OpenCart 4), os dados do titular do cartão são obtidos do nome do cliente e do endereço de entrega.
Depois de pagar, a CorvusPay devolve o cliente à Success URL. O pedido só é marcado como pago depois que a CorvusPay confirma: o número do pedido na CorvusPay deve ter sido emitido por esta loja, a assinatura deve corresponder à Secret Key da loja em que o pagamento foi iniciado, e o valor e a moeda devem corresponder ao 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 CorvusPay payment has been received. Para Authorize only, a página mostra Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order., e para um pedido em status de revisão, Your payment was received and is being reviewed by the shop.
Se o pagamento não puder ser aplicado naquele momento (por exemplo, porque outra requisição está confirmando o mesmo pedido), o cliente vê Your payment is being confirmed com um botão Check again, que leva à página de sucesso assim que o pedido tiver um status. Se a requisição à Success URL não puder ser verificada, o cliente vê Payment not confirmed e We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. Nada é alterado. A Success URL também funciona enquanto a loja estiver em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup action) para as URLs de sucesso e de cancelamento. No OpenCart 4, o navegador não envia a sessão da loja quando a CorvusPay devolve o cliente, então a extensão primeiro mostra uma página curta que abre novamente o mesmo endereço a partir da sua loja: o cliente mantém o carrinho e o login.
Se o cliente cancelar na página da CorvusPay, o pedido fica sem status e o cliente volta à finalização de compra com o carrinho intacto e a mensagem The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. No OpenCart 4, essa mensagem é exibida acima da página de finalização de compra. 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, e uma nova tentativa recebe um novo número de pedido da CorvusPay. Se outro pedido do mesmo carrinho já estiver pago, o cliente é levado à página de sucesso em vez de pagar de novo.
No OpenCart 4, o pedido permanece na finalização de compra até a página de sucesso ser exibida. Se, nesse meio tempo, esse pedido foi fechado sem pagamento (por exemplo, você o cancelou), o Confirm Order ou o retorno da CorvusPay devolve o cliente à finalização de compra com Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 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 placed. The cart has changed since then: please confirm the new order to pay for it. Em ambos os casos, o próximo Confirm Order paga um novo pedido do carrinho.
Se o pagamento não puder ser iniciado, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão: CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … ou This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.
O pedido só é confirmado quando a CorvusPay devolve o cliente à Success URL; não há notificações de servidor para servidor. Se o cliente fechar o navegador logo depois de pagar, o pedido fica sem status. A extensão não oferece reembolsos, capturas ou anulações a partir do OpenCart (a API de servidor da CorvusPay exige um certificado de cliente), nem cartões salvos, assinaturas, parcelamentos ou formulário de cartão na própria loja.
Pedidos
Status de pedido
Sem status (pedido ausente): o cliente foi enviado à CorvusPay e não voltou com um pagamento confirmado, ou cancelou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders. Se o cliente pagou, mas não voltou, verifique o pagamento no CorvusPay Merchant Center e defina o status do pedido manualmente.
Processing, Completed ou status de revisão: o pagamento Sale foi confirmado. O status segue Order Status After Payment. Uma nota mostra o número do pedido na CorvusPay, o código de aprovação e o tipo de cartão.
Status de revisão, autorizado: Authorize only está selecionado. Capture o pagamento no CorvusPay Merchant Center e depois altere o status do pedido.
Status de revisão, divergência de valor ou de moeda: o valor ou a moeda pagos não correspondem ao pedido. Não envie antes de verificar o pagamento no CorvusPay Merchant Center.
Status de revisão, pagamento após o cancelamento: chegou um pagamento bem-sucedido referente a uma tentativa que o cliente havia cancelado. Atenda o pedido ou reembolse o pagamento no CorvusPay Merchant Center.
Se chegar outro pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você verifique o CorvusPay Merchant Center e reembolse o pagamento duplicado, se necessário. Se chegar um pagamento para outro pedido do mesmo carrinho enquanto um pedido já está pago, esse pedido permanece sem status e a nota é adicionada ao pedido pago.
As notas são entradas do History do pedido que o cliente não vê.
Aba VibeFox CorvusPay Gateway
Em Sales > Orders, abra um pedido pago com a CorvusPay. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox CorvusPay Gateway mostra o CorvusPay order number, o Status da tentativa de pagamento, o Transaction type, o Amount (e o valor recebido, se a CorvusPay o tiver informado), o Approval code, a Transaction, o tipo de Card e as CorvusPay notes. Pagamentos de teste são marcados com Test. A aba é somente leitura e é exibida para usuários que têm acesso à extensão.
Reembolsos: reembolsos, capturas e anulações a partir do OpenCart não são suportados. Faça-os no CorvusPay Merchant Center e registre o resultado no OpenCart manualmente. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela CorvusPay.
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 CorvusPay Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > 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-corvuspay e o link Manage licenses and domains in your account, que abre a sua conta na 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 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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, a CorvusPay 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. 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 prévia não está disponível: a loja não enxerga o login do painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece 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 CorvusPay.
Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
A CorvusPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o Store ID e a Secret Key do modo atual estão preenchidos (Test Store ID e Test Secret Key no modo de teste, Live Store ID e Live Secret Key no modo de produção) e se a moeda da finalização de compra é suportada pela CorvusPay. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Minimum Total.
O pagamento foi feito, mas o pedido continua sem status: provavelmente a Success URL não foi informada no CorvusPay Merchant Center, ou a Secret Key no OpenCart não corresponde à loja. Procure por INVALID signature no campo Log na página da extensão (erros são sempre registrados). O pedido também fica sem status se o cliente fechou o navegador antes de voltar; nesse caso, verifique o pagamento no Merchant Center e defina o status do pedido manualmente.
O cliente vê Payment not confirmed: a requisição à Success URL foi rejeitada: faltavam campos obrigatórios, o número do pedido na CorvusPay não foi emitido por esta loja, a Secret Key dessa loja está vazia ou a assinatura não correspondeu. Nada é alterado. O log mostra o motivo.
O cliente vê Your payment is being confirmed por muito tempo: o status do pedido não pôde ser definido. O log mostra o motivo; verifique o pagamento no Merchant Center.
O cliente vê This order total cannot be paid via CorvusPay: o total é zero ou tem mais de 2 casas decimais.
O cliente vê CorvusPay is not configured ou CorvusPay does not accept payments in …: falta o Store ID ou a Secret Key do modo atual, ou a moeda da finalização de compra não é suportada.
O cliente vê This payment method is not available. Please reload the checkout page.: a sessão de finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desativado nesse meio tempo. O cliente recarrega a finalização de compra.
O pedido está no status de revisão: leia as notas na aba VibeFox CorvusPay Gateway. Authorize only está selecionado, o valor ou a moeda pagos não correspondiam ao pedido, o pagamento chegou depois que o cliente tinha cancelado, ou Order Status After Payment está definido como On hold.
Para desenvolvedores: antes de o formulário ser assinado, a extensão dispara o evento do OpenCart corvuspay_p_form_params com os campos do formulário e o pedido.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox CorvusPay Gateway. 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, Minimum Total e os status da seção Order statuses, que voltam aos padrões em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, seus eventos e a ação de inicialização, que deixa a CorvusPay passar no modo de manutenção). Se Delete Data estiver ativada, as demais configurações do gateway (título, descrição, Store IDs, Secret Keys, modo de teste, configurações de pagamento, registro de log) e os arquivos de log são removidos. Se estiver desativada, são mantidos para uma reinstalação posterior. Os dados de transação da CorvusPay são sempre mantidos, então a aba da CorvusPay dos pedidos antigos volta após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox CorvusPay Gateway na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
A CorvusPay é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela CorvusPay.