VibeFox Moneris for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão SimpleXML. O módulo não é instalado em versões antigas do PHP nem sem SimpleXML.

Moeda da loja: CAD para uma conta canadense da Moneris, USD para uma conta antiga da Moneris USA. A forma de pagamento só é exibida quando a moeda do carrinho é a moeda da conta.

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

Conta Moneris: você precisa do Store ID e do API Token da sua loja no Moneris Gateway, que ficam em 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 de desenvolvedores da Moneris.

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 o VibeFox Moneris Gateway na lista de módulos e clique em Configure.

3. Digite sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).

4. Escolha o país da conta e preencha 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 Purchase ou Pre-Authorization e os logotipos dos cartões, depois ative Enable / Disable e clique em Save.

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

Ao ser instalado, o módulo cria dois status de pedido: Moneris payment authorized e Moneris payment on hold. O PrestaShop habilita o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringir isso em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Moneris Gateway > Configure. Cada seção tem o seu botão Save, que salva a página inteira. Acima dos campos, a página mostra Moneris gateway is in TEST MODE. No real charges will be made. enquanto o modo de teste está ativo. No modo live, ela avisa se os campos live contêm credenciais de teste da Moneris (a forma de pagamento fica então oculta na finalização de compra) e se o SSL não está ativo na loja. Ela também avisa se a moeda padrão da loja não é a moeda da conta Moneris; a forma de pagamento fica então oculta na finalização de compra para as outras moedas.

Moneris

Enable / Disable: Enable Moneris Gateway liga ou desliga a forma de pagamento. Padrão: desligado.

Title: o título da forma de pagamento exibido ao cliente. Também é o nome da forma de pagamento salvo no pedido. Padrão: Credit card (Moneris). No modo de teste, (Test Mode) é acrescentado ao título. Obrigatório.

Description: o texto exibido acima dos campos do cartão na finalização de compra. Padrão: Pay securely with your credit card.

Conta Moneris

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

País da conta Moneris: contas canadenses cobram em CAD, contas dos EUA em USD. A forma de pagamento só é exibida quando a moeda do carrinho corresponde. Padrão: Canada (CAD).

Test mode: usa o gateway de QA da Moneris e as credenciais de teste; nenhuma cobrança real é feita. Capturas, anulações e reembolsos são sempre enviados para o 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: ligado.

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.

Clear saved tokens: marque um token e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Pagamento

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

Card logos: as bandeiras de cartão exibidas junto com a forma 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.

Avançado

Debug log: registra as requisições e respostas da API em logs/wc_mng_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Número do cartão, CVV, validade e API token são mascarados. Erros são sempre registrados, mesmo com a opção desligada. Padrão: desligado.

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

Delete data on uninstall: quando ligado, desinstalar o módulo remove as configurações do gateway e o registro. Os dados Moneris dos pedidos (necessários para os reembolsos) e os status de pedido sempre permanecem. Padrão: desligado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe a forma de pagamento (por padrão Credit card (Moneris)) e digita Card number, Expiry (MM/YY) e Card code (CVC) no formulário do cartão abaixo da opção. Os três campos são obrigatórios. Quando o pedido é feito, o seu servidor envia o cartão à Moneris pelo total do carrinho e recebe o resultado na hora. Não há redirecionamento nem webhook. Os dados do cartão são usados apenas nessa requisição; nunca são armazenados, e o registro mostra apenas os últimos quatro dígitos.

O pedido só é criado a partir de uma resposta aprovada da Moneris. Depois, o cliente vê a página padrão de confirmação do pedido. Com Pre-Authorization, o pedido fica em Moneris payment authorized até você capturar os valores. Se a Moneris tiver processado um valor diferente do total do carrinho, ou se o carrinho tiver mudado durante o pagamento, o pedido é criado em Moneris payment on hold com uma nota.

