VibeFox Kushki for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda da loja: USD (Equador) ou COP (Colômbia). Para 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).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_kushki_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Kushki > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira os Merchant IDs públicos e privados de teste e mantenha Test mode ativado. Opcionalmente, configure o webhook no Kushki Console e cole a chave de assinatura dele (veja Configuração).
6. Ative Enable / Disable e faça um pedido de teste. Quando estiver pronto, insira os Merchant IDs de produção (e a assinatura do webhook de produção) e desmarque Test mode.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Kushki. Acima dos campos, a página avisa quando o método de pagamento está ativado, mas os Merchant IDs do modo atual não foram preenchidos (nesse caso o método fica oculto na finalização de compra), quando a moeda da loja não é compatível, 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 está ativado, ela mostra Test mode is on: the Kushki test environment is used, no real money is charged. Ao salvar com o método de pagamento ativado, mas sem os Merchant IDs do modo atual, um erro lembra você de preenchê-los. Espaços em volta dos IDs são removidos ao salvar.
Geral
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 o cliente vê na finalização de compra. Padrão: Credit / debit card (Kushki).
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 da 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 somente os IDs de teste, e o modo de produção somente os IDs de produção.
Test mode: Use the Kushki test (UAT) environment muda ao mesmo tempo os Merchant IDs, o formulário de cartão e a API para o ambiente de teste da Kushki. Nenhum dinheiro real é cobrado, e um selo TEST MODE aparece na finalização de compra. Padrão: ativado. Desmarque para receber pagamentos reais.
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.
Webhook (recomendado)
Os pagamentos são confirmados na hora pela resposta da API da Kushki, então o webhook não é obrigatório. Ele confirma adicionalmente pagamentos cuja resposta se perdeu (por exemplo, em um timeout) e informa cancelamentos e reembolsos feitos no Kushki Console. No Kushki Console (Webhooks), adicione a URL exibida nesta seção das configurações para pagamentos com cartão. Ela tem este formato: https://your-site/wc-api/webhook_kushki_p/. Faça isso para a conta de teste e para a conta de produção.
O plugin 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.
Webhooks sem uma assinatura válida são rejeitados. 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: Log API calls and webhooks grava as requisições e os webhooks da Kushki em WooCommerce > Status > Logs, origem wcp_kushki_payment. Erros são sempre registrados. Os logs nunca contêm Merchant IDs, tokens de cartão ou e-mails de clientes. Padrão: desativado.
Delete data on uninstall: quando ativado, excluir o plugin remove as configurações e os logs. Os pedidos e as referências deles na Kushki são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Credit / debit card (Kushki)). O formulário de cartão da Kushki aparece abaixo, com o total do pedido na moeda do pedido. Na página Pay for order, o formulário usa o total do pedido. O cliente digita o cartão, escolhe as parcelas se o formulário da Kushki oferecê-las e pressiona o botão de pagamento dentro do formulário da Kushki.
Na finalização de compra clássica, o botão Place order do WooCommerce fica oculto enquanto a Kushki está selecionada: depois que o cartão é aceito, o pedido é enviado automaticamente. No bloco de Finalização de compra, o cliente também pressiona o botão de pagamento dentro do formulário da Kushki. Se o cliente tentar fazer o pedido sem isso, aparece a mensagem Please enter your card details in the Kushki form and press its pay button.
Sua loja então cobra o cartão no servidor. O pedido só é marcado como pago depois que a Kushki o confirma com um número de ticket, e o cliente vai direto para a página de pedido recebido. Se a Kushki informar um valor ou uma moeda aprovados, eles são comparados com o pedido.
Se o cartão for recusado, o cliente vê Your payment was declined com o motivo informado pela Kushki e pode tentar outro cartão no mesmo formulário. Para problemas de rede, de chaves ou do servidor, o cliente vê The payment could not be processed right now. Please try again in a moment or choose another payment method. O motivo técnico é adicionado às notas do pedido e ao log. Um segundo clique enquanto um pagamento está sendo processado mostra A payment for this order is already being processed. Please wait a moment and check your order status.
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 WooCommerce High-Performance Order Storage (HPOS). O 3-D Secure, as regras antifraude e as parcelas oferecidas são configurados no Kushki Console.
O plugin aceita apenas cobranças com cartão em uma etapa. Não há reembolsos parciais, cartões salvos, assinaturas ou Add payment method, nem pagamento em dinheiro, transferência bancária (PSE) ou pagamentos com cartão de débito por redirecionamento, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Pending payment: o pedido foi criado e o cartão ainda não foi cobrado.
Processing: a Kushki confirmou a cobrança (pela resposta da API ou pelo webhook). Pedidos com apenas produtos virtuais para download são marcados como Completed, o padrão do WooCommerce. A nota do pedido mostra o modo, o número de ticket da Kushki e a referência. O ID da transação é a referência de transação da Kushki (ou o número do ticket).
On hold: a Kushki retornou um sucesso sem número de ticket ou informou um valor ou uma moeda diferentes do pedido. A nota do pedido explica isso. Verifique a transação no Kushki Console e então atenda o pedido ou reembolse o pagamento.
Failed: o cartão foi recusado ou a cobrança não pôde ser feita. A nota do pedido mostra o código e a mensagem da Kushki. O cliente pode pagar novamente.
Se um webhook informar outra cobrança aprovada para um pedido já pago, cancelado ou reembolsado, o pedido não é alterado. Uma nota pede que você verifique uma cobrança em duplicidade e a reembolse no Kushki Console. Um webhook do ambiente de teste para um pedido de produção (ou o contrário) é ignorado, com uma nota.
Reembolsos
Abra o pedido, clique em Refund, informe o total completo do pedido e clique em Refund via Credit / debit card (Kushki) (o botão mostra o seu Title). A Kushki reembolsa o pagamento inteiro, por isso só são aceitos reembolsos completos. Para um valor parcial, o plugin exibe Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. Um pagamento pode ser reembolsado uma única vez.
O reembolso é enviado no modo em que o pagamento foi feito (teste ou produção), portanto o Merchant ID privado desse modo precisa estar preenchido. Se a Kushki não aceitar o reembolso, o WooCommerce exibe o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ticket de reembolso da Kushki.
Cancelamentos e reembolsos feitos no Kushki Console chegam pelo webhook e são adicionados às notas do pedido. Eles não são registrados automaticamente como reembolsos 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 no topo de WooCommerce > Settings > Payments > Kushki. 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 na vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta da 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. Os gerentes da loja logados continuam vendo 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 de Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os webhooks continuam sendo processados e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Kushki não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado 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. Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é USD ou COP. A página de configurações mostra um aviso para cada um desses problemas.
O pagamento foi feito, mas o pedido está Failed ou continua em Pending payment: a resposta da API da Kushki se perdeu, por exemplo por um timeout. O webhook confirma esses pagamentos. No Kushki Console, verifique se a URL do webhook é exatamente a exibida nas configurações, 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 faz o pedido passar para Aguardando em vez disso.
O webhook responde Webhook signature not configured: nenhuma das assinaturas do 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 pertence a este pedido (chave de pedido ou transação incorreta). O pedido não é alterado.
O webhook responde Busy, retry later: o pedido estava sendo processado por outra requisição no mesmo momento. A Kushki pode reenviar a notificação.
O formulário de cartão não carrega: o cliente vê The Kushki card form could not be loaded. Please reload the page or choose another payment method. Verifique o Merchant ID público do modo atual.
O cliente vê This payment option is not available in this store. Please pay by card.: uma opção de pagamento que não é cartão foi escolhida no formulário da Kushki. O plugin cobra apenas cartões.
O cliente vê um erro ao pagar: abra as notas do pedido ou ative o Debug log e veja em WooCommerce > Status > Logs, origem wcp_kushki_payment. Um Merchant ID privado errado ou ausente gera a mensagem geral de que o pagamento não pôde ser processado.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e o Merchant ID privado desse modo não está preenchido. Insira-o e tente novamente.
O reembolso falha com No Kushki ticket number found for this order: o pedido não tem uma cobrança confirmada da Kushki. Reembolse-o no Kushki Console.
Outras moedas: desenvolvedores podem alterar a lista de moedas com o filtro kushki_p_supported_currencies, por sua conta e risco. A moeda precisa estar habilitada na sua conta da Kushki.
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 da 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 continua funcionando com o último status conhecido.
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 método de pagamento e os logs só são removidos se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento, números de ticket da Kushki e IDs de transação.
Kushki é uma marca de seu respectivo proprietário. Este plugin não é afiliado à Kushki nem endossado por ela.