VibeFox Helcim for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou posterior.

HTTPS e PCI DSS: os dados do cartão são digitados na finalização de compra e enviados do seu servidor para a Helcim. Eles nunca são armazenados nem registrados em log, mas passam pelo seu servidor; por isso, sua loja precisa de certificado SSL para a finalização de compra, e sua hospedagem deve atender ao PCI DSS (SAQ D).

Moeda: a Helcim processa CAD e USD. O método de pagamento só é exibido quando a moeda da finalização de compra é uma das Account currencies definidas na extensão.

Conta na Helcim: uma conta de comerciante na Helcim no Canadá ou nos Estados Unidos e um token de API com direito de processar transações (veja Configuration). Uma conta de teste (developer) na Helcim é opcional para testes.

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 do OpenCart 3 wcp_helcim_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_helcim_gateway.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á até Extensions > Installer, clique em Upload e escolha o arquivo wcp_helcim_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então não é preciso atualizar Extensions > Modifications. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá até Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Helcim Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter o direito de 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. Na Helcim, abra All Tools > Integrations > API Access Configuration, crie um acesso à API com direito de processamento de transações (compras, pré-autorizações, capturas e reembolsos) e copie o token.

5. Cole o token em Live API token e o token da sua conta de teste da Helcim em Test API token, caso tenha uma.

6. Escolha o Transaction type e as Account currencies, ative Enable / Disable e clique em Save. Para testar primeiro, ative Test mode e pague com sua conta de teste; depois desative.

OpenCart 4

1. No painel administrativo, vá até Extensions > Installer, clique em Upload e escolha o arquivo wcp_helcim_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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á até Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Helcim Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

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

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

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Helcim 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 avisa se a moeda padrão da sua loja não está entre as Account currencies (nesse caso, a Helcim só é oferecida para pedidos em uma moeda permitida) e, enquanto o método de pagamento estiver ativado, se o token de API do modo atual estiver vazio (o método de pagamento fica então oculto na finalização de compra). 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 estar 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 cada status de pedido precisa existir. Se algo estiver errado, nada é salvo e a página lista os erros.

Helcim

Enable / Disable: Enable Helcim Gateway liga ou desliga o método de pagamento. Padrão: desligado.

Title: o título do método de pagamento exibido na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit card (Helcim). Obrigatório.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do formulário do cartão. Padrão: Pay securely with your credit card.

Sort Order: a posição do método de pagamento na finalização de compra. Deixe em branco ou digite um número inteiro.

Geo Zone: exibe o formulário do cartão apenas para endereços de pagamento da 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 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.

Credenciais de API

Na Helcim, vá até All Tools > Integrations > API Access Configuration, crie um acesso à API e copie o token. Dê a ele o direito de processamento de transações para compras, pré-autorizações, capturas e reembolsos. As contas de teste da Helcim usam o mesmo endereço de API das contas reais, então o modo de teste simplesmente usa o token da sua conta de teste da Helcim. A seção traz um link para a documentação da API da Helcim.

Live API token: o token de API da sua conta real da Helcim. É usado quando o modo de teste está desativado.

Test mode: usa o Test API token (conta de teste da Helcim). Pagamentos, capturas e reembolsos são enviados à sua conta de teste da Helcim, e os clientes veem um aviso de modo de teste. Capturas e reembolsos de um pedido sempre usam o token do modo em que o pedido foi pago. Padrão: desligado.

Test API token: o token de API da sua conta de teste (developer) da Helcim. É usado quando o modo de teste está ligado.

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: como o cartão é cobrado.

Account currencies: as moedas que sua conta da Helcim pode processar. Os pedidos são sempre cobrados na moeda do pedido. O método de pagamento fica oculto na finalização de compra para outras moedas.

Pedidos

O pedido é criado na etapa Confirm Order sem status (um pedido ausente) e só recebe um status depois que a Helcim aprova o cartão. Cada campo lista os status de pedido do seu OpenCart.

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

