VibeFox Kushki 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.
Moeda: USD (Equador) ou COP (Colômbia). Para carrinhos em outras moedas, o método de pagamento fica oculto na finalização de compra.
HTTPS: a Kushki exige que a finalização de compra seja servida por HTTPS no modo de produção.
Conta Kushki: você precisa dos Merchant IDs públicos e privados da sua conta de teste (UAT) da Kushki e da sua conta de produção. Eles estão no Kushki Console, em Developers > Credentials. Para o webhook opcional, você também precisa da chave de assinatura do webhook de cada conta (veja Configuração).
VibeFox license key: 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 Kushki Payment na lista de módulos e clique em Configure.
3. Informe 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. Informe os Merchant IDs públicos e privados de teste e mantenha Test mode ativado. Opcionalmente, configure o webhook no Kushki Console e cole a sua chave de assinatura (veja Configuração).
5. Ative Enable / Disable, clique em Save e faça um pedido de teste. Quando estiver pronto, informe os Merchant IDs de produção (e a assinatura do webhook de produção) e desative Test mode.
Na instalação, o módulo cria o status de pedido Kushki payment on hold. O PrestaShop atribui um novo módulo de pagamento às moedas, países e grupos de clientes da sua loja. Em Payment > Preferences, confira se o módulo está permitido para USD ou COP e para Equador ou Colômbia.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Kushki Payment > 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 o método de pagamento está ativado, mas faltam os Merchant IDs do modo atual (nesse caso o método de pagamento fica oculto na finalização de compra), quando a moeda padrão da sua loja não é USD nem COP, quando o modo de produção é usado sem HTTPS e quando o modo atual não tem assinatura de webhook. Enquanto o modo de teste estiver ativado, ela mostra Modo de teste ativado: o ambiente de teste da Kushki é usado, nenhum dinheiro real é cobrado. Se você salvar com o método de pagamento ativado, mas sem os Merchant IDs do modo atual, as configurações são salvas e uma mensagem lembra você de informá-los. Espaços em volta dos IDs são removidos ao salvar.
Kushki
Enable / Disable: Enable Kushki card payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit / debit card (Kushki). Obrigatório.
Description: o texto exibido acima do formulário de cartão na finalização de compra. Padrão: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.
Credenciais de API
Copie os Merchant IDs públicos e privados do Kushki Console (Developers > Credentials). As contas de teste (UAT) e de produção têm IDs diferentes. O modo de teste usa apenas os IDs de teste, e o modo de produção usa apenas os IDs de produção.
Test mode: usa o ambiente de teste (UAT) da Kushki: os Merchant IDs de teste, o formulário de cartão de teste e a API de teste juntos. Nenhum dinheiro real é cobrado, e um selo TEST MODE é exibido na finalização de compra. Padrão: ativado. Desative para receber pagamentos reais. Os reembolsos sempre vão para o ambiente em que o pagamento foi feito.
Test Public Merchant ID: o Merchant ID público da sua conta de teste da Kushki. Ele carrega o formulário de cartão.
Test Private Merchant ID: o Merchant ID privado da sua conta de teste da Kushki. Ele é usado no servidor para cobranças e reembolsos.
Live Public Merchant ID: o Merchant ID público da sua conta de produção da Kushki.
Live Private Merchant ID: o Merchant ID privado da sua conta de produção da Kushki. Mantenha-o em segredo.
Os Merchant IDs privados e as assinaturas de webhook salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo: deixe vazio para mantê-lo. Digite um novo valor somente se quiser alterá-lo.
Webhook (recomendado)
Os pagamentos são confirmados imediatamente pela resposta da API da Kushki, então o webhook não é obrigatório. Além disso, ele cria o pedido de um pagamento cuja resposta se perdeu (por exemplo, por timeout) e informa os cancelamentos e reembolsos feitos no Kushki Console. No Kushki Console (Webhooks), adicione a URL exibida em Webhook URL para pagamentos com cartão. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_kushki_payment/webhook, possivelmente com um código de idioma como /es/. Copie a URL exatamente como as configurações a mostram. Faça isso para a conta de teste e para a conta de produção.
O módulo trata estas notificações de cartão:
Test webhook signature: a chave de assinatura do webhook da conta de teste da Kushki (Console > Webhooks).
Live webhook signature: a chave de assinatura do webhook da conta de produção da Kushki.
Clear saved secrets: marque um Merchant ID privado ou uma assinatura de webhook e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Webhooks sem assinatura válida são rejeitados. Uma notificação precisa estar assinada com a chave do modo em que o pagamento foi feito, então uma notificação de teste nunca confirma um pagamento real. Sem chave de assinatura, todas as notificações de webhook são rejeitadas, mas os pagamentos continuam funcionando, porque são confirmados pela resposta da API.
Avançado
Debug log: grava as requisições e os webhooks da Kushki em logs/kushki_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados. Os logs nunca contêm Merchant IDs, tokens de cartão nem e-mails de clientes. Padrão: desativado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações e os logs. Os registros de pagamentos da Kushki (cobranças e reembolsos) e o status de pedido Kushki payment on hold sempre permanecem, para que pedidos antigos possam ser reembolsados depois de 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 / debit card (Kushki)). Logo abaixo aparece o formulário de cartão da Kushki, com o total do carrinho na moeda do carrinho. O cliente digita o cartão, escolhe as parcelas, se o formulário da Kushki as oferecer, e pressiona o botão de pagamento dentro do formulário da Kushki.
O botão Place order do PrestaShop continua visível, porque ele contém os termos de serviço. Se os termos já tiverem sido aceitos, o pagamento é enviado automaticamente após o botão de pagamento da Kushki. Caso contrário, o cliente vê Seu cartão foi aceito pela Kushki. Aceite os termos de serviço e pressione "Place order" para pagar. Se o cliente pressionar Place order sem usar o formulário da Kushki, a mensagem Informe os dados do seu cartão no formulário da Kushki e pressione o botão de pagamento dele. é exibida.
Em seguida, a sua loja cobra o cartão no servidor. O pedido só é marcado como pago depois que a Kushki confirma com um número de ticket. Então o pedido é criado, e o cliente vê a página padrão de confirmação do pedido com Seu pagamento com cartão foi recebido. Se a Kushki informar um valor ou uma moeda, eles são comparados com o carrinho. Um pedido em espera exibe Seu pagamento está em análise. Atualizaremos o seu pedido assim que a análise for concluída.
Se o cartão for recusado, nenhum pedido é criado e o cliente volta à etapa de pagamento com Seu pagamento foi recusado e o motivo informado pela Kushki, podendo tentar outro cartão. Em caso de problemas de rede, de chave ou de servidor, o cliente vê No momento não foi possível processar o pagamento. Tente novamente em instantes ou escolha outro método de pagamento. O motivo técnico é gravado no log. Um segundo clique enquanto um pagamento está sendo processado exibe Já há um pagamento em processamento para este pedido. Aguarde um momento e verifique o status do seu pedido.
Se a resposta da Kushki se perder (por exemplo, por timeout), o cliente vê a mensagem geral, mas a tentativa de cobrança é mantida. Quando o webhook assinado informa a cobrança aprovada, o pedido é criado. Um carrinho que já tem um pedido, ou uma cobrança aprovada cujo pedido ainda não foi criado, nunca é cobrado de novo: o cliente vê a confirmação desse pedido. Se o cliente pagar novamente antes de qualquer webhook chegar, isso é uma nova cobrança; uma aprovação tardia da primeira cobrança apenas acrescenta uma nota sobre uma possível cobrança duplicada.
O webhook funciona mesmo com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja. O 3-D Secure, as regras antifraude e as parcelas oferecidas são configurados no Kushki Console.
O módulo aceita apenas pagamentos com cartão em uma etapa. Não há reembolsos parciais, cartões salvos ou assinaturas, nem pagamentos em dinheiro, transferência bancária (PSE) ou com cartão de débito por redirecionamento, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente não pagou, o cartão foi recusado, ou a resposta da Kushki se perdeu e o webhook ainda não chegou. Existe apenas o carrinho.
Payment accepted: a Kushki confirmou a cobrança (pela resposta da API ou pelo webhook). O pagamento é registrado com a referência de transação da Kushki (ou o número do ticket) como ID da transação. Uma nota mostra o modo, o número do ticket da Kushki e a referência.
Kushki payment on hold: a Kushki devolveu um sucesso sem número de ticket, informou um valor ou uma moeda diferentes do carrinho, ou o carrinho foi alterado durante o pagamento. A nota explica. Confira a transação no Kushki Console e processe o pedido ou reembolse o pagamento. Uma aprovação assinada posterior, com número de ticket e valor correspondente, muda o pedido para Payment accepted.
Payment error: o webhook informou que a cobrança de um pedido em espera foi recusada.
Refunded: o pagamento foi reembolsado pelo módulo.
Se a Kushki informar outra cobrança aprovada para um pedido que já está pago, cancelado ou reembolsado, o pedido não é alterado. Uma nota pede que você verifique uma possível cobrança duplicada e a reembolse no Kushki Console. Um webhook do ambiente de teste para um pagamento de produção (ou o contrário) é ignorado com uma nota.
Bloco de pagamento da Kushki
A página do pedido mostra um bloco Kushki payment com o número do ticket, a referência da transação, o ambiente (com um selo Test para pagamentos de teste), o status da cobrança, o valor cobrado e o total do pedido, o formulário de reembolso, o histórico de reembolsos e as Kushki notes do pedido.
Reembolsos
A Kushki reembolsa a cobrança inteira, então só são possíveis reembolsos completos. No bloco Kushki payment, o valor cobrado pela Kushki já vem preenchido. Opcionalmente, informe um motivo e clique em Refund via Kushki, depois confirme a pergunta Reembolsar o pagamento inteiro pela Kushki? Esta ação não pode ser desfeita. Você precisa ter permissão para editar pedidos. Para qualquer outro valor, o módulo mostra A Kushki reembolsa apenas o pagamento inteiro. Informe o valor total cobrado junto com o valor, e nada é enviado. O reembolso é feito no valor e na moeda que a Kushki cobrou, então, em caso de divergência de valor, o cliente recebe de volta o que de fato foi cobrado, e não o total do pedido. Um pagamento pode ser reembolsado uma única vez.
O reembolso é enviado no modo em que o pagamento foi feito (teste ou produção), então o Merchant ID privado desse modo precisa estar informado. Se a Kushki não aceitar o reembolso, o bloco exibe Falha no reembolso da Kushki com o código e a mensagem da Kushki, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas com o ticket de reembolso da Kushki, e o pedido passa a Refunded. Os reembolsos exigem uma cobrança confirmada da Kushki com número de ticket.
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 Kushki. Os cancelamentos e reembolsos feitos no Kushki Console chegam pelo webhook e são adicionados às notas. O status do pedido não muda automaticamente.
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 Kushki Payment é o primeiro bloco de Modules > Module Manager > VibeFox Kushki Payment > Configure, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-kushki e o link Manage licenses and domains in your account, que abre a sua conta na 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 (inclui inglês e russo).
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 vibefox.net.
Sem uma chave ativa, a Kushki 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 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 pode 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á iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 informada, 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 Kushki não aparece na finalização de compra: confira se a licença está ativa, se Enable / Disable está ativado e se o modo atual tem os dois Merchant IDs: os IDs de teste no modo de teste, os IDs de produção no modo de produção. Confira se a moeda do carrinho é USD ou COP. Em Payment > Preferences, confira se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente. A página de configurações exibe um aviso quando os IDs estão faltando.
O pagamento foi concluído, mas nenhum pedido foi criado: a resposta da API da Kushki se perdeu, por exemplo por timeout. O webhook cria o pedido para esses pagamentos. No Kushki Console, confira se a URL do webhook é exatamente a mostrada em Webhook URL, para a conta do modo que você usa, e se a chave de assinatura dessa conta está no campo correspondente (Test webhook signature ou Live webhook signature). Uma cobrança aprovada sem o valor e a moeda pagos cria o pedido em Kushki payment on hold.
O webhook responde Webhook signature not configured: nenhuma das duas assinaturas de webhook está definida. Cole a chave de assinatura nas configurações.
O webhook responde Invalid signature: a chave de assinatura pertence a outra conta ou modo, ou a notificação foi alterada no caminho.
O webhook responde Order mismatch: a notificação não corresponde a uma cobrança deste carrinho (chave de tentativa ou transação incorreta). Nada é alterado.
O webhook responde Busy, retry later: o pedido estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Kushki pode enviar a notificação novamente. Os erros são sempre gravados no log.
A URL do webhook mostra apenas POST no navegador: isso é normal. A URL aceita apenas notificações da Kushki.
O formulário de cartão não carrega: o cliente vê Não foi possível carregar o formulário de cartão da Kushki. Recarregue a página ou escolha outro método de pagamento. Confira o Merchant ID público do modo atual.
O cliente vê Esta opção de pagamento não está disponível nesta loja. Pague com cartão.: uma opção de pagamento que não é cartão foi escolhida no formulário da Kushki. O módulo cobra apenas cartões.
O cliente vê um erro ao pagar: ative o Debug log e consulte o campo Log na página do módulo. Um Merchant ID privado incorreto ou ausente gera a mensagem geral de que o pagamento não pôde ser processado.
O cliente vê Seu pagamento foi recebido, mas o pedido não pôde ser concluído automaticamente: a Kushki aprovou a cobrança, mas o PrestaShop não conseguiu criar o pedido. O log mostra o motivo. A próxima tentativa de pagamento do mesmo carrinho cria o pedido sem uma nova cobrança.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito em modo de teste ou de produção, e o Merchant ID privado desse modo não está informado. Informe-o e tente novamente.
O reembolso não é oferecido, e aparece a mensagem «Nenhum número de ticket da Kushki encontrado para este pedido»: o pedido não tem uma cobrança confirmada da Kushki. Reembolse-o no Kushki Console.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Kushki Payment 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 e os logs são removidos. Se estiver desativado, todas as configurações são mantidas para uma futura reinstalação. Os registros de pagamentos da Kushki (cobranças e reembolsos) e o status de pedido Kushki payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados depois de uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento, números de ticket da Kushki e IDs de transação.
Kushki é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Kushki nem endossado por ela.