VibeFox Helcim for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin não pode ser ativado.

PHP: 8.0 ou superior.

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 via HTTPS. Eles nunca são armazenados nem registrados em log, 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 Helcim: uma conta de comerciante na Helcim no Canadá ou nos Estados Unidos e um token de API com direitos de processamento de transações (consulte Configuração). A Helcim processa CAD e USD. Uma conta de teste (desenvolvedor) da Helcim é opcional para a realização de testes.

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, acesse Plugins > Add New > Upload Plugin, selecione o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_helcim_gateway para /wp-content/plugins/ via FTP.

2. Clique em Activate.

3. Na Helcim, acesse All Tools > Integrations > API Access Configuration, crie um acesso de API com direitos de processamento de transações (compras, pré-autorizações, capturas, reembolsos) e copie o seu token.

4. Abra as configurações: WooCommerce > Settings > Payments > Helcim > Manage, ou clique em Settings sob o nome do plugin na página Plugins.

5. Insira a sua chave de licença VibeFox no bloco de licença na parte superior da página e clique em Activate.

6. Cole o token em Live API token, e o token da sua conta de teste da Helcim em Test API token se você tiver uma.

7. Escolha o Transaction type e as Account currencies, ative Enable / Disable e salve. Para testar primeiro, ative o Test mode e pague com a sua conta de teste; depois desative-o.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Helcim. Acima dos campos, a página avisa quando a moeda da loja não é uma das Account currencies e, enquanto o gateway estiver ativado, quando o token de API do modo atual estiver vazio. Em ambos os casos, o gateway fica oculto na finalização de compra. Na lista de formas de pagamento, o gateway fica marcado como necessitando de configuração até que o modo atual tenha um token.

Enable / Disable: Enable Helcim Gateway ativa ou desativa a forma de pagamento. Padrão: desativado.

Title: o título da forma de pagamento exibido na finalização de compra. Padrão: Credit card (Helcim).

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, acesse All Tools > Integrations > API Access Configuration, crie um acesso de API e copie o seu token. Conceda a ele direitos 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 da Helcim.

Live API token: o token de API da sua conta Helcim de produção. Usado quando o modo de teste está desativado.

Test mode: Use the Test API token (Helcim test account). Pagamentos, capturas e reembolsos vão para a sua conta de teste da Helcim, e os clientes visualizam um aviso de modo de teste. Reembolsos e capturas de um pedido sempre usam o token do modo no qual o pedido foi pago. Padrão: desativado.

Test API token: o token de API da sua conta de teste (desenvolvedor) da Helcim. Usado quando o modo de teste está ativado.

Pagamento

Transaction type: como o cartão é cobrado.

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

Avançado

Debug log: Log API requests and responses em WooCommerce > Status > Logs, fonte wcp_helcim_gateway. Os números de cartão são reduzidos para os últimos 4 dígitos. CVC, validade, tokens, nomes, endereços, e-mails e endereços IP nunca são registrados no log. Padrão: desativado.

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. Padrão: desativado.

Finalização de compra

O cliente escolhe a forma de pagamento (por padrão Credit card (Helcim)) e insere Card Number, Expiry (MM/YY), CVC e Cardholder Name na sua finalização de compra. Ícones da Visa, Mastercard, American Express e Discover são exibidos ao lado do título. No modo de teste, o formulário exibe TEST MODE — payments go to a Helcim test account, no real charges are made. Antes do envio, o plugin verifica o dígito verificador do número do cartão, se a data de validade é válida e não expirou, se o CVC possui 3 ou 4 dígitos e se o nome está preenchido.

Quando o pedido é finalizado, seu servidor envia o cartão para a Helcim como uma compra ou pré-autorização referente ao total do pedido na moeda do pedido. O endereço de faturamento, telefone e e-mail são enviados para verificação de endereço. O pagamento é exibido na Helcim com um número de fatura composto pelo número do pedido e um código curto. A Helcim responde na mesma requisição. O pedido só é marcado como pago após a Helcim aprovar a transação e o valor e a moeda aprovados corresponderem ao pedido. Em seguida, o cliente é direcionado para a página de pedido recebido.

Apenas uma tentativa de pagamento por pedido é executada por vez, e um pedido que já está pago nunca é cobrado novamente. Cada tentativa utiliza uma chave de idempotência. Se a Helcim não responder, o pedido permanece como Pagamento pendente, e uma nova tentativa em até 5 minutos retorna o resultado original da Helcim em vez de cobrar o cartão duas vezes.

Mensagens que o cliente pode visualizar: Your card was declined. Please check the card details or use another card. quando a Helcim recusar; Payment failed: com o motivo da Helcim para outras requisições rejeitadas; 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 responder; This payment method is temporarily unavailable. Please choose another payment method. quando o token de API estiver ausente ou for rejeitado; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. em caso de envio duplicado. Detalhes técnicos são registrados nas notas do pedido e no log.

A forma de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra (com os mesmos campos de cartão) e na página Pay for order. Ela é compatível com o Armazenamento de Pedidos de Alto Desempenho (HPOS) do WooCommerce.

O plugin não utiliza HelcimPay.js nem Helcim.js, de modo que os dados do cartão passam pelo seu servidor. Não possui cartões salvos, assinaturas, pagamentos bancários ou ACH, Apple Pay, Google Pay ou 3-D Secure, e não recebe webhooks da Helcim.

Pedidos e reembolsos

Status do pedido

Pending payment: o pagamento foi recusado ou ainda não foi confirmado. Se a Helcim não respondeu, a nota do pedido solicita que você verifique a fatura na Helcim antes de cobrar o cliente novamente.

Processing: uma compra foi aprovada ou uma pré-autorização foi capturada. Pedidos contendo apenas produtos virtuais para download tornam-se Concluído, o padrão do WooCommerce. A nota do pedido exibe o ID da transação, código de aprovação, tipo de cartão, os últimos 4 dígitos e o modo. O ID da transação é o ID da transação da Helcim.

On hold (pre-authorization): os fundos estão apenas retidos. Capture-os com a ação de pedido ou libere-os com um reembolso total.

On hold after payment: a Helcim aprovou uma transação, mas o valor, a moeda ou o ID da transação na resposta não coincidem com o pedido. A nota informa Helcim response verification FAILED. Verifique a transação na Helcim antes de atender ao pedido.

Captura

Abra o pedido (status Aguardando), escolha a ação de pedido Capture Helcim pre-authorization e clique em Update. O valor total atual do pedido, subtraídos os reembolsos, é capturado. Ele pode ser inferior ao valor autorizado, mas não superior. A captura utiliza o token do modo no qual o pedido foi pago. Após uma captura bem-sucedida, o pedido passa para Processando e o ID da transação é atualizado para o da transação de captura. Se a captura falhar, o motivo será exibido e adicionado às notas do pedido.

Reembolsos

Abra o pedido, clique em Refund, insira o valor e clique em Refund via Credit card (Helcim) (o botão exibe o seu Title). São suportados reembolsos totais e parciais de uma compra ou de uma pré-autorização capturada. Uma pré-autorização não capturada só pode ser reembolsada integralmente: a retenção é liberada e o cliente não é cobrado. O reembolso é enviado no modo em que o pedido foi pago, portanto o token desse modo deve estar definido. Ele só é contabilizado após a aprovação da Helcim. Se a Helcim o recusar, o WooCommerce exibirá o erro e nenhum reembolso será registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID da transação de reembolso da Helcim. Uma nova tentativa após tempo limite não gera reembolso duplo.

O plugin não recebe webhooks da Helcim. Capturas, reembolsos e anulações feitos no painel da Helcim não são refletidos no WooCommerce; portanto, execute-os a partir do WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica na parte superior de WooCommerce > Settings > Payments > Helcim. Cole a chave em License key e clique em Activate. O bloco exibe o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para consultar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera o seu espaço de domínio. Libere o espaço na sua conta no 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 verá This payment method is not available. Please choose another one. Gerentes da loja conectados ainda veem a forma de pagamento, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete é exibido na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: capturas e reembolsos continuam funcionando.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte necessitam de renovação. O status é verificado novamente de forma automática em segundo plano.

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 possui o respectivo token de API (Live API token, ou Test API token no modo de teste) e se a moeda do carrinho é uma das Account currencies. Na página Pay for order, considera-se a moeda do pedido. A página de configurações exibe um aviso em ambos os casos.

A Helcim não respondeu e o pedido continua como Pagamento pendente: o cartão pode ter sido cobrado. Leia a nota do pedido e verifique a fatura na Helcim antes de cobrar o cliente novamente. Uma nova tentativa em até 5 minutos retorna o resultado original e não realiza cobrança dupla.

Os clientes visualizam This payment method is temporarily unavailable: o token de API do modo atual está vazio ou foi rejeitado pela Helcim. A nota do pedido orienta a verificar o token e as suas permissões. Certifique-se de que o acesso de API possui direitos de processamento de transações.

O pagamento falhou com um motivo da Helcim: a Helcim rejeitou a requisição, por exemplo devido ao cartão ou aos dados de faturamento. A nota do pedido contém os detalhes.

O pedido está Aguardando após o pagamento: leia a nota do pedido. O pedido foi pré-autorizado e aguarda a captura, ou a resposta da Helcim não coincidiu com o pedido (falha na verificação da resposta).

A captura não é possível: o valor a ser capturado deve ser maior que 0 e não exceder o valor autorizado, e o token do modo no qual o pedido foi pago deve estar definido.

O reembolso falha: leia a mensagem. Uma pré-autorização não capturada só pode ser reembolsada integralmente. Uma mensagem sobre o modo significa que o token do modo no qual 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 da Helcim. Os pedidos mantêm o modo em que foram pagos; portanto, alternar o modo mais tarde não transfere as suas capturas e reembolsos para a outra conta.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere um espaço na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continuará funcionando com o último status conhecido.

Para desenvolvedores: o filtro wc_hlg_supported_currencies altera a lista de moedas, e wc_hlg_card_brands altera os ícones de cartão na finalização de compra.

Desinstalação

Ao desativar o plugin, todos os dados são mantidos. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway, as opções próprias do plugin e os logs são removidos apenas se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os dados de pedidos fazem parte do histórico de pedidos e nunca são excluídos. Pedidos existentes mantêm as suas notas de pagamento e IDs de transação.

Helcim é uma marca comercial de seu respectivo titular. Este plugin não é afiliado à Helcim nem endossado por ela.