Authorized Status: pré-autorização: os valores estão apenas reservados, ainda não cobrados. Capture-os com Capture payment na aba do pedido. Padrão: Pendente, porque o OpenCart não tem o status On hold.

On Hold (Review) Status: a resposta da Helcim não corresponde ao pedido (aprovação parcial, outra moeda, sem ID de transação, ou o total do pedido é diferente da cobrança). Verifique a transação na Helcim antes de atender o pedido; uma observação explica o motivo. Padrão: Pendente. Você pode criar seus próprios status em System > Localisation > Order Statuses para distinguir pedidos autorizados e pedidos em análise.

Canceled Status: uma pré-autorização não capturada foi liberada na aba do pedido (o cliente não foi cobrado). Padrão: Cancelado.

Refunded Status: definido após o pagamento ser reembolsado por completo na aba do pedido. Padrão: Reembolsado.

Avançado

Debug log: grava as requisições e respostas da API em wc_hlg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Os números de cartão são reduzidos aos últimos 4 dígitos. CVC, validade, tokens, nomes, endereços, e-mails e endereços IP nunca são registrados em log. Erros (pagamentos recusados ou falhos, erros de API, capturas e reembolsos falhos) são sempre registrados, mesmo quando esta opção está desligada. Padrão: desligado.

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

Delete data on uninstall: quando ligado, desinstalar a extensão remove as configurações do gateway e os arquivos de log. As transações e reembolsos da Helcim são sempre mantidos, para que pedidos pagos antes possam ser capturados e reembolsados depois de uma reinstalação. Padrão: desligado.

Importar / Exportar

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

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. Os tokens de API 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 (Helcim)). Na etapa Confirm Order, o cliente vê um ícone de cartão, sua descrição e o formulário com Card Number, Expiry (MM/YY), CVC e Cardholder Name. No modo de teste, o formulário mostra TEST MODE — payments go to a Helcim test account, no real charges are made. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão verifica a soma de controle do número do cartão, se a validade é válida e não está vencida, se o CVC tem 3 ou 4 dígitos e se o nome foi preenchido. Os erros aparecem acima do formulário, e nada é enviado à Helcim.

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. O formulário do cartão então aparece no bloco de confirmação do pedido, na parte inferior da página de finalização de compra, acima do botão Confirm Order. Por padrão, o OpenCart 4 não pede um endereço de pagamento; nesse caso, a extensão envia à Helcim o endereço de entrega para a verificação de endereço, junto com o nome do titular do cartão.

Em seguida, seu servidor envia o cartão à Helcim como compra ou pré-autorização pelo valor total do pedido, na moeda do pedido. O nome do titular, o endereço de pagamento, o telefone e o e-mail são enviados para a verificação de endereço. O pagamento aparece na Helcim com um número de fatura formado pelo número do pedido, -OC e um código curto. A Helcim responde na mesma requisição. O pedido só recebe o status depois que a Helcim aprova a transação, do modo padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque. O carrinho é esvaziado imediatamente, e o cliente vai para a página de sucesso do pedido do OpenCart.

Apenas uma tentativa de pagamento por carrinho é executada por vez, e um carrinho já pago nunca é cobrado de novo, mesmo que o OpenCart tenha criado um novo pedido para ele nesse meio tempo (OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; no OpenCart 4, um pedido anterior ou uma segunda aba do navegador ainda podem estar associados ao mesmo carrinho). O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza, por isso, após um cartão recusado, o cliente paga o mesmo pedido. Se esse pedido foi encerrado nesse meio tempo (por exemplo, você o cancelou), ou se já estiver pago e o carrinho tiver agora uma nova compra, o Confirm Order leva o cliente de volta à página de finalização de compra com Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order. acima dela, e o próximo Confirm Order paga um novo pedido do carrinho. Qualquer alteração no carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de pagamento próprio. Cada tentativa usa uma chave de idempotência. Se a Helcim não responder, o pedido fica sem status, e uma nova tentativa em até 5 minutos devolve o resultado original da Helcim em vez de cobrar o cartão duas vezes. Se o pagamento foi aprovado, mas não foi possível definir o status do pedido, a próxima tentativa do mesmo carrinho define o status sem cobrar o cartão novamente.