Se o cartão for recusado, o cliente permanece na finalização de compra com Your card was declined e o motivo informado pela Moneris, e pode conferir os dados do cartão ou usar outro. Nenhum pedido é criado. Se a Moneris não conseguir processar a requisição (por exemplo, com 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 registro. Dados de cartão incorretos geram mensagens curtas, como Invalid card number. ou Invalid card expiry date., e nada é enviado à Moneris.

Um segundo clique ou uma segunda aba do navegador enquanto um pagamento está sendo processado mostra A payment for this order is already being processed. Please wait a moment and check your order status before trying again. Um carrinho que já tem um pedido nunca é cobrado de novo; o cliente é direcionado ao pedido existente.

Se a Moneris não responder (erro de rede ou tempo esgotado), o módulo envia à Moneris um Status Check com o mesmo ID de pedido da Moneris para descobrir se a transação foi concluída. Se a Moneris não tiver nenhuma transação assim, o cliente pode pagar novamente. Se o Status Check também não obtiver resposta, o pedido é criado em Moneris payment on hold com o ID do pedido na Moneris, e o cliente não é convidado a pagar uma segunda vez.

O módulo 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 preços em várias moedas.

Pedidos e reembolsos

Status do pedido

No order yet: o cartão foi recusado ou não processado. Existem apenas o carrinho e a tentativa no registro. O cliente pode pagar novamente.

Payment accepted: a compra foi aprovada. O pagamento é registrado com o número da transação Moneris como ID da transação.

Moneris payment authorized: uma pré-autorização foi aprovada e aguarda captura. Nenhum pagamento foi registrado ainda.

Moneris payment on hold: o valor processado era diferente do total do carrinho, o carrinho mudou durante o pagamento, a Moneris não confirmou o resultado, ou o PrestaShop gravou um status de pago embora a captura tivesse falhado. As notas explicam. Para uma compra com valor diferente, o pagamento é registrado com o valor processado pela Moneris.

Canceled: para um pedido pré-autorizado, o cancelamento libera os valores reservados (void).

Refunded: o pagamento foi reembolsado integralmente pelo módulo.

Bloco de pagamento Moneris

A página do pedido mostra um bloco Moneris payment com o ID do pedido na Moneris, o país e o modo da conta, um selo Test mode para pagamentos de teste, o Trans ID (e o Trans ID da pré-autorização após uma captura), o tipo de transação e o estado dela (não capturada, capturada ou liberada), o recibo e o tipo de cartão, o valor processado, o total do pedido e o valor reembolsado, o histórico de reembolsos e as Moneris notes do pedido. Para um pagamento não confirmado, o bloco pede que você procure o ID do pedido na Moneris no Merchant Resource Center. Todas as ações do bloco exigem apenas a permissão para editar pedidos.

Captura e anulação

Para capturar uma pré-autorização, clique em Capture payment no bloco e confirme, ou mude o pedido para um status de pago como Pagamento aceito, Enviado ou Entregue. O total do pedido, menos os reembolsos, é capturado; ele não pode ser maior que o valor autorizado. Após uma captura pelo botão, o pedido passa para Payment accepted; o pagamento é registrado com o Trans ID da captura. Se a Moneris recusar a captura, o status não muda, nenhum e-mail de status de pago é enviado e uma nota explica: Status not changed: the Moneris pre-authorization could not be captured, com o motivo. As pré-autorizações da Moneris expiram após alguns dias, então capture a tempo.

Para liberar os valores, clique em Void pre-authorization (cancel order) ou mude o pedido para Cancelado. Mudar o pedido para Reembolsado também libera uma pré-autorização aberta. Se a liberação falhar, uma nota pede que você a libere no Merchant Resource Center.

Reembolsos

No bloco Moneris payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Moneris. Confirme a pergunta Refund this amount through Moneris? This cannot be undone. Reembolsos totais e parciais são aceitos. Os reembolsos ficam limitados ao valor que a Moneris efetivamente cobrou; por isso, após uma diferença de valores, você pode reembolsar até o que o cliente pagou, e não até o total do pedido. Uma pré-autorização só pode ser reembolsada depois de capturada; antes disso, cancele o pedido para liberar os valores. O reembolso é enviado ao ambiente e à conta em que o pagamento foi feito, então as credenciais desse modo devem continuar preenchidas. Se a Moneris não aceitar o reembolso, o bloco mostra Refund failed com o motivo, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas com o Trans ID da Moneris. Um reembolso total muda o pedido para Refunded; um reembolso parcial não altera o status.

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

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 Moneris Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Moneris Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: presta-payment-moneris 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 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 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. Libere-a na sua conta vibefox.net.

Sem uma chave ativa, a Moneris 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á conectado ao back office, então a forma de pagamento também fica oculta para você: pode configurar o módulo antes de comprar uma chave, mas não 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: capturas, anulações e reembolsos de pagamentos anteriores continuam funcionando.

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 inserção da chave e 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 Moneris não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado e se o modo atual tem Store ID e API Token. No modo live, os campos live devem conter as suas credenciais de produção, não as credenciais de teste da Moneris. Verifique se a moeda do carrinho é a moeda da conta: CAD para o Canadá, USD para uma conta dos EUA. Em Payment > Preferences, verifique se o módulo está permitido para essa moeda, para o país do cliente e para o grupo do cliente.

O pagamento foi concluído, mas o pedido está em Moneris payment on hold: o módulo não tem webhook; o resultado vem somente da resposta da Moneris. Leia as Moneris notes no bloco. Se a Moneris não confirmou o resultado, significa que ela não respondeu e que o Status Check também falhou. Procure o ID do pedido na Moneris no Merchant Resource Center: se a transação estiver lá, envie o pedido (e reembolse lá, se necessário); se não estiver, cancele o pedido ou peça ao cliente que pague novamente. Se o valor foi diferente, confira o pedido e atenda-o ou reembolse o pagamento.

O cliente vê Payment gateway is misconfigured. Please contact the store administrator.: faltam as credenciais do modo atual, ou o modo live está ativo com credenciais de teste da Moneris nos campos live. Digite o seu Store ID e API Token de produção.

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

O cliente vê um erro ao pagar: consulte o campo Log na página do módulo. 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. As pré-autorizações da Moneris também expiram após alguns dias.

Reembolso, captura ou anulação falha com uma mensagem sobre o modo ou a conta: o pagamento foi feito no modo de teste ou live, e as credenciais desse modo não estão preenchidas, ou o pagamento foi feito com uma conta Moneris do outro país. Preencha 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 um módulo de CAPTCHA ou de limitação de requisições para a sua loja.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Moneris Gateway 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 ligado, as configurações do gateway e o registro são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. As transações e os reembolsos da Moneris e os status de pedido Moneris payment authorized e Moneris payment on hold 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 as suas notas de pagamento e IDs de transação.

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