VibeFox Moneris for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: CAD para uma conta canadense da Moneris, USD para uma conta legada da Moneris USA. O método de pagamento só é exibido quando a moeda da finalização de compra é a moeda da conta.

HTTPS e PCI DSS: os números de cartão são digitados na página de finalização de compra e passam pelo seu servidor. Pagamentos reais exigem HTTPS e conformidade com o PCI DSS SAQ D. Se você não puder cumprir isso, use em vez disso uma solução de página de pagamento hospedada.

Conta na Moneris: você precisa do Store ID e do API Token da sua loja no Moneris Gateway, disponíveis no Moneris Merchant Resource Center > Admin > Store Settings. Para testes, a loja de teste pública da Moneris já vem preenchida. As credenciais de teste e os cartões de teste estão no portal para desenvolvedores da Moneris.

Chave de licença VibeFox: adquirida 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_moneris_gateway-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_moneris_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_moneris_gateway-oc3-(version).ocmod.zip. A extensão não possui 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 Moneris 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 com o 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 License key).

4. Escolha o país da conta e informe o Live Store ID e o Live API Token. O modo de teste vem ativado por padrão e usa a loja de teste pública (store5 / yesguy para o Canadá, monusqa002 / qatoken para os EUA).

5. Escolha o tipo de transação e os logotipos de cartão; depois, ative Enable / Disable e clique em Save.

6. Faça um pedido de teste com um cartão de teste da Moneris e, depois, desative Test mode.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_moneris_gateway.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. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Moneris Gateway, clique em Install (o botão verde +) e, em seguida, em Edit (o botão com o lápis).