Mensagens que o cliente pode ver acima do formulário: Your card was declined. Please check the card details or use another card. quando a Helcim recusa; Payment failed: com o motivo da Helcim para outras requisições recusadas; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. quando a Helcim não responde; This payment method is temporarily unavailable. Please choose another payment method. quando o token de API é rejeitado; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. em caso de envio duplo; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. quando o pagamento foi aprovado, mas não foi possível definir o status do pedido. O cliente permanece na etapa Confirm Order com o mesmo carrinho. Os detalhes técnicos vão para o log.

A extensão não usa HelcimPay.js nem Helcim.js, por isso os dados do cartão passam pelo seu servidor. Ela não tem cartões salvos, assinaturas, pagamentos ACH ou bancários, Apple Pay, Google Pay ou 3-D Secure, nem webhooks da Helcim.

Pedidos e reembolsos

Status do pedido

Sem status (pedido ausente): o cartão foi recusado, a Helcim não respondeu ou o cliente ainda não pagou. Recusas e erros são gravados no log e adicionados como observações. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processing): uma compra foi aprovada, ou uma pré-autorização foi capturada. Uma observação mostra o ID da transação, o código de aprovação, o tipo de cartão, os últimos 4 dígitos e o modo.

Authorized Status (padrão Pending): uma pré-autorização foi aprovada. Os valores estão apenas reservados. Capture-os ou libere-os com um reembolso total.

On Hold (Review) Status (padrão Pending): a Helcim aprovou uma transação, mas o valor, a moeda ou o ID da transação na resposta não correspondem ao pedido, por exemplo após uma aprovação parcial ou quando o total do pedido mudou durante o pagamento. A observação diz Helcim response verification FAILED. Verifique a transação na Helcim antes de atender o pedido.

Refunded Status (padrão Refunded): o pagamento foi reembolsado por completo pela extensão.

Canceled Status (padrão Canceled): uma pré-autorização não capturada foi liberada. O cliente não foi cobrado.

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

Aba VibeFox Helcim Gateway

Em Sales > Orders, abra um pedido pago com a Helcim. Na parte de baixo da página do pedido, ao lado de History e Additional, a aba VibeFox Helcim Gateway mostra o Transaction ID (e o ID da pré-autorização após uma captura) com um rótulo Test mode para pagamentos de teste, o Transaction type e o estado da captura, a Invoice, o Card e o código de aprovação, os valores Approved / order / refunded, o botão de captura e o formulário de reembolso, o histórico de reembolsos e as Helcim notes do pedido. A aba é exibida aos usuários que têm acesso à extensão; capturas e reembolsos exigem o direito de modificação (definido em System > Users > User Groups).

Captura

Para uma pré-autorização não capturada, clique em Capture payment na aba (o botão mostra o valor) e confirme Capture the pre-authorized amount through Helcim? É capturado o total atual do pedido, menos os reembolsos. Ele pode ser menor que o valor autorizado, mas nunca maior. A captura usa o token do modo em que o pedido foi pago. Após uma captura bem-sucedida, o pedido recebe Order Status After Payment. Se a captura falhar, a aba mostra o motivo e o adiciona às observações.

Reembolsos

Na aba, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Helcim. Confirme Refund this amount through Helcim? This cannot be undone. São suportados reembolsos totais e parciais de uma compra ou de uma pré-autorização capturada, até o valor que a Helcim realmente cobrou; por isso, após uma aprovação parcial, você não pode reembolsar mais do que o cliente pagou. Para uma pré-autorização não capturada, o botão é Release pre-authorization: só o valor total pode ser liberado, a reserva é removida e o pedido recebe Canceled Status.

O reembolso é enviado no modo em que o pedido foi pago, então o token desse modo precisa estar definido. Ele só conta quando a Helcim o aprova. Se a Helcim o recusar, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às observações, com o ID da transação de reembolso da Helcim. Um reembolso total define o pedido como Refunded Status sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status. Um reembolso parcial não altera o status. Uma nova tentativa após um tempo limite não reembolsa duas vezes.

