VibeFox Cardcom for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin se recusa a ser ativado sem ele.
PHP: 8.0 ou superior.
HTTPS: o seu site deve ser acessível pela internet por HTTPS, para que a Cardcom possa enviar a notificação de pagamento.
Moeda: a moeda do pedido deve ser ILS, USD, EUR ou GBP. Para qualquer outra moeda, o método de pagamento fica oculto na finalização de compra.
Conta Cardcom: para pagamentos reais, você precisa de uma conta de comerciante da Cardcom com número de terminal, nome de usuário da API e senha da API. Os pagamentos precisam apenas do número de terminal e do nome de usuário da API. A senha da API é usada somente para reembolsos feitos pelo WooCommerce. O modo de teste funciona sem uma conta Cardcom.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_cardcom_payment_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Cardcom > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Ative Enable/Disable, mantenha Test Mode ativado e faça um pedido de teste com o cartão 4580 0000 0000 0000, qualquer data de validade futura, CVV 123.
6. Para pagamentos reais, desmarque Test Mode e informe o Terminal Number, o API Username e a API Password recebidos da Cardcom.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Cardcom. Acima dos campos, a página mostra Test mode is on. enquanto o modo de teste estiver ativado. No modo de produção, ela avisa quando o número do terminal ou o nome de usuário da API estão ausentes (a Cardcom fica então oculta na finalização de compra) e lembra que, sem a senha da API, reembolsos pelo WooCommerce não são possíveis. Ela também avisa quando a moeda da loja não é suportada. Ao salvar o modo de produção sem o número do terminal ou o nome de usuário da API, uma mensagem de erro informa que o gateway continua oculto na finalização de compra até que sejam preenchidos.
Geral
Enable/Disable: Enable Cardcom Payment Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Credit Card (Cardcom).
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit card via Cardcom.
Modo de teste
O modo de teste usa o terminal de teste público da Cardcom 1000 (usuário da API CardTest1994). Nenhum dinheiro real é cobrado e não é preciso ter uma conta Cardcom. Cartão de teste: 4580 0000 0000 0000, qualquer data de validade futura, CVV 123. No modo de teste, a finalização de compra também mostra uma linha com esse cartão de teste.
Test Mode: Enable test mode (terminal 1000, no real money). Padrão: ativado. Desmarque para aceitar pagamentos reais com as credenciais de produção abaixo. Os reembolsos são sempre enviados com as credenciais do modo em que o pedido foi pago.
Credenciais de produção
O número do terminal, o nome de usuário da API e a senha da API são fornecidos pela Cardcom com a sua conta de comerciante: no painel da Cardcom, em configurações de API, ou pelo suporte da Cardcom. Esses campos são usados somente no modo de produção.
Terminal Number: o número do seu terminal Cardcom. Deve conter apenas dígitos. Se você informar outra coisa, um erro é mostrado e o valor anterior é mantido.
API Username: o nome de usuário da API Cardcom (ApiName) para este terminal. Espaços são removidos ao salvar.
API Password: a sua senha da API Cardcom. Ela é necessária apenas para reembolsos feitos pelo WooCommerce e é armazenada exatamente como digitada.
Página de pagamento
A Cardcom envia as notificações de pagamento (IndicatorUrl) para o endereço exibido nesta seção. Ele tem a forma https://your-site/wc-api/cardcom_p_callback/. O endereço é enviado à Cardcom automaticamente em cada pagamento, junto com o ID do pedido, então não há nada para configurar na Cardcom. Ele precisa ser acessível pela internet.
Operation: o que a Cardcom faz na página de pagamento.
Max Installments: o número máximo de parcelas que o cliente pode escolher na página da Cardcom, de 1 a 36. 1 significa sem parcelamento. Padrão: 1.
Success Order Status: o status do pedido após um pagamento confirmado. O status é definido de imediato, sem uma segunda mudança de status.
Avançado
Debug log: Log API requests and notifications grava em WooCommerce > Status > Logs, origem wcp_cardcom_payment_gateway. Erros são sempre registrados. Credenciais, tokens de cartão e dados do titular do cartão nunca são gravados. Padrão: desativado.
Delete on Uninstall: Delete all plugin data when uninstalling. Quando ativado, excluir o plugin remove permanentemente as configurações, os dados da Cardcom armazenados nos pedidos e os logs. Os pedidos em si são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Credit Card (Cardcom)) e faz o pedido. O plugin cria uma página de pagamento da Cardcom para o total do pedido na moeda do pedido e envia o cliente para lá. A página abre em hebraico quando o idioma do site é o hebraico; caso contrário, abre em inglês. Os itens do pedido são enviados à Cardcom como nome do produto. O cliente digita os dados do cartão e, se o parcelamento for permitido, escolhe o número de parcelas.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Cardcom confirma. A Cardcom chama o endereço de notificação, e o plugin extrai dessa chamada apenas o código da página de pagamento. Ele verifica se esse código foi emitido pela sua loja para esse pedido e então pede à Cardcom, de servidor para servidor, o resultado real. Se a notificação atrasar, a mesma verificação é feita quando o cliente chega à página de pedido recebido.
Se o pagamento não for concluído, a Cardcom envia o cliente de volta à finalização de compra (ou à página Pay for order), que mostra The card payment was not completed. Please try again or choose a different payment method. Um pagamento recusado confirmado pela Cardcom marca o pedido como Falhou. O cliente pode pagar novamente um pedido não pago, por exemplo pela página Pay for order. Um pagamento feito em uma página de pagamento mais antiga do mesmo pedido continua sendo reconhecido. Se o cliente mudou para outro método de pagamento, mas pagou na página da Cardcom, o pagamento é registrado e o método de pagamento volta a ser a Cardcom.
Se a Cardcom não conseguir abrir a página de pagamento, o cliente vê uma mensagem curta, por exemplo Could not connect to Cardcom. Please try again in a moment., ou que a Cardcom não pôde abrir a página de pagamento, com o código da Cardcom, e pode escolher outro método de pagamento.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).
O plugin aceita pagamentos com cartão somente na página da Cardcom. Não há cartões salvos nem pagamentos com um clique, assinaturas, cobrança de tokens armazenados, configurações de fatura ou recibo da Cardcom, Bit, Apple Pay, Google Pay ou PayPal via Cardcom, modo iframe nem acordos de captura posterior. Páginas de pagamento abandonadas não são verificadas automaticamente.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Cardcom e ainda não pagou, ou a Cardcom ainda não confirmou o pagamento.
Processing, Completed or On Hold: o pagamento foi confirmado. O status segue Success Order Status. A nota do pedido mostra a transação da Cardcom e, quando a Cardcom informa, os últimos quatro dígitos do cartão, o número da fatura e o número de parcelas. Pagamentos de teste são marcados com Test mode — no real money was charged. O ID da transação do pedido é o número da operação na Cardcom.
On hold after payment: a Cardcom confirmou um pagamento que não corresponde ao pedido, por exemplo porque o total do pedido foi alterado depois que a página de pagamento foi aberta, ou porque foi cobrado um valor ou uma moeda diferentes. A nota do pedido explica. Compare o pagamento no painel da Cardcom com o pedido e, depois, atenda o pedido ou reembolse o pagamento.
Failed: a Cardcom recusou o pagamento. A nota do pedido mostra o código de resposta da Cardcom. Uma recusa em uma página de pagamento mais antiga não invalida uma nova tentativa, e uma recusa tardia nunca altera um pedido pago.
Se chegar um segundo pagamento bem-sucedido para um pedido que já está pago (por exemplo, o cliente pagou em duas abas do navegador), o pedido não é alterado novamente. Uma nota avisa que o cliente pode ter sido cobrado duas vezes e pede que você faça o reembolso no painel da Cardcom.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit Card (Cardcom) (o botão mostra o título do método de pagamento). São compatíveis reembolsos totais e parciais, e vários reembolsos parciais podem ser feitos para um mesmo pedido. O reembolso é enviado com as credenciais do modo em que o pedido foi pago: pedidos de teste são reembolsados no terminal de teste da Cardcom, mesmo depois que você mudou para o modo de produção, e pedidos reais sempre usam as suas credenciais de produção. Reembolsos reais precisam de API Username e API Password. Se a Cardcom não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido, com a transação de reembolso da Cardcom e o motivo.
Reembolsos feitos no painel da Cardcom não são informados de volta à loja. Se necessário, crie um reembolso manual no WooCommerce, sem usar o botão Refund via do gateway.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Cardcom. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar 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 em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Cardcom não é mostrada 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. Gerentes da loja logados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente automaticamente, em segundo plano.
Solução de problemas
A Cardcom não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se a moeda do pedido é ILS, USD, EUR ou GBP. No modo de produção, verifique se Terminal Number e API Username estão preenchidos. A página de configurações mostra um aviso quando algo está faltando.
O pagamento foi feito, mas o pedido continua com o status Pending payment: a Cardcom não conseguiu acessar o seu site, por exemplo por causa do modo de manutenção, de um firewall, de proteção por senha ou de um site de desenvolvimento local. O endereço de notificação precisa ser acessível pela internet por HTTPS. O pedido também é confirmado quando o cliente volta à página de pedido recebido. Ative o Debug log e verifique WooCommerce > Status > Logs, origem wcp_cardcom_payment_gateway.
A notificação responde Missing or invalid lowprofilecode ou Unknown lowprofilecode for this order: a chamada não trouxe um código de página de pagamento emitido pela sua loja para esse pedido. O pedido não é alterado.
A notificação responde Gateway not configured ou Indicator check failed: as credenciais do modo em que a página de pagamento foi criada estão ausentes, ou a Cardcom não pôde ser acessada para a verificação. O pedido não é alterado e é verificado novamente quando o cliente volta à loja.
A notificação responde ReturnValue mismatch ou Terminal mismatch: a Cardcom informou um pagamento de outro pedido ou de outro terminal. O pedido não é alterado. Confira se Terminal Number é o terminal da sua conta.
O cliente vê Payment error: this currency is not supported by Cardcom.: a moeda do pedido não é ILS, USD, EUR ou GBP.
O cliente vê Card payment is temporarily unavailable. Please choose another payment method.: o modo de produção está ativado, mas o número do terminal ou o nome de usuário da API está ausente.
O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou ative o Debug log e consulte o log. Problemas de conexão e códigos de erro da Cardcom são registrados ali.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido. Atenda o pedido ou reembolse o pagamento.
O reembolso falha com API username and API password are required for refunds: informe a API Password (e o API Username) nas configurações e tente de novo.
O reembolso falha com Could not connect to Cardcom: verifique o painel da Cardcom antes de tentar de novo, porque o reembolso pode ou não ter sido feito.
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 uma vaga 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 no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Para desenvolvedores, o readme lista o filtro cardcom_p_supported_currencies, que amplia a lista de moedas (adicione apenas moedas habilitadas no seu terminal Cardcom).
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway, os dados da Cardcom armazenados nos pedidos e os logs são removidos somente se Delete on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Cardcom é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Cardcom.