4. Informe a chave de licença e as configurações como nos passos 3 a 6 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

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

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Moneris Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página exibe Moneris gateway is in TEST MODE. No real charges will be made. enquanto o modo de teste estiver ativado. No modo de produção, ela avisa quando os campos de produção contêm credenciais de teste da Moneris (o método de pagamento fica então oculto na finalização de compra) e quando o SSL não está ativado na loja (no OpenCart 4, quando o endereço da vitrine começa com http://). Também avisa quando o método de pagamento está ativado, mas o Store ID ou o API Token do modo atual está vazio, e quando a moeda padrão da loja não é a moeda da conta Moneris; nos dois casos, o método de pagamento fica oculto na finalização de compra. 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 precisa ter de 1 a 128 caracteres, Sort Order precisa ser um número inteiro e Total precisa ser um número igual ou maior que 0. Se um valor estiver errado, a página mostra o erro e nada é salvo.

Moneris

Enable / Disable: Enable Moneris Gateway ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o título do método de pagamento exibido ao cliente. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Cartão de crédito (Moneris). No modo de teste, (Test Mode) é adicionado ao título. Obrigatório.

Description: o texto exibido acima dos campos do cartão na etapa Confirm Order. Padrão: Pay securely with your credit card.

Sort Order: a posição da Moneris entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: exibe o formulário do cartão 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 valor total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que o método de pagamento seja oferecido. Deixe em branco para oferecê-lo para qualquer valor.

Conta Moneris

Seu Store ID e seu API Token estão no Moneris Merchant Resource Center, em Admin > Store Settings. As credenciais de teste e os cartões de teste estão no portal para desenvolvedores da Moneris. A seção tem links para ambos.

Moneris account country: contas canadenses cobram em CAD; contas dos EUA, em USD. O método de pagamento só é exibido quando a moeda do pedido corresponde. Padrão: Canadá (CAD).

Test mode: usa o gateway de QA da Moneris e as credenciais de teste; nenhuma cobrança real é feita. Reembolsos, capturas e anulações são sempre enviados ao ambiente em que o pagamento foi feito. Os clientes veem TEST MODE: use a Moneris test card, no real charges are made. acima dos campos do cartão. Padrão: ativado.

Live Store ID: o Store ID de produção, por exemplo monca01234.

Live API Token: o API Token de produção.

Test Store ID: a loja de teste pública da Moneris: store5 (Canadá) ou monusqa002 (EUA). Padrão: store5.

Test API Token: o token de teste público: yesguy (Canadá) ou qatoken (EUA). Padrão: yesguy.

Os API Tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo. Para remover um token salvo, marque Clear the saved token on save abaixo do campo e clique em Save.

Pagamento

Transaction type: a forma como o cartão é cobrado. Padrão: Purchase.

Card logos: as bandeiras de cartão exibidas com o método de pagamento na finalização de compra: Visa, Mastercard, Discover, American Express, JCB. As bandeiras aceitas dependem da sua conta Moneris. Padrão: Visa e Mastercard.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a Moneris responde. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o cartão foi cobrado (uma compra ou a captura de uma pré-autorização). Padrão: Processando.

Authorized Status: uma pré-autorização: os valores estão apenas reservados, ainda não cobrados. Capture-os na aba do pedido ou definindo um status de pago. Padrão: Pendente.

On Hold (Review) Status: é necessária uma análise manual: o valor processado pela Moneris difere do pedido, ou a Moneris não respondeu e a verificação de status também falhou (o cartão pode ter sido cobrado). Uma observação explica o motivo. Padrão: Pendente, porque o OpenCart não tem um status Em espera. Você pode criar seus próprios status em System > Localisation > Order Statuses e selecioná-los aqui e em Authorized Status.

Canceled Status: definido por Void pre-authorization (cancel order) na aba do pedido. Definir um pedido com este status libera (anula) uma pré-autorização não capturada. Padrão: Cancelado.

Refunded Status: definido depois que o pagamento é totalmente reembolsado na aba do pedido. Definir um pedido com este status também libera uma pré-autorização não capturada. Padrão: Reembolsado.

Avançado

Debug log: registra as requisições e respostas da API em wc_mng_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Número do cartão, CVV, validade e API Token são mascarados. Os erros são sempre registrados, mesmo com esta opção desativada. Padrão: desativado.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. Os dados da Moneris dos pedidos (necessários para capturas e reembolsos) são sempre mantidos. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. Os API Tokens não são exportados.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. Os API Tokens salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Credit card (Moneris)). Na etapa Confirm Order, o cliente vê a sua descrição, os logotipos dos cartões e os campos Card number, Expiry (MM/YY) e Card code (CVC). Os três campos são obrigatórios. 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; os campos do cartão aparecem então no bloco de confirmação do pedido, no final da página de finalização de compra, acima do botão Confirm Order. Quando o cliente clica em Confirm Order, o seu servidor envia o cartão para a Moneris pelo total do pedido e recebe o resultado na hora. Não há redirecionamento nem webhook. Os dados do cartão são usados apenas nessa única requisição; nunca são armazenados, e o log mostra apenas os quatro últimos dígitos.

O pedido só recebe seu status a partir de uma resposta aprovada da Moneris, da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque. O carrinho é esvaziado e o cliente vê a página de sucesso do pedido do OpenCart. Com a pré-autorização, o pedido aguarda no Authorized Status até que você capture os valores. Se a Moneris processou um valor diferente do total do pedido, o pedido recebe o status de análise com uma observação.

Se o cartão for recusado, o cliente permanece na etapa Confirm Order com Your card was declined e o motivo informado pela Moneris, e pode conferir os dados do cartão ou usar outro. O pedido não mantém status; o motivo da recusa também é gravado no log. Se a Moneris não conseguiu processar a requisição (por exemplo, um Store ID ou API Token incorreto), o cliente vê The payment could not be processed. Please try again or use another payment method. O motivo é gravado no log. Campos de cartão incorretos geram mensagens curtas, como Please enter your card details., Invalid card number. ou Invalid card expiry date., e nada é enviado à Moneris.