As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Helcim. A extensão não recebe webhooks da Helcim: capturas, reembolsos e anulações feitos no painel da Helcim não são refletidos no OpenCart, então faça-os na página 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 Helcim Gateway é o primeiro bloco de Extensions > Extensions > Payments > VibeFox Helcim 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-payment-helcim e o link Manage licenses and domains in your account, que abre 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 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 após 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 Helcim 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 painel 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é-visualização não está disponível: a loja não enxerga o login do administrador, por isso, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já feitos são mantidos, e capturas e reembolsos continuam funcionando.

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

Solução de problemas

A Helcim não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado, se o modo atual tem o token de API (Live API token, ou Test API token no modo de teste) e se a moeda da finalização de compra está entre as Account currencies. A página de configurações mostra um aviso quando o token está ausente ou a moeda da loja não é permitida. 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.

O cliente viu We could not confirm your payment: a Helcim não respondeu, então o cartão pode ter sido cobrado. A observação do pedido e o log informam a fatura da Helcim. Verifique essa fatura na Helcim antes de cobrar o cliente novamente. Uma nova tentativa em até 5 minutos devolve o resultado original e não cobra duas vezes.

Os clientes veem This payment method is temporarily unavailable: a Helcim rejeitou o token de API. A observação do pedido orienta a verificar o token e as permissões dele. Certifique-se de que o acesso à API tem o direito de processamento de transações.

Os clientes veem This payment method is not available. Please reload the checkout page.: a sessão da finalização de compra não corresponde mais ao pedido, o método de pagamento foi desligado nesse meio tempo, ou o token ou a moeda não são mais adequados. O cliente recarrega a finalização de compra.

Pagamento falhou com um motivo da Helcim: a Helcim recusou a requisição, por exemplo por causa do cartão ou dos dados de cobrança. A observação do pedido e o log têm os detalhes.

O cliente viu Your payment was received, but the order could not be completed: a Helcim aprovou o pagamento, mas o OpenCart não conseguiu definir o status do pedido. O log informa o motivo. Quando o cliente envia o mesmo carrinho novamente, o status é definido a partir do pagamento aprovado, sem uma segunda cobrança.

O pedido está em status de análise: leia as observações na aba VibeFox Helcim Gateway. A resposta da Helcim não correspondeu ao pedido (falha na verificação da resposta). Verifique a transação na Helcim e, em seguida, atenda o pedido ou reembolse o pagamento.

A captura não é possível: o valor a capturar precisa ser maior que 0 e não pode ultrapassar o valor autorizado, e o token do modo em que o pedido foi pago precisa estar definido.

O reembolso falha: leia a mensagem. Uma pré-autorização não capturada só pode ser liberada por completo. Uma mensagem sobre o modo significa que o token do modo em que o pedido foi pago está vazio. Um reembolso recusado não é registrado. You do not have permission to capture or refund (modify this extension). significa que seu grupo de usuários não tem o direito de modificar a extensão.

Pagamentos de teste: o modo de teste envia pagamentos, capturas e reembolsos para sua conta de teste da Helcim. Os pedidos mantêm o modo em que foram pagos, então mudar o modo depois não transfere as capturas e os reembolsos deles para a outra conta.

Desinstalação

Vá até Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Helcim 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 reinstalação. No OpenCart 4, o evento do OpenCart da extensão, que exibe a mensagem acima da página de finalização de compra, também é removido. Se Delete data on uninstall estiver ligado, são removidas as demais configurações do gateway (título, descrição, tokens de API, modo de teste, tipo de transação, moedas da conta, chave do log de depuração) e o log. Se estiver desligado, elas são mantidas para uma reinstalação posterior. As transações e os reembolsos da Helcim são sempre mantidos, para que pedidos pagos antes possam ser capturados e reembolsados depois de 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, vá até Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Helcim Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

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