VibeFox Helcim for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões mais antigas do PHP.
HTTPS e PCI DSS: os dados do cartão são inseridos na sua finalização de compra e enviados do seu servidor para a Helcim por HTTPS. Eles nunca são armazenados nem registrados, mas passam pelo seu servidor, portanto a sua loja precisa de um certificado SSL e a sua hospedagem deve atender ao PCI DSS (SAQ D).
Conta na Helcim: uma conta de comerciante na Helcim no Canadá ou nos Estados Unidos e um token de API com direito de processamento de transações (veja Configuração). A Helcim processa CAD e USD. Uma conta de teste (desenvolvedor) na Helcim é opcional para testes.
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 Helcim Gateway na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
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, reembolsos) e copie o token.
5. Cole o token em Live API token, e o token da sua conta de teste na 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 o Test mode e pague com a sua conta de teste; depois, desative-o.
Na instalação, o módulo cria dois status de pedido, Helcim payment authorized e Helcim payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Helcim Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a moeda padrão da sua loja não está entre as Account currencies e, enquanto a forma de pagamento estiver ativada, quando o token de API do modo atual está vazio. Nesse caso, a forma de pagamento fica oculta na finalização de compra.
Helcim
Enable / Disable: Enable Helcim Gateway ativa ou desativa a forma de pagamento. Padrão: off.
Title: o título da forma de pagamento exibido na finalização de compra. É também o nome da forma de pagamento salvo no pedido. Padrão: Credit card (Helcim). Obrigatório.
Description: a descrição da forma de pagamento exibida na finalização de compra. Padrão: Pay securely with your credit card.
Credenciais de API
Na Helcim, vá em 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 de produção, portanto o modo de teste simplesmente usa o token da sua conta de teste na Helcim.
Live API token: o token de API da sua conta de produção na 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 vão para a sua conta de teste na 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: off.
Test API token: o token de API da sua conta de teste (desenvolvedor) na Helcim. É usado quando o modo de teste está ativado.
Os tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente 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.
Account currencies: as moedas que a sua conta na Helcim pode processar. Os pedidos são sempre cobrados na moeda do carrinho. A forma de pagamento fica oculta na finalização de compra para as demais moedas.
Avançado
Debug log: grava as requisições e respostas da API em logs/wc_hlg_debug.log.php, na pasta do módulo. 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. Erros (pagamentos recusados ou com falha, erros da API, capturas e reembolsos com falha) são sempre registrados, mesmo com esta opção desativada. Padrão: off.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway e os arquivos de registro. As transações, os reembolsos e os status de pedido da Helcim sempre permanecem, portanto os pedidos pagos antes ainda podem ser capturados e reembolsados após uma reinstalação. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe a forma de pagamento (por padrão Credit card (Helcim), com um ícone de cartão) e preenche Card Number, Expiry (MM/YY), CVC e Cardholder Name no formulário abaixo. No modo de teste, o formulário exibe TEST MODE — payments go to a Helcim test account, no real charges are made. Quando o cliente finaliza o pedido, o módulo verifica o dígito verificador do número do cartão, se a validade é correta e não expirou, se o CVC tem 3 ou 4 dígitos e se o nome está preenchido. Os erros são exibidos na finalização de compra, e nada é enviado à Helcim.
Em seguida, o seu servidor envia o cartão à Helcim como compra ou pré-autorização pelo total do carrinho, na moeda do carrinho. O endereço de cobrança, o telefone e o e-mail são enviados para verificação de endereço. O pagamento aparece na Helcim com um número de fatura formado pelo número do carrinho, -PS e um código curto. A Helcim responde na mesma requisição. O pedido só é criado depois que a Helcim aprova a transação, e o cliente chega à página padrão de confirmação do pedido. Antes disso, nenhum pedido existe.
Apenas uma tentativa de pagamento por carrinho é executada por vez, e um carrinho que já tem um pedido nunca é cobrado novamente. Cada tentativa usa uma chave de idempotência. Se a Helcim não responder, nenhum pedido é criado, e uma nova tentativa em até 5 minutos retorna o resultado original da Helcim em vez de cobrar o cartão duas vezes. Se o pagamento foi aprovado, mas o pedido não pôde ser criado, a tentativa seguinte do mesmo carrinho cria o pedido sem cobrar o cartão novamente.
Mensagens que o cliente pode ver na finalização de compra: 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 está ausente ou foi recusado pela Helcim; 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 o pedido não pôde ser criado. O carrinho é mantido. Os detalhes técnicos vão para o registro.
O módulo não usa HelcimPay.js nem Helcim.js, então os dados do cartão passam pelo seu servidor. Ele 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
No order: o cartão foi recusado, a Helcim não respondeu ou o cliente ainda não pagou. Existe apenas o carrinho. Recusas e erros são gravados no registro.
Payment accepted: uma compra foi aprovada, ou uma pré-autorização foi capturada. O pagamento é registrado com o ID da transação na Helcim, e uma nota mostra o ID da transação, o código de aprovação, a bandeira do cartão, os últimos 4 dígitos e o modo.
Helcim payment authorized: uma pré-autorização foi aprovada. Os fundos apenas estão retidos. Capture-os ou libere-os com um reembolso total.
Helcim payment on hold: a Helcim aprovou uma transação, mas o valor, a moeda ou o ID da transação na resposta não correspondem ao carrinho, por exemplo após uma aprovação parcial ou se o carrinho foi alterado durante o pagamento. A nota diz Helcim response verification FAILED. Para uma compra, o pagamento é registrado com o valor que a Helcim realmente cobrou. Verifique a transação na Helcim antes de atender o pedido.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Canceled: uma pré-autorização não capturada foi liberada. O cliente não foi cobrado.
Se uma segunda transação for aprovada para um carrinho que já tem um pedido, o pedido não é alterado. Uma nota pede que você a verifique e a estorne ou reembolse na Helcim.
Bloco de pagamento da Helcim
A página do pedido mostra um bloco Helcim payment com o ID da transação (e o ID da pré-autorização após uma captura), o tipo de transação e o estado da captura, o número da fatura, o cartão e o código de aprovação, o valor aprovado, o total do pedido e o valor reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Helcim notes do pedido. Captura e reembolsos exigem a permissão para editar pedidos.
Captura
Para um pedido em Helcim payment authorized, clique em Capture payment no bloco 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 pré-autorizado, mas não maior. A captura usa o token do modo em que o pedido foi pago. Após uma captura bem-sucedida, o pedido passa para Pagamento aceito, e o pagamento é registrado com o ID da transação de captura. Se a captura falhar, o bloco mostra o motivo e o acrescenta às notas.
Reembolsos
No bloco, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, 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; assim, 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 retenção é removida e o pedido passa para Cancelado.
O reembolso é enviado no modo em que o pedido foi pago, por isso o token desse modo precisa estar definido. Ele só conta se a Helcim o aprovar. Se a Helcim o recusar, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID da transação de reembolso da Helcim. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status. Uma nova tentativa após tempo limite não reembolsa duas vezes.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Helcim. O módulo não recebe webhooks da Helcim: capturas, reembolsos e anulações feitos no painel da Helcim não são refletidos no PrestaShop, então faça-os pela página do pedido.
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 Helcim Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Helcim 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 deles ficam a linha Product: presta-payment-helcim 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 seguido de uma data. Depois que o endereço da loja for alterado, 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 sua vaga de domínio. Libere a vaga na sua conta 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. A loja do PrestaShop não sabe que você está conectado ao back office, então a forma de pagamento também fica oculta para você: é possível 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: os pagamentos já feitos são mantidos, e capturas e reembolsos 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 chave ser inserida, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo 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á ativado, se o modo atual tem o seu token de API (Live API token, ou Test API token no modo de teste) e se a moeda do carrinho é uma das Account currencies. A página de configurações exibe um aviso quando o token está ausente ou a moeda da loja não é permitida. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O cliente viu «We could not confirm your payment»: a Helcim não respondeu, então o cartão pode ter sido cobrado. Veja o campo Log: o erro indica o carrinho e a fatura da Helcim. Verifique essa fatura na Helcim antes de cobrar o cliente novamente. Uma nova tentativa em até 5 minutos retorna o resultado original e não cobra duas vezes.
Os clientes veem «This payment method is temporarily unavailable»: o token de API do modo atual está vazio ou foi recusado pela Helcim. O log orienta a verificar o token e as suas permissões. Certifique-se de que o acesso à API tem o direito de processamento de transações.
Pagamento recusado por um motivo da Helcim: a Helcim rejeitou a requisição, por exemplo por causa do cartão ou dos dados de cobrança. O log tem os detalhes.
O cliente viu «Your payment was received, but the order could not be completed»: a Helcim aprovou o pagamento, mas o PrestaShop não conseguiu criar o pedido (por exemplo, porque o módulo estava desativado). O log indica o motivo. Quando o cliente enviar novamente o mesmo carrinho, o pedido é criado a partir do pagamento aprovado, sem uma segunda cobrança.
Pedido em Helcim payment on hold: leia as notas no bloco da Helcim. A resposta da Helcim não correspondeu ao carrinho (falha na verificação da resposta). Verifique a transação na Helcim e, depois, atenda o pedido ou reembolse o pagamento.
Captura não é possível: o valor a capturar deve ser maior que 0 e não superior ao valor pré-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 integralmente. 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.
Pagamentos de teste: o modo de teste envia pagamentos, capturas e reembolsos para a sua conta de teste na Helcim. Os pedidos mantêm o modo em que foram pagos, então trocar o modo depois não move as capturas e os reembolsos deles para a outra conta.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Helcim 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 ativado, as configurações do gateway e o registro são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos da Helcim e os status de pedido Helcim payment authorized e Helcim payment on hold sempre são mantidos, portanto os pedidos pagos antes ainda podem ser capturados e reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
A Helcim é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Helcim.