VibeFox Khipu for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: peso chileno (CLP), peso argentino (ARS) ou sol peruano (PEN). A moeda precisa existir em System > Localisation > Currencies. A Khipu só é oferecida enquanto o cliente paga em uma dessas moedas; para outras moedas, o método de pagamento fica oculto no checkout.

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

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

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um único domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote para OpenCart 3 wcp_khipu_gateway-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_khipu_gateway.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_khipu_gateway-oc3-(version).ocmod.zip. A extensão não possui modificações OCMOD, portanto Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Khipu Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja License key).

4. Informe o Receiver ID, a API key e a Secret key da sua conta de cobrança na Khipu (veja Configuration).

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

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_khipu_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Khipu Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as chaves da Khipu como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Apenas a URL de notificação é diferente (veja Notificações de pagamento).

Uma instalação nova começa com o método de pagamento desativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando o Receiver ID, a API key ou a secret key estão ausentes (a Khipu então não é oferecida no checkout) e quando a moeda padrão da loja não é compatível com a Khipu (a Khipu então só é oferecida enquanto o cliente paga em CLP, ARS ou PEN). Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode estar vazio nem ter mais de 128 caracteres, Sort Order precisa ser um número inteiro, Total precisa ser um número igual ou maior que 0, e a zona geográfica e os status de pedido precisam existir. Caso contrário, nada é salvo e a página indica o campo. Chaves ausentes não impedem o salvamento.

Khipu

Enable / Disable: Enable Khipu payments 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. Ele também é o nome do método de pagamento gravado no pedido. Padrão: Khipu. Obrigatório, de 1 a 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pague por transferência bancária com a Khipu.

Sort Order: a posição da Khipu entre os métodos de pagamento no checkout. Deixe em branco ou informe um número inteiro.

Geo Zone: ofereça a Khipu somente para endereços de pagamento da zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total do checkout, na moeda padrão da loja, que um pedido deve atingir antes que a Khipu seja oferecida. Deixe em branco para oferecer a Khipu para qualquer total.

Conta na Khipu

Copie o Receiver ID, a API key e a secret key da sua conta de cobrança na Khipu (a seção tem um link para khipu.com/merchant/profile). A Khipu não tem um servidor sandbox separado, e a extensão 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 for para o modo real.

Receiver ID: o seu ID de recebedor ("cobrador") na Khipu. Pagamentos de outras contas Khipu são rejeitados.

API key: usada para criar pagamentos e para verificar cada pagamento com a Khipu.

Secret key: usada para verificar a assinatura (HMAC-SHA256) das notificações de pagamento da 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 somente se quiser alterá-lo. Para remover uma chave salva, marque Clear the saved value abaixo do campo e clique em Save.

Notificações de pagamento

Notification URL: a Khipu confirma os pagamentos chamando a URL mostrada aqui. No OpenCart 3 ela tem o formato https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook; no OpenCart 4, o formato é https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. 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 precisa trazer uma assinatura válida feita com a sua Secret key. Notificações sem assinatura válida são rejeitadas. A extensão nunca confia no conteúdo da notificação: ela consulta o status do pagamento na Khipu e age de acordo com o que a Khipu informa:

Status after payment: o status que o pedido recebe quando a Khipu confirma o pagamento. O status é aplicado de imediato, em uma única alteração de status.

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele só recebe um status depois que a Khipu confirma o pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Paid Order Status: o status após um pagamento confirmado quando Status after payment é Processing. Padrão: Processando.

Complete Order Status: o status após um pagamento confirmado quando Status after payment é Completed. Padrão: Concluído.

On Hold (Review) Status: os pagamentos cujo valor ou moeda não correspondem ao pedido, ou que chegam depois que o pedido foi cancelado, recebem este status e uma nota explicando o motivo. Padrão: Pendente, porque o OpenCart não tem um status "On hold". Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Avançado

Debug log: registra as chamadas de API e as notificações em wc_khp_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para wc_khp_debug.old.log.php. Erros são sempre registrados, mesmo com a chave desativada. Chaves e dados do pagador 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 data on uninstall: quando ativado, ao desinstalar a extensão são removidas as configurações do gateway e o log. Os dados dos pedidos (os IDs de pagamento Khipu dos pedidos) são sempre mantidos. Padrão: desativado.

Importação / Exportação

Export: Download JSON salva as configurações em um arquivo JSON. A API key e a secret key não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. A API key e a secret key salvas são mantidas.

Checkout

Na etapa Payment Method o cliente escolhe o método de pagamento (por padrão, Khipu). Na etapa Confirm Order o cliente vê a sua descrição acima do botão de confirmação. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria um pagamento na Khipu pelo total do pedido, na moeda do pedido, e envia o cliente para a página de pagamento da Khipu. Na Khipu, o pagamento aparece como Order # com o número do pedido e o nome da loja, junto com a lista de produtos. O e-mail do cliente é enviado à Khipu quando é válido. Na página da Khipu, o cliente paga por transferência bancária do próprio banco.

No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose no bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte de baixo da página de finalização de compra.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Khipu confirma: pela notificação assinada ou por uma consulta de status à Khipu quando o cliente retorna. O retorno em si nunca marca nada como pago. Em seguida o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização de estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Se o banco ainda estiver verificando a transferência ou a Khipu não puder ser acessada, uma página de Payment confirmation mostra Khipu is confirming your bank transfer. Your order will be confirmed 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 da Khipu do pedido não puder ser associado a ele (por exemplo, porque pertence a outro Receiver ID), o cliente volta ao checkout com a mensagem We could not match this payment to an order. If you paid, please contact us.

Se o cliente cancelar na página da Khipu, ou o pagamento não tiver sido concluído, o cliente volta ao checkout com a mensagem The Khipu payment was not completed. You can try again or choose another payment method. O carrinho é mantido. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. Cada nova tentativa (o OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 atualiza o pedido da finalização de compra e o paga com um novo pagamento Khipu) exclui o pagamento anterior não pago da Khipu do pedido ou do carrinho, para que o link antigo não possa mais ser pago. Se a Khipu já tiver recebido o pagamento anterior, ele é aplicado e o cliente vai para a página de sucesso, sem novo pagamento. Se a transferência anterior ainda estiver sendo verificada pelo banco, 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 pagamento anterior estiver em análise, o cliente é orientado a entrar em contato com a loja antes de pagar novamente. Uma alteração do carrinho, incluindo uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se, nesse meio-tempo, o pedido foi fechado sem pagamento (por exemplo, você o cancelou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Se o pedido já foi registrado e o carrinho mudou desde então, a mensagem é Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. Nos dois casos, o próximo clique em Confirm Order paga um novo pedido do carrinho.

Se a Khipu não conseguir criar o pagamento, o cliente permanece na etapa Confirm Order com uma mensagem curta acima do botão, 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.

A notificação também funciona enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup action) que deixa passar a notificação e o retorno do cliente.

A extensão aceita somente pagamentos únicos por transferência bancária. Reembolsos não são enviados à Khipu pelo OpenCart, e não há assinaturas, métodos de pagamento salvos nem pré-autorizações. Pagamentos não concluídos não estão vinculados a uma reserva de estoque.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado à Khipu e não pagou, ou a Khipu ainda não confirmou a transferência. Em Sales > Orders esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Paid Order Status ou Complete Order Status (padrão Processando ou Concluído): a Khipu confirmou o pagamento. O status segue Status after payment. Uma nota mostra Khipu payment verified. Payment ID: com o ID do pagamento e o valor.

On Hold (Review) Status (padrão Pendente): a Khipu confirmou um pagamento cujo valor ou moeda não corresponde ao pedido, ou o pagamento chegou depois que o pedido foi cancelado ou recusado. Uma nota explica. Verifique o pagamento na sua conta Khipu e depois conclua o pedido ou reembolse o cliente. Se, mais tarde, chegar um pagamento do valor correto para o mesmo pedido, ele passa ao status de pago e o cliente é avisado por e-mail. Se o pagamento chegar depois que o pedido tiver sido passado para outro status de processamento, o status não muda e apenas uma nota é adicionada.

Se chegar um pagamento para um pedido que já está pago, ou para outro pedido de um carrinho já pago, o pedido não é alterado. Uma nota pede que você o reembolse ao cliente, se for um segundo pagamento. Se a Khipu informar que um pagamento pago foi revertido, o pedido recebe uma nota e o seu status não muda.

As notas são entradas do History do pedido que o cliente não vê. Elas começam com a palavra Khipu.

Aba VibeFox Khipu Gateway

Em Sales > Orders abra um pedido pago com a Khipu. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Khipu Gateway mostra as tentativas de pagamento da Khipu do pedido (data, valor, ID do pagamento na Khipu, status e resultado na Khipu), um aviso Manual review enquanto o pedido estiver no status de revisão, e as Khipu notes do pedido. A aba é somente leitura e é exibida para os usuários que têm acesso à extensão.

Reembolsos

Reembolsos não são enviados à Khipu pelo OpenCart, porque a Khipu não oferece reembolso pela sua API. A aba informa isso. Reembolse o cliente pela sua conta Khipu ou por transferência bancária e, depois, altere manualmente o status do pedido no OpenCart.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Khipu Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit, 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 aparecem a linha Product: opencart-payment-khipu e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (estão incluídos 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 muda, ou depois que você libera uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja nas configurações do OpenCart. 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 Khipu 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. Um usuário administrador conectado ao painel no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 esta prévia não está disponível: a loja não enxerga o login do administrador, então sem uma chave ativa o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A Khipu não aparece no checkout: verifique se a licença está ativa, se Enable / Disable está ativado e se o Receiver ID, a API key e a Secret key estão todos informados. O cliente precisa pagar em CLP, ARS ou PEN. A página de configurações mostra um aviso quando algo está faltando. Confira também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: a Khipu confirma uma transferência depois que o banco a verifica. O pedido recebe o seu status quando a notificação da Khipu chega ou quando o cliente clica em Check again. Verifique se a sua loja está acessível pela internet no endereço mostrado em Notification URL (sem proteção por senha e sem firewall bloqueando a Khipu) e consulte o campo Log na página da extensão.

A notificação responde Secret key not configured: a Secret key está vazia. Informe-a. A 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 da Khipu.

A notificação responde Order not found, Payment not found for this account ou Payment does not belong to this order: o pagamento foi feito para outro Receiver ID, com outras chaves ou para outro pedido. Verifique o Receiver ID e as chaves.

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

A notificação responde Busy, retry later ou Order could not be updated, retry later: o pedido estava sendo confirmado por outra requisição no mesmo momento, ou o status do pedido não pôde ser definido. A Khipu envia a notificação novamente. O motivo está no log.

O pedido está no status de revisão após o pagamento: leia as notas na aba VibeFox Khipu Gateway. O valor ou a moeda não correspondiam ao pedido, ou o pagamento chegou depois que o pedido tinha sido cancelado.

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

Para desenvolvedores: a extensão dispara os eventos do OpenCart wc_khp_supported_currencies (para adicionar uma moeda que a sua conta Khipu aceita, por exemplo EUR para a Khipu Espanha), wc_khp_currency_decimals e wc_khp_payment_data.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Khipu Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable / Disable, Sort Order, Geo Zone, Total e os três status de pedido, que voltam aos padrões em uma reinstalação. No OpenCart 4, também são removidos o seu evento e a sua ação de inicialização (startup action), que deixa passar a notificação e o retorno do cliente no modo de manutenção. Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, Receiver ID, chaves, status após o pagamento, debug log) e o log são removidos. Se estiver desativado, elas são mantidas para uma futura reinstalação. As tentativas de pagamento da Khipu são sempre mantidas, para que notificações tardias de pedidos pagos antes continuem sendo tratadas após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, depois da desinstalação acesse Extensions > Installer e clique em Uninstall (o botão laranja −) ao lado de VibeFox Khipu Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

Khipu é uma marca de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Khipu.