Um segundo clique enquanto um pagamento está em processamento mostra A payment for this order is already being processed. Please wait a moment and check your order status before trying again. 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, depois de um cartão recusado, o cliente paga o mesmo pedido. De qualquer forma, a extensão trata todos os pedidos de um mesmo carrinho como um único pagamento: um carrinho já pago, ou cujo resultado é desconhecido, nunca é cobrado novamente, e o cliente vai para a página de sucesso. O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se esse pedido já tiver um status e o carrinho tiver produtos novamente (por exemplo, o pagamento foi concluído, mas a página de sucesso não foi exibida, e o cliente adicionou produtos), ou se o pedido foi cancelado, reembolsado ou se a pré-autorização foi anulada nesse meio-tempo, o cliente volta à página de finalização de compra em Confirm Order, e o próximo Confirm Order paga um novo pedido. Acima da página de finalização de compra, o cliente vê This order was cancelled or refunded by the store, so it cannot be paid again. Please check your cart and confirm the new order. quando o pedido foi encerrado, ou This order has already been paid, and your cart now holds a new purchase. Please check your cart and confirm the new order. quando ele foi pago por um carrinho anterior.

Se a Moneris não responder (erro de rede ou tempo esgotado), a extensão envia à Moneris uma verificação de status com o mesmo ID de pedido da Moneris para descobrir se a transação foi concluída. Se a Moneris não tiver essa transação, o cliente pode pagar novamente. Se a verificação de status também não obtiver resposta, o pedido recebe o status de análise com uma observação que indica o ID de pedido da Moneris, e o cliente não é convidado a pagar uma segunda vez. Se o pagamento foi concluído, mas não foi possível definir o status do pedido, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.

A extensão não tem cartões salvos nem Moneris Vault, assinaturas, Apple Pay, Google Pay ou Interac Online, Moneris Checkout ou Hosted Tokenization, 3-D Secure, AVS ou Kount, nem precificação em várias moedas.

Pedidos e reembolsos

Status dos pedidos

Sem status (pedido ausente): o cartão foi recusado ou não foi processado. O cliente pode pagar novamente. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processando): a compra foi aprovada, ou uma pré-autorização foi capturada. Uma observação mostra o valor, o Moneris Trans ID e o comprovante.

Authorized Status (padrão Pendente): uma pré-autorização foi aprovada e aguarda a captura.

On Hold (Review) Status (padrão Pendente): o valor processado era diferente do total do pedido, ou a Moneris não confirmou o resultado. As observações explicam.

Canceled Status (padrão Cancelado): para um pedido pré-autorizado, os valores reservados foram liberados (anulação).

Refunded Status (padrão Reembolsado): o pagamento foi totalmente reembolsado pela extensão.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox Moneris Gateway

Em Sales > Orders, abra um pedido pago com a Moneris. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Moneris Gateway mostra o Trans ID (e o Trans ID da pré-autorização após uma captura), o Moneris order ID, o Receipt, o Transaction type e o estado dele (não capturado, capturado ou liberado), a Account / environment com um rótulo Test mode para pagamentos de teste, o Card com o código de autorização, os valores Authorized / charged / refunded, os botões de captura, anulação e reembolso, o histórico de reembolsos e as Moneris notes do pedido. Para um pagamento não confirmado, a aba pede que você procure o ID do pedido da Moneris no Merchant Resource Center. A aba é exibida para os usuários que têm acesso à extensão; captura, anulação e reembolso exigem a permissão para modificar a extensão (definida em System > Users > User Groups).

Captura e anulação

Para capturar uma pré-autorização, clique em Capture payment na aba e confirme Capture the pre-authorized amount through Moneris?, ou altere o status do pedido com Add History para um status de pago, como Order Status After Payment ou outro status de processamento ou concluído do OpenCart. Captura-se o total do pedido, menos os reembolsos; não pode ser maior que o valor autorizado. Após uma captura feita pelo botão, o pedido recebe Order Status After Payment. Se a Moneris recusar a captura, o status não muda, nenhum e-mail é enviado, Add History mostra o motivo em vez de uma mensagem de sucesso, e uma observação explica: Moneris: status not changed — the pre-authorization could not be captured, com o motivo. As pré-autorizações da Moneris expiram após alguns dias, então capture-as a tempo.

Para liberar os valores, clique em Void pre-authorization (cancel order) e confirme, ou defina o pedido como Canceled Status. Definir o pedido como Refunded Status também libera uma pré-autorização aberta. Se a liberação falhar, uma observação pede que você a libere no Merchant Resource Center.

Essas alterações de status também funcionam enquanto a extensão está desativada (mas instalada); por isso, pré-autorizações feitas antes ainda podem ser capturadas e liberadas.

Reembolsos

Na aba VibeFox Moneris Gateway, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Moneris. Confirme a pergunta Refund this amount through Moneris? This cannot be undone. São aceitos reembolsos totais e parciais. Os reembolsos ficam limitados ao valor que a Moneris realmente cobrou; por isso, após uma divergência de valor, você pode reembolsar até o que o cliente pagou, e não o total do pedido. Uma pré-autorização só pode ser reembolsada depois de capturada; antes disso, anule-a para liberar os valores. O reembolso é enviado ao ambiente e à conta em que o pagamento foi feito, por isso as credenciais desse modo precisam continuar preenchidas. Se a Moneris não aceitar o reembolso, a aba mostra Refund failed com o motivo, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às observações, com o Moneris Trans ID. Um reembolso total define o pedido como Refunded Status; um reembolso parcial não altera o status. Captura, anulação e reembolso alteram diretamente o status do pedido, sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status.

As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Moneris.

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 Moneris Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Moneris 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-moneris e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do 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 em vibefox.net.

Sem uma chave ativa, a Moneris 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. Um usuário administrador conectado ao administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado com (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é-visualização não está disponível: a loja não vê 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 administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: capturas, anulações e reembolsos de pagamentos anteriores continuam funcionando.

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

Solução de problemas

A Moneris 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 um Store ID e um API Token. No modo de produção, os campos de produção devem conter as suas credenciais de produção, e não as credenciais de teste da Moneris. Verifique se a moeda da finalização de compra é a moeda da conta (CAD para o Canadá, USD para uma conta dos EUA), se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido está no status de análise: a extensão não tem webhook; o resultado vem apenas da resposta da Moneris. Leia as Moneris notes na aba. Se a Moneris não confirmou o resultado, ela não respondeu e a verificação de status também falhou. Procure o ID do pedido da Moneris no Merchant Resource Center: se a transação estiver lá, envie o pedido (e reembolse-o lá, se necessário); se não estiver, cancele o pedido ou peça ao cliente que pague novamente. Se o valor era diferente, confira o pedido e atenda-o ou reembolse o pagamento.

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, o método de pagamento foi desativado nesse meio-tempo, ou faltam as credenciais do modo atual (ou o modo de produção usa credenciais de teste da Moneris).

O cliente vê This payment method does not support the order currency.: a moeda do pedido não é a moeda da conta Moneris.

O cliente vê um erro ao pagar: consulte o campo Log na página da extensão. Os erros são sempre gravados; ative Debug log para ver as requisições e respostas completas.

A captura falha: o pedido não tem uma pré-autorização aguardando captura, o total do pedido é zero, ou o valor é maior que o valor autorizado. Além disso, as pré-autorizações da Moneris expiram após alguns dias.

O reembolso, a captura ou a anulação falham com uma mensagem sobre o modo ou a conta: o pagamento foi feito no modo de teste ou de produção e as credenciais desse modo não estão definidas, ou o pagamento foi feito com uma conta Moneris de outro país. Informe as credenciais ou processe o pagamento no Merchant Resource Center.

Ataques de teste de cartões: formulários de cartão diretos são alvo de testes de cartões. Use as regras eFraud ou de velocidade da sua conta Moneris e uma extensão de CAPTCHA ou de limitação de requisições para a sua loja.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Moneris 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, Total e os status de pedido da seção Orders, que voltam aos valores padrão em uma nova instalação. Os eventos do OpenCart da extensão também são removidos, então as alterações de status não capturam nem liberam mais pré-autorizações. Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, país da conta, modo de teste, Store IDs e API Tokens, tipo de transação, logotipos de cartão, logging) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. As transações e os reembolsos da Moneris são sempre mantidos, de modo que pedidos pagos antes ainda podem ser capturados ou reembolsados após uma reinstalação. Os pedidos existentes mantêm suas observações 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 Moneris Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Moneris é uma marca registrada do seu titular. Esta extensão não é afiliada à Moneris nem endossada por ela.