VibeFox Khipu for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin se recusa a ser ativado.
PHP: 8.0 ou superior.
Moeda da loja: peso chileno (CLP), peso argentino (ARS) ou sol peruano (PEN). O meio de pagamento fica oculto na finalização de compra quando a loja, ou o pedido na página Pay for order, usa outra moeda.
Conta Khipu: você precisa do Receiver ID ("Id de cobrador"), da chave de API e da chave secreta ("llave") da sua conta de cobrança Khipu. Você as encontra na sua conta Khipu, no perfil de comerciante (khipu.com/merchant/profile). As três são obrigatórias: sem a chave secreta, nenhum pagamento pode ser confirmado.
Site acessível: o Khipu confirma os pagamentos chamando a sua loja, então o site precisa estar acessível pela internet (sem modo de manutenção, autenticação básica ou firewall bloqueando o Khipu).
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_khipu_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Khipu > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Informe sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe o Receiver ID, a API key e a Secret key da sua conta de cobrança Khipu (veja Configuração).
6. Ative Enable / Disable e salve. Para testar primeiro, use as chaves de uma conta de desenvolvedor Khipu e depois substitua pelas chaves da sua conta de produção.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Khipu. Acima dos campos, a página avisa quando o Receiver ID, a chave de API ou a chave secreta estão faltando (nesse caso o Khipu não é oferecido na finalização de compra) e quando a moeda da loja não é suportada. Na lista de meios de pagamento, o Khipu aparece marcado como precisando de configuração até que as três chaves sejam informadas.
Geral
Enable / Disable: Enable Khipu payments ativa ou desativa o meio de pagamento. Padrão: desativado.
Title: o nome do meio de pagamento que os clientes veem na finalização de compra. Padrão: Khipu.
Description: o texto exibido abaixo do meio de pagamento na finalização de compra. Padrão: Pay by bank transfer with Khipu.
Conta Khipu
Copie o Receiver ID, a chave de API e a chave secreta da sua conta de cobrança Khipu (khipu.com/merchant/profile). O Khipu não tem um servidor de testes separado, e o plugin não tem uma opção de modo de teste. Para testar, use as chaves de uma conta de cobrança de desenvolvedor ("desarrollo"): ela paga com o banco de testes DemoBank, e nenhum dinheiro real é movimentado. Passe para as chaves da sua conta de cobrança de produção quando colocar a loja no ar.
Receiver ID: seu ID de Receiver ("cobrador") do Khipu. Pagamentos de outras contas Khipu são rejeitados.
API key: usada para criar pagamentos e para verificar cada pagamento junto ao Khipu.
Secret key: usada para verificar a assinatura (HMAC-SHA256) das notificações de pagamento do Khipu. Sem ela, nenhum pagamento pode ser confirmado.
Notificações de pagamento
O Khipu confirma os pagamentos chamando a URL de notificação mostrada nesta seção das configurações. Ela se parece com https://your-site/wc-api/webhook_wc_khipu/. A URL é enviada automaticamente com cada pagamento, então não há nada a configurar na sua conta Khipu, mas a URL precisa estar acessível pela internet.
Cada notificação deve trazer uma assinatura válida feita com sua Secret key. Notificações sem uma assinatura válida são rejeitadas. Em seguida, o plugin consulta o Khipu sobre o status do pagamento e age conforme o que o Khipu informa:
Status after payment: o status do pedido depois que o Khipu confirma o pagamento. O status é definido de uma só vez, com uma única mudança de status e um único conjunto de e-mails.
Avançado
Debug log: Log API calls and notifications em WooCommerce > Status > Logs, origem wcp_khipu_gateway. Erros são sempre registrados. Chaves e dados do pagador nunca são gravados. Padrão: desativado.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Os dados dos pedidos (IDs de pagamento Khipu nos pedidos) são sempre mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o meio de pagamento (por padrão, Khipu) e faz o pedido. O plugin cria um pagamento Khipu com o total do pedido na moeda do pedido, com o número do pedido, o nome da loja e os itens pedidos, e envia o cliente para a página de pagamento do Khipu. O e-mail de cobrança é passado ao Khipu quando é válido. Na página do Khipu, o cliente paga por transferência bancária a partir do próprio banco e escolhe ali entre os tipos de transferência que o Khipu oferece.
Depois de pagar, o cliente volta para a página de pedido recebido da sua loja. O pedido só é marcado como pago depois que o Khipu confirma a transferência: pela notificação assinada, ou por uma consulta de status ao Khipu quando o cliente abre a página de pedido recebido. O retorno em si nunca marca um pedido como pago. Enquanto a transferência não é confirmada, a página mostra Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.
Se o cliente sair da página do Khipu sem pagar, ele chega à página Pay for order com The Khipu payment was not completed. You can try again or choose another payment method. Uma nova tentativa exclui o pagamento Khipu anterior não pago, então o link antigo não pode mais ser pago. Se o Khipu já tiver recebido o pagamento anterior, o pedido é concluído e nenhum novo pagamento é criado. Se a transferência anterior ainda estiver em verificação, o cliente vê Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.
Com o controle de estoque ativado, o pagamento Khipu expira junto com o tempo Hold stock (minutes) do WooCommerce, então o cliente não consegue pagar um pedido que já foi cancelado.
Se o Khipu não conseguir criar o pagamento, o cliente vê uma mensagem curta, por exemplo Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. ou Khipu is temporarily unavailable. Please try again in a few minutes. Os detalhes são gravados no log.
O meio de pagamento funciona na finalização de compra clássica, no bloco de Checkout e na página Pay for order. Ele é compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin aceita apenas pagamentos únicos por transferência bancária. Reembolsos do WooCommerce não são suportados, e ele não tem assinaturas, meios de pagamento salvos ou pré-autorizações.
Pedidos
Status dos pedidos
Pending payment: o cliente foi enviado ao Khipu e ainda não pagou, ou o Khipu ainda não confirmou a transferência. A nota do pedido mostra o ID do pagamento Khipu.
Processing or Completed: o Khipu confirmou o pagamento. O status segue a opção Status after payment. A nota do pedido mostra o ID do pagamento Khipu, e o ID da transação é o ID do pagamento Khipu.
On hold: o Khipu informou um pagamento cujo valor ou moeda não corresponde ao pedido, ou o pagamento chegou depois que o pedido havia sido cancelado (por exemplo, após o tempo de reserva de estoque). A nota do pedido explica a situação. Verifique o pagamento na sua conta Khipu e conclua o pedido ou reembolse o cliente.
Se um pagamento chegar para um pedido que já está pago ou que foi encerrado após o pagamento, o pedido não é alterado. Uma nota pede que você o reembolse ao cliente, caso seja um segundo pagamento.
Reembolsos
Os reembolsos não são enviados ao Khipu a partir do WooCommerce. Reembolse o cliente pela sua conta Khipu ou por transferência bancária e depois registre o reembolso manualmente no WooCommerce.
Chave de licença
O plugin funciona com uma chave de licença VibeFox do vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Khipu. 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta 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 vibefox.net.
Sem uma chave ativa, o Khipu não é mostrado 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 de loja conectados ainda veem o meio 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. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem uma renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
O Khipu não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado e se o Receiver ID, a API key e a Secret key estão todos preenchidos. A moeda da loja precisa ser CLP, ARS ou PEN. A página de configurações mostra um aviso quando algo está faltando.
O pagamento foi feito, mas o pedido continua como Pagamento pendente: o Khipu confirma uma transferência depois que o banco a verifica. O pedido é atualizado quando a notificação do Khipu chega ou quando o cliente abre a página de pedido recebido. Verifique se o seu site está acessível pela internet na URL de notificação mostrada nas configurações (sem modo de manutenção, autenticação básica ou firewall bloqueando o Khipu) e consulte WooCommerce > Status > Logs, origem wcp_khipu_gateway.
A notificação responde Secret key not configured: a Secret key está vazia. Informe-a. O Khipu envia a notificação novamente.
A notificação responde Invalid signature, Missing signature ou Malformed signature: a Secret key não pertence à conta de cobrança cujas chaves você usa, ou a requisição não veio do Khipu.
A notificação responde Payment does not belong to this order: o pagamento foi feito para outro Receiver ID ou para outro pedido. Verifique o Receiver ID.
A notificação responde Payment not final yet ou Verification unavailable: a transferência ainda está em verificação, ou não foi possível contatar o Khipu. O Khipu envia a notificação novamente.
O pedido está Aguardando: leia a nota do pedido. O valor ou a moeda não correspondia ao pedido, ou o pagamento chegou depois que o pedido havia sido cancelado.
O cliente vê "Khipu payments are not available right now": a chave de API está faltando ou está incorreta. Verifique as chaves na sua conta Khipu.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já está em uso em outro domínio, libere uma vaga na sua conta 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.
Se a sua conta Khipu aceitar outra moeda, por exemplo EUR para o Khipu Espanha, os desenvolvedores podem adicioná-la com o filtro wc_khp_supported_currencies.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative 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 e os logs são removidos apenas se Delete data on uninstall estiver ativado. Caso contrário, eles permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Khipu é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado ao Khipu nem endossado por ele.