VibeFox IntaSend 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, com a extensão cURL.

HTTPS: a IntaSend exige HTTPS para pagamentos em produção e para webhooks. A página de configurações avisa você quando o modo produção está ativo e o endereço da loja não é HTTPS.

Conta IntaSend: você precisa da chave publicável (ISPubKey_...) e da chave secreta (ISSecretKey_...) da sua conta IntaSend, para o sandbox, para produção ou para ambos, e de um webhook com uma frase de desafio (challenge) no painel da IntaSend (veja Configuração). A chave publicável cria o pagamento na finalização de compra. A chave secreta é usada somente no seu servidor, para consultar a IntaSend sobre o status do pagamento.

Moeda: KES, USD, EUR, GBP, UGX, TZS, NGN, GHS, XAF ou XOF. Quando a moeda da finalização de compra do cliente for outra, o método de pagamento fica oculto.

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_intasend_pay-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_intasend_pay.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, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_intasend_pay-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox IntaSend Pay Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão de 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 Chave de licença).

4. Cole suas chaves IntaSend de sandbox e/ou de produção, adicione o webhook no painel da IntaSend e informe a mesma challenge na extensão (veja Configuração).

5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test mode ativado e depois desative Test mode para aceitar pagamentos reais.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_intasend_pay.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. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox IntaSend Pay 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, as chaves IntaSend e o webhook 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 do webhook é diferente (veja Webhook).

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

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox IntaSend Pay Gateway > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, uma caixa de status mostra Test mode: IntaSend sandbox, no real money is charged. ou Live mode: real payments are accepted. Ela também avisa quando as chaves do modo atual estão ausentes ou incorretas (o método de pagamento fica então oculto na finalização de compra), quando a moeda padrão da loja não é suportada, quando nenhuma challenge de webhook está definida e quando o modo produção é usado sem HTTPS. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode ficar vazio nem ter mais de 128 caracteres, Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0, e a zona geográfica e os status de pedido selecionados precisam existir. Caso contrário, nada é salvo e o erro indica o campo. Problemas nas chaves não impedem o salvamento: a caixa de status os aponta. Chaves coladas têm os espaços das extremidades removidos.

IntaSend

Enable/Disable: Enable IntaSend 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. Também é o nome do método de pagamento gravado no pedido. Padrão: IntaSend (M-Pesa, card). Obrigatório, de 1 a 128 caracteres.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

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

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

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir antes que a IntaSend seja oferecida. Deixe em branco para oferecer a IntaSend para qualquer valor.

Chaves de API

Obtenha as chaves no painel da IntaSend, em Settings > API Keys, separadamente no painel do sandbox e no painel de produção (a seção tem links para ambos). O modo de teste usa as chaves do sandbox e a API do sandbox; o modo produção usa as chaves de produção e a API de produção. A extensão verifica se a chave publicável começa com ISPubKey_, se a chave secreta começa com ISSecretKey_ e se as chaves pertencem ao modo atual: chaves de sandbox contêm _test, chaves de produção contêm _live. Caso contrário, o método de pagamento fica oculto e a caixa de status explica o motivo.

Test mode: usa o sandbox da IntaSend; nenhum dinheiro real é cobrado. Padrão: ativado. Desative para aceitar pagamentos reais com as chaves de produção. Enquanto o modo de teste estiver ativo, os clientes veem TEST MODE - IntaSend sandbox, no real money is charged. na etapa Confirm Order.

Sandbox publishable key: começa com ISPubKey_test. Identifica o seu negócio quando uma finalização de compra é criada.

Sandbox secret key: começa com ISSecretKey_test. Usada somente no seu servidor para confirmar pagamentos com a Payment Status API.

Live publishable key: começa com ISPubKey_live.

Live secret key: começa com ISSecretKey_live. Usada somente no seu servidor para confirmar pagamentos.

Chaves secretas salvas e a challenge do webhook nunca mais são exibidas. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo. Para remover um valor salvo, marque Clear the saved value abaixo do campo e clique em Save.

Webhook

O webhook informa à sua loja que um pagamento foi feito, mesmo quando o cliente não volta à loja (navegador fechado, M-Pesa confirmado depois). No painel da IntaSend, no sandbox e em produção, abra Webhooks e adicione a URL mostrada em Webhook URL nesta seção. No OpenCart 3 ela tem a forma https://your-store/index.php?route=extension/payment/wcp_intasend_pay/webhook, e no OpenCart 4, https://your-store/index.php?route=extension/wcp_intasend_pay/payment/wcp_intasend_pay.webhook. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie a URL exatamente como as configurações a mostram. Informe ali uma frase de desafio e a mesma frase na extensão. Use uma única challenge para o sandbox e para produção.

Webhook challenge: a mesma challenge do painel da IntaSend. Webhooks com outra challenge são rejeitados. Enquanto este campo estiver vazio, os webhooks não são processados e os pagamentos são confirmados somente quando o cliente volta à loja. Esses webhooks recebem a resposta Ignored, e não um erro, para que a IntaSend não desative o webhook antes de você informar a challenge.

