VibeFox Khipu for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou posterior. O módulo não é instalado em versões mais antigas do PHP.

Moeda: peso chileno (CLP), peso argentino (ARS) ou sol peruano (PEN). Para carrinhos em outras moedas, o método de pagamento fica oculto na finalização de compra.

Conta Khipu: você precisa do Receiver ID («Id de cobrador»), da API key e da Secret key da sua conta de cobrança Khipu. Você encontra esses dados na sua conta Khipu, no perfil do comerciante (khipu.com/merchant/profile). Os três são obrigatórios: sem a Secret key, nenhum pagamento pode ser confirmado. Não é preciso configurar nada na conta Khipu.

Loja acessível: o Khipu confirma pagamentos chamando a sua loja, então a URL de notificação precisa estar acessível pela internet, sem proteção por senha e sem firewall que bloqueie o Khipu. O modo de manutenção da loja não bloqueia essa comunicação.

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

3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).

4. Insira o Receiver ID, a API key e a Secret key da sua conta de cobrança Khipu (veja Configuração).

5. Ative Enable / Disable e clique em Save. Para testar primeiro, use as chaves de uma conta de desenvolvedor do Khipu e depois substitua-as pelas chaves da sua conta de produção.

Ao instalar, o módulo cria o status de pedido Khipu payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Khipu Gateway > 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 Receiver ID, a API key ou a Secret key estão faltando (nesse caso o Khipu não é oferecido na finalização de compra) e quando a moeda padrão da loja não é suportada pelo Khipu.

Khipu

Enable / Disable: Enable Khipu payments liga ou desliga o método de pagamento. Padrão: desligado.

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento gravado no pedido. Padrão: Khipu. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay by bank transfer with Khipu.

Conta Khipu

Copie o Receiver ID, a API key e a Secret key da sua conta de cobrança Khipu (khipu.com/merchant/profile). O Khipu não tem um servidor de testes separado, e o módulo não tem chave de modo de teste. Para testar, use as chaves de uma conta de cobrança de desenvolvedor («desarrollo»): ela paga pelo banco de testes DemoBank, e nenhum dinheiro real é movimentado. Troque para as chaves da sua conta de cobrança de produção quando entrar em operação.

Receiver ID: o seu ID de recebedor («cobrador») no Khipu. Pagamentos de outras contas Khipu são rejeitados.

API key: usada para criar os pagamentos e para verificar cada pagamento no Khipu.

Secret key: usada para verificar a assinatura (HMAC-SHA256) das notificações de pagamento do Khipu. Sem ela, nenhum pagamento pode ser confirmado.

As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.

Clear saved secrets: marque API key ou Secret key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Notificações de pagamento

Notification URL: o Khipu confirma pagamentos chamando a URL mostrada aqui. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_khipu_gateway/webhook, possivelmente com um código de idioma. A URL é enviada automaticamente com cada pagamento, então não há nada para configurar na sua conta Khipu, mas a URL precisa estar acessível pela internet.

Cada notificação deve conter uma assinatura válida feita com a sua Secret key. Notificações sem assinatura válida são rejeitadas. O módulo nunca confia no conteúdo da notificação: ele consulta o Khipu para obter o status do pagamento e age de acordo com o que o Khipu informa:

Status after payment: o status do pedido assim que o Khipu confirma o pagamento. O status é definido de imediato, com uma única alteração de status.

Avançado

Debug log: registra as chamadas à API e as notificações em logs/wc_khp_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com a chave desligada. Chaves e dados do pagador nunca são gravados. Padrão: desligado.

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

Delete data on uninstall: quando ligado, desinstalar o módulo remove as configurações do gateway e o registro. Os dados dos pedidos (IDs de pagamento Khipu dos pedidos) são sempre mantidos. Padrão: desligado.

Finalização de compra

Na finalização de compra, o cliente escolhe o método de pagamento (por padrão Khipu) com a sua descrição e confirma o pedido. O módulo cria um pagamento Khipu para o total do carrinho na moeda do carrinho e envia o cliente para a página de pagamento do Khipu. No Khipu, o pagamento aparece como Order # com o número do carrinho e o nome da loja, junto com a lista de produtos. O e-mail do cliente é passado ao Khipu quando é válido. Na página do Khipu, o cliente paga por transferência bancária do próprio banco. Nesse momento ainda não existe pedido.

Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago depois que o Khipu confirma: pela notificação assinada ou por uma consulta de status ao Khipu quando o cliente retorna. O retorno em si nunca marca nada como pago. Depois que o pedido é criado, o cliente vê a página padrão de confirmação do pedido. Se o banco ainda estiver verificando a transferência ou o Khipu não estiver acessível, uma página Payment confirmation mostra Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. com os botões Check again e Back to checkout. Se o último pagamento Khipu do carrinho não puder ser associado a ele (por exemplo, pertence a outro Receiver ID), o cliente volta à finalização de compra com a mensagem We could not match this payment to an order. If you paid, please contact us.

Se o cliente sair da página do Khipu sem pagar, ou o pagamento não tiver sido concluído, ele volta à finalização de compra com a mensagem The Khipu payment was not completed. You can try again or choose another payment method. O carrinho é mantido. 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á recebeu o pagamento anterior, o pedido é criado e nenhum novo pagamento é feito. Se a transferência anterior ainda estiver sendo verificada, 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.

Se o Khipu não conseguir criar o pagamento, o cliente permanece na finalização de compra com 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 registro.

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

O módulo aceita apenas pagamentos únicos por transferência bancária. Reembolsos não são enviados ao Khipu a partir do PrestaShop, e o módulo não tem assinaturas, métodos de pagamento salvos nem pré-autorizações. Pagamentos não concluídos não ficam vinculados a uma reserva de estoque.

Pedidos

Status do pedido

No order yet: o cliente foi enviado ao Khipu e não pagou, ou o Khipu ainda não confirmou a transferência. Existe apenas o carrinho.

Payment accepted or Delivered: o Khipu confirmou o pagamento. O status segue Status after payment. O pagamento é registrado com o ID de pagamento do Khipu como ID da transação, e uma nota mostra Khipu payment verified. Payment ID: com o ID do pagamento e o valor.

Khipu payment on hold: o Khipu confirmou um pagamento cujo valor ou moeda não corresponde ao pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou), ou o pagamento chegou depois que o pedido foi cancelado. O valor realmente recebido é registrado no pedido (não quando a moeda é diferente), e uma nota explica isso. Verifique o pagamento na sua conta Khipu e depois conclua o pedido ou reembolse o cliente. Se um pagamento posterior do valor correto chegar para o mesmo carrinho, o pedido passa para o status de pago.

Se chegar um pagamento para um pedido que já está pago ou que foi fechado após o pagamento, o pedido não é alterado. Uma nota pede que você reembolse o cliente se for um segundo pagamento. Se o Khipu informar que um pagamento pago foi estornado, o pedido recebe uma nota e o seu status não muda.

Bloco de pagamento Khipu

A página do pedido mostra um bloco Khipu payment com as tentativas de pagamento Khipu do carrinho do pedido (data, valor, ID de pagamento Khipu, status e resultado no Khipu), um aviso Manual review enquanto o pedido estiver em Khipu payment on hold, e as Khipu notes do pedido. O bloco é somente leitura.

Reembolsos

Reembolsos não são enviados ao Khipu a partir do PrestaShop, porque o Khipu não oferece reembolso pela sua API. Reembolse o cliente pela sua conta Khipu ou por transferência bancária, e depois registre o reembolso manualmente no PrestaShop.

Chave de licença

O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Khipu Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Khipu 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-khipu e o link Manage licenses and domains in your account, que abre a sua conta em 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 (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 for alterado, 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 domínio: o domínio da loja principal, também em uma configuração com várias lojas. 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, o Khipu não é exibido 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.

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 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

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 do carrinho precisa ser CLP, ARS ou PEN. A página de configurações mostra 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: o Khipu confirma a transferência depois que o banco a verifica. O pedido é criado quando a notificação do Khipu chega ou quando o cliente clica em Check again. Verifique se a sua loja está acessível pela internet na URL mostrada em Notification URL (sem proteção por senha e sem firewall bloqueando o Khipu), e veja o campo Log na página do módulo.

A notificação responde Secret key not configured: a Secret key está vazia. Preencha-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 Order not found ou Payment does not belong to this order: o pagamento foi feito para outro Receiver ID ou para outro carrinho. Verifique o Receiver ID.

A notificação responde Payment not final yet ou Verification unavailable: a transferência ainda está sendo verificada, ou o Khipu não pôde ser contatado. O Khipu envia a notificação novamente.

A notificação responde Busy, retry later ou Order could not be created, retry later: o pedido estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O Khipu envia a notificação novamente. O motivo está no registro.

O pedido está em Khipu payment on hold: leia as notas no bloco Khipu payment. O valor ou a moeda não correspondiam ao pedido, ou o pagamento chegou depois que o pedido foi cancelado.

O cliente vê "Khipu payments are not available right now": a API key está faltando ou está incorreta. Verifique as chaves na sua conta Khipu.

Se a sua conta Khipu aceitar outra moeda, por exemplo EUR para o Khipu Espanha, desenvolvedores podem adicioná-la com o hook actionWcpKhipuSupportedCurrencies.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Khipu Gateway 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 ligado, as configurações do gateway e o registro são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. As tentativas de pagamento Khipu e o status de pedido Khipu payment on hold são sempre mantidos. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.

Khipu é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo Khipu.