VibeFox Cardcom for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

HTTPS: sua loja precisa estar acessível pela internet por HTTPS, para que a Cardcom possa enviar a notificação de pagamento.

Moeda: a moeda do carrinho deve ser ILS, USD, EUR ou GBP. Para qualquer outra moeda, o método de pagamento fica oculto no checkout.

Conta na 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 apenas para reembolsos feitos pelo PrestaShop. O modo de teste funciona sem uma conta na Cardcom.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 VibeFox Cardcom Payment Gateway na lista de módulos e clique em Configure.

3. Insira 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. Ative Enable/Disable, deixe Test Mode ativado e clique em Save. Faça um pedido de teste com o cartão 4580 0000 0000 0000, qualquer data de validade futura e CVV 123.

5. Para pagamentos reais, desative Test Mode, insira o Terminal Number, o API Username e a API Password que você recebeu da Cardcom e clique em Save.

Ao ser instalado, o módulo cria o status de pedido Cardcom 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 ficam na página do módulo: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página exibe um aviso enquanto o modo de teste estiver ativado. No modo de produção, ela avisa quando o número de terminal ou o nome de usuário da API está faltando (nesse caso a Cardcom fica oculta no checkout), quando os campos de produção contêm o terminal de teste público 1000 / CardTest1994 (a Cardcom também fica oculta no checkout, porque nenhum dinheiro real seria cobrado), e lembra que, sem a senha da API, não são possíveis reembolsos pelo PrestaShop. Ela também avisa quando a moeda padrão da sua loja não é compatível. Ao salvar o modo de produção com credenciais ausentes ou de teste, uma mensagem de erro informa que o gateway continua oculto no checkout até que você insira seu próprio número de terminal e nome de usuário da API.

Cardcom

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ê no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit Card (Cardcom). Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. 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 é necessária uma conta na Cardcom. Cartão de teste: 4580 0000 0000 0000, qualquer data de validade futura, CVV 123. No modo de teste, o checkout também exibe uma linha com esse cartão de teste.

Test Mode: ativa o modo de teste (terminal 1000, sem dinheiro real). Padrão: ativado. Desative-o 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 de terminal, o nome de usuário da API e a senha da API são fornecidos pela Cardcom com 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 na Cardcom. Ele deve conter apenas dígitos. Se você digitar outra coisa, um erro é exibido e o valor anterior é mantido.

API Username: seu nome de usuário da API na Cardcom (ApiName) para este terminal. Os espaços são removidos ao salvar.

API Password: sua senha da API na Cardcom. Ela é necessária apenas para reembolsos feitos pelo PrestaShop. A senha salva nunca é exibida novamente: o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.

Clear the saved API password: marque a caixa e clique em Save para remover a senha. Um campo vazio mantém o valor salvo.

Página de pagamento

Notification URL: a Cardcom envia as notificações de pagamento (IndicatorUrl) para este endereço. Com URLs amigáveis ele tem esta aparência: https://your-shop/module/wcp_cardcom_payment_gateway/webhook, possivelmente com um código de idioma como /en/. O endereço é informado automaticamente à Cardcom em cada pagamento, junto com o ID do carrinho, então não há nada para configurar na Cardcom. Ele precisa ser acessível pela internet por HTTPS.

Operation: o que a Cardcom faz na página de pagamento.

Max Installments: o número máximo de parcelas (pagamentos) 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 pedido é criado diretamente neste status.

Pagamentos que não correspondem ao pedido sempre vão para Cardcom payment on hold.

Avançado

Debug log: registra as requisições à API e as notificações em logs/cardcom_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados. Credenciais, tokens de cartão e dados do titular nunca são gravados. Padrão: desativado.

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

Delete on Uninstall: quando ativado, desinstalar o módulo remove permanentemente as configurações e os logs. Pedidos, transações e reembolsos da Cardcom e o status de pedido Cardcom payment on hold são sempre mantidos, para que pedidos antigos possam ser reembolsados após uma reinstalação. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Credit Card (Cardcom)) e vê a nota You will be redirected to the secure Cardcom payment page. Após a confirmação, o módulo cria uma página de pagamento da Cardcom para o total do carrinho na moeda do carrinho e envia o cliente para lá. Nesse ponto ainda não existe pedido. A página abre em hebraico quando o idioma do cliente é o hebraico, e em inglês nos demais casos. Os produtos do carrinho são informados à 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.

Após o pagamento, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Cardcom confirma. A Cardcom chama o endereço de notificação, e o módulo extrai dessa chamada apenas o código da página de pagamento. Ele verifica se esse código foi emitido pela sua loja para aquele carrinho e então pede à Cardcom, de servidor para servidor, o resultado real. Se a notificação chegar atrasada, a mesma verificação é feita quando o cliente voltar. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with Cardcom has been received. Se a Cardcom ainda não tiver confirmado o pagamento quando o cliente voltar, uma página de Payment confirmation mostra Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. com um botão Check again; a notificação cria o pedido assim que chegar.

Se o pagamento não for concluído ou a Cardcom o recusar, o cliente volta ao checkout com The card payment was not completed. Please try again or choose a different payment method. Nenhum pedido é criado e o carrinho é mantido. O cliente pode tentar de novo: cada tentativa recebe uma nova página de pagamento da Cardcom. Um pagamento feito em uma página de pagamento anterior do mesmo carrinho continua sendo reconhecido, e uma recusa em uma página antiga não afeta uma nova tentativa.

Se a Cardcom não conseguir abrir a página de pagamento, o cliente permanece no checkout com uma mensagem curta, por exemplo Could not connect to Cardcom. Please try again in a moment., ou com a informação de que a Cardcom não pôde abrir a página de pagamento, junto com o código da Cardcom, e pode escolher outro método de pagamento.

A notificação funciona enquanto a loja estiver em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

O módulo aceita pagamentos com cartão somente na página da Cardcom. Não há cartões salvos nem pagamentos com um clique, nem assinaturas, não cobra tokens armazenados, não tem configurações de fatura ou recibo da Cardcom, não oferece Bit, Apple Pay, Google Pay ou PayPal pela Cardcom, nem modo iframe ou transações com captura posterior.

Pedidos e reembolsos

Status dos pedidos

No order yet: o cliente foi enviado à Cardcom e não pagou, o pagamento foi recusado ou a Cardcom ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted, Delivered or Cardcom payment on hold: o pagamento foi confirmado. O status segue Success Order Status. O pagamento é registrado com o número da operação (deal) da Cardcom como ID da transação. Uma mensagem privada do pedido mostra a transação da Cardcom e, quando a Cardcom informa esses dados, os quatro últimos dígitos do cartão, o número da fatura e a quantidade de parcelas. Pagamentos de teste são marcados com Test mode — no real money was charged.

Cardcom payment on hold after payment: a Cardcom confirmou um pagamento que não corresponde ao pedido, por exemplo porque o carrinho foi alterado depois que a página de pagamento foi aberta, ou porque foi cobrado outro valor ou outra moeda. A mensagem explica isso, e o bloco da Cardcom mostra o pedido em Needs review. O pagamento é registrado pelo valor cobrado pela Cardcom quando a moeda coincide com a do pedido. Compare o pagamento no painel da Cardcom com o pedido e depois atenda o pedido ou reembolse o pagamento.

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

Se chegar um segundo pagamento aprovado para um carrinho que já tem pedido (por exemplo, se o cliente pagou em duas abas do navegador), o pedido não é alterado. Uma mensagem avisa que o cliente pode ter sido cobrado duas vezes e pede que você faça o reembolso no painel da Cardcom.

Bloco de pagamento da Cardcom

A página do pedido mostra um bloco Cardcom payment com a transação, o código da página de pagamento, o status, o cartão, as parcelas, a fatura, o token do cartão (com Charge + Save token), o valor cobrado, o total do pedido e o valor reembolsado, um selo Test mode para pagamentos de teste e o histórico de reembolsos.

Reembolsos

No bloco Cardcom payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Cardcom. Confirme a pergunta Refund this amount through Cardcom? This cannot be undone. Reembolsos totais e parciais são suportados, e vários reembolsos parciais podem ser feitos para um mesmo pedido. Você precisa da permissão para editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são feitos no valor e na moeda cobrados pela Cardcom, então, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente efetivamente pagou, e não o total do 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 suas credenciais de produção. Reembolsos de produção precisam de API Username e API Password. Se a Cardcom não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às mensagens do pedido, com a transação de reembolso da Cardcom e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.

O módulo não gera notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Cardcom. Reembolsos feitos no painel da Cardcom não são informados à loja.

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 Cardcom Payment Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Cardcom Payment 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-cardcom e o link Manage licenses and domains in your account, que abre sua conta em vibefox.net. Apenas 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 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 único 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 vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Cardcom não é exibida aos clientes no checkout. Se um pagamento for iniciado mesmo assim, 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 o método de pagamento também fica oculto para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

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 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 Cardcom não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se a moeda do carrinho é ILS, USD, EUR ou GBP. No modo de produção, verifique se Terminal Number e API Username estão preenchidos com suas próprias credenciais, e não com o terminal de teste 1000 / CardTest1994. A página de configurações exibe um aviso quando algo está faltando. 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 pagamento foi feito, mas nenhum pedido foi criado: a Cardcom não conseguiu acessar sua loja, por exemplo por causa de um firewall, de uma 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 é criado quando o cliente volta à loja depois de pagar. Ative o Debug log e veja o campo Log na página do módulo.

A notificação responde Missing or invalid lowprofilecode or Unknown lowprofilecode for this order: a chamada não trouxe um código de página de pagamento emitido pela sua loja para aquele carrinho. Nada é alterado.

A notificação responde Gateway not configured or Indicator check failed: faltam as credenciais do modo em que a página de pagamento foi criada, ou a Cardcom não pôde ser contactada para a verificação. Nada é alterado; o pagamento é verificado novamente quando o cliente volta à loja.

A notificação responde Busy, retry: o carrinho estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). Ative o Debug log para ver o motivo.

A notificação responde ReturnValue mismatch or Terminal mismatch: a Cardcom informou um pagamento de outro carrinho ou de outro terminal. Nada é alterado. Verifique se o Terminal Number é o terminal da sua conta.

O cliente vê Payment error: this currency is not supported by Cardcom.: a moeda do carrinho não é ILS, USD, EUR nem 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 de terminal ou o nome de usuário da API está faltando, ou os campos de produção contêm o terminal de teste público.

O cliente vê um erro ao escolher a Cardcom: ative o Debug log e veja o campo Log. Problemas de conexão e códigos de erro da Cardcom são registrados ali.

O pedido está em Cardcom payment on hold after payment: leia a mensagem do pedido ou o item Needs review no bloco Cardcom payment. O valor ou a moeda pagos não correspondiam ao 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 novamente.

O reembolso falha com Could not connect to Cardcom: verifique o painel da Cardcom antes de tentar novamente, porque o reembolso pode ou não ter sido feito.

Para desenvolvedores, o README lista o hook actionCardcomSupportedCurrencies, que amplia a lista de moedas (adicione apenas moedas ativadas no seu terminal da Cardcom), e o actionCardcomLowProfileParams, que altera os parâmetros da página de pagamento.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Cardcom Payment Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete on Uninstall estiver ativado, as configurações e os logs 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 Cardcom e o status de pedido Cardcom payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados após uma reinstalação. Pedidos existentes mantêm suas mensagens de pagamento e IDs de transação.

A Cardcom é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Cardcom nem endossado por ela.