A extensão reage aos seguintes status de pagamento informados pela IntaSend. Cada vez, antes de alterar qualquer coisa, ela consulta a Payment Status API para obter o status real:

Notificações que não são pagamentos de finalização de compra desta loja, por exemplo links de pagamento ou eventos de envio de dinheiro da mesma conta IntaSend, recebem a resposta Ignored, para que a IntaSend não desative o webhook.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente, missing order). O pedido só recebe um status depois que a IntaSend confirma o pagamento pela Payment Status API. Cada campo abaixo lista os seus status de pedido do OpenCart.

Paid Order Status: o status definido após um pagamento confirmado pela IntaSend. Padrão: Processing.

On Hold Status: a IntaSend informou um valor ou uma moeda diferentes, um pagamento parcial, ou um pagamento feito depois que o pedido foi cancelado. O pedido recebe este status e uma nota explicando o motivo. Padrão: Pending, 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.

Refunded Status: um pagamento que chega para um pedido neste status apenas adiciona uma nota; o pedido não é reaberto. Padrão: Refunded. A própria extensão não faz reembolsos.

Avançado

Debug log: registra eventos de finalização de compra, retorno e webhook em intasend_p_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 intasend_p_debug.old.log.php. Erros e avisos são sempre registrados. Chaves de API, a challenge e os dados dos clientes nunca são registrados. 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 a extensão remove as configurações do gateway e o log. As referências da IntaSend salvas para os pedidos fazem parte do histórico de pagamentos e são sempre mantidas. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves secretas e a challenge do webhook não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves secretas salvas e a challenge do webhook são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, IntaSend (M-Pesa, card)). Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma finalização de compra na IntaSend pelo total do pedido, na moeda do pedido, e envia o cliente à página de pagamento hospedada pela IntaSend. Lá o cliente paga com M-Pesa, cartão ou outro método ativado na sua conta IntaSend. O e-mail e o telefone do cliente, bem como o nome, o endereço e o país do endereço de pagamento, são repassados à IntaSend quando atendem às regras de campos da IntaSend. Campos vazios ou inadequados são omitidos. Cada tentativa recebe uma referência IntaSend própria.

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. Por padrão, o OpenCart 4 não pede um endereço de pagamento; nesse caso a extensão envia à IntaSend o endereço, a cidade, o CEP e o país do endereço de entrega.

Depois do pagamento, o cliente volta pelo endereço da página inicial da sua loja, porque a IntaSend não aceita alguns caracteres no endereço de retorno; a extensão então encaminha o cliente para a sua página de retorno. O pedido só é marcado como pago depois que a IntaSend confirma: a extensão consulta a Payment Status API quando o cliente retorna e quando o webhook chega. O pedido então recebe o status da forma padrão do OpenCart, com os e-mails habituais de pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Se o pedido foi colocado em espera, a página também mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed. Se o pagamento ainda não estiver confirmado, ou se a IntaSend não puder ser acessada naquele momento, uma página Payment confirmation mostra Your payment is being confirmed by IntaSend (M-Pesa confirmations can take a minute). You will receive an e-mail as soon as it is confirmed. com os botões Check again e Back to checkout. O webhook define o status do pedido assim que a IntaSend confirma o pagamento.

Se o pagamento falhou, o cliente volta à finalização de compra com The payment was not successful. Please try again or choose another payment method. (com o motivo da IntaSend, se informado). Se o cliente voltou sem pagar, a mensagem é The payment was not completed. Please try again or choose another payment method. O carrinho é mantido e o cliente pode pagar de novo. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. 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, então, após um pagamento com falha, o cliente paga o mesmo pedido com uma nova tentativa. Um mesmo carrinho é pago apenas uma vez: se outro pedido do mesmo carrinho já estiver pago, o cliente vai para a página de sucesso em vez de um novo pagamento. 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 (por exemplo, você o cancelou ou reembolsou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled or refunded. Please confirm the order again. Se o pedido já foi registrado e o carrinho agora tem outros produtos, a mensagem é Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. Nos dois casos, o próximo clique em Confirm Order paga um novo pedido do carrinho.

Se a IntaSend não puder iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma mensagem acima do botão: IntaSend could not start the payment: e o motivo informado pela IntaSend, ou IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. Os detalhes são gravados no log. Um pedido com total zero não pode ser pago com a IntaSend.

O webhook 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 o webhook e o retorno do cliente.

A extensão aceita apenas pagamentos únicos. Reembolsos não são enviados à IntaSend pela loja, e ela não tem cartões salvos, assinaturas nem formulário de pagamento embutido (pop-up). Links de finalização de compra mais antigos do mesmo pedido não podem ser cancelados na IntaSend.

Pedidos

Status de pedido

No status (missing order): o cliente foi enviado à IntaSend e não pagou, o pagamento falhou, ou a IntaSend ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Paid Order Status (default Processing): o pagamento foi confirmado. Uma nota mostra a fatura da IntaSend, o método de pagamento na IntaSend, o valor, o modo (sandbox ou produção) e como foi confirmado (webhook ou retorno do cliente).

On Hold Status (default Pending): a IntaSend informou um valor ou uma moeda diferentes do total do pedido, um pagamento parcial, ou um pagamento que chegou depois que o pedido foi cancelado. A nota explica. Verifique o pagamento no painel da IntaSend e então conclua o pedido ou reembolse o pagamento. Se o pagamento correto chegar depois, o pedido passa para Paid Order Status e o cliente é avisado por e-mail.

Se um segundo pagamento chegar para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você o reembolse no painel da IntaSend, caso seja uma duplicata. Um pagamento para um pedido no status Refunded Status adiciona uma nota e não reabre o pedido.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox IntaSend Pay Gateway

Em Sales > Orders, abra um pedido pago com a IntaSend. Na parte de baixo da página do pedido, ao lado de History e Additional, a aba VibeFox IntaSend Pay Gateway mostra as IntaSend checkout attempts do pedido (data, referência, finalização de compra na IntaSend, ambiente, valor, fatura e método de pagamento, resultado com o motivo da falha), as Invoices processed (fatura, status na IntaSend, valor e resultado) e as IntaSend 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 à IntaSend pela loja. Reembolse o pagamento no painel da IntaSend e registre o reembolso no OpenCart manualmente, por exemplo, definindo o pedido como Refunded Status.

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 IntaSend Pay Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox IntaSend Pay 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 ficam a linha Product: opencart-payment-intasend e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma da administração (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 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a IntaSend 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. Um usuário administrador conectado à administração 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, um lembrete aparece no Dashboard da administração. Feche-o com × para ocultá-lo por 7 dias. 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 de novo automaticamente quando você abre o Dashboard ou a página Edit da administração: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é preciso 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 IntaSend não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se as chaves do modo atual estão preenchidas e pertencem a esse modo: chaves de sandbox (com _test) no modo de teste, chaves de produção (com _live) no modo produção. A caixa de status no topo da página de configurações mostra o que está errado. A moeda da finalização de compra do cliente precisa ser suportada. Verifique 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: as confirmações do M-Pesa podem levar um momento. O webhook define o status quando a IntaSend informa o estado final. Verifique se a URL do webhook no painel da IntaSend (sandbox ou produção, o modo que você usa) é exatamente a mostrada em Webhook URL e se a challenge ali é a mesma de Webhook challenge. O pedido também recebe o status quando o cliente volta à loja ou clica em Check again.

O webhook responde Ignored: webhook challenge not configured: o campo Webhook challenge está vazio. Informe a challenge do painel da IntaSend.

O webhook responde Invalid challenge: a challenge na IntaSend e na extensão são diferentes, ou o webhook não tem challenge.

O webhook responde Verification unavailable, retry later ou Busy, retry later: a IntaSend não pôde ser acessada naquele momento, o pedido (o seu carrinho) estava sendo confirmado por outra requisição, ou não foi possível definir o status do pedido. A IntaSend tenta o webhook novamente. O motivo está no log.

O webhook responde Invoice not verified ou Invoice does not match the reference: a IntaSend não confirmou que esta fatura pertence ao pedido. Nada é alterado.

A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da IntaSend.

O pedido está no On Hold Status: leia as notas na aba VibeFox IntaSend Pay Gateway. O valor ou a moeda pagos eram diferentes do pedido, o pagamento foi parcial, ou ele chegou depois que o pedido foi cancelado. Verifique o pagamento no painel da IntaSend.

O cliente vê um erro depois de Confirm Order: veja o campo Log na página da extensão (ative Debug log para mais detalhes). Se as chaves do modo atual estiverem erradas, o cliente vê IntaSend is not available at the moment. Please choose another payment method or contact the store. This payment method is not available. significa que a sessão de finalização de compra não corresponde mais ao pedido ou que o método de pagamento foi desativado nesse meio-tempo: o cliente recarrega a finalização de compra. Se o log disser que a URL de retorno contém caracteres que a IntaSend não aceita, a causa é o endereço da loja.

O cliente vê We could not match this payment to an order: o link de retorno foi alterado ou pertence a outro pedido. Se o cliente pagou, o webhook ainda define o status do pedido.

Para desenvolvedores: antes de a finalização de compra ser criada, a extensão dispara o evento do OpenCart intasend_p_checkout_payload com os dados da requisição, o pedido e o modo; o evento intasend_p_supported_currencies pode alterar a lista de moedas.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox IntaSend Pay 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 status de pedido da seção Orders, que voltam aos padrões em uma reinstalação. Os eventos do OpenCart da extensão também são removidos (no OpenCart 4, também a sua ação de inicialização (startup action), que deixa passar o webhook 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, modo de teste, chaves, challenge do webhook, chave do debug log) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação futura. As tentativas de finalização de compra na IntaSend e as faturas dos pedidos são sempre mantidas. 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 IntaSend Pay Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

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