VibeFox IntaSend for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão cURL. O módulo não é instalado em versões mais antigas do PHP nem sem cURL.

HTTPS: a IntaSend exige HTTPS para pagamentos em produção e para webhooks. A página de configurações avisa quando o modo produção está ativado e a loja não usa HTTPS.

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

Moeda da loja: KES, USD, EUR, GBP, UGX, TZS, NGN, GHS, XAF ou XOF. Para outras moedas, o método de pagamento fica oculto.

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

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

4. Cole as suas chaves IntaSend de sandbox e/ou produção, adicione o webhook no painel da IntaSend e informe a mesma frase de desafio no módulo (veja Configuração).

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

Na instalação, o módulo cria o status de pedido IntaSend payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox IntaSend Pay Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, 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 erradas (nesse caso o método de pagamento fica oculto na finalização de compra), quando a moeda padrão da loja não é aceita, quando não há frase de desafio do webhook e quando o modo produção é usado sem HTTPS. As chaves coladas têm os espaços removidos ao salvar.

IntaSend

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

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

Chaves de API

Obtenha as chaves no painel da IntaSend, em Settings > API Keys, separadamente no painel sandbox e no painel de produção (a seção tem links para os dois). O modo de teste usa as chaves sandbox e a API sandbox; o modo produção usa as chaves de produção e a API de produção. O módulo verifica se a chave pública começa com ISPubKey_, se a chave secreta começa com ISSecretKey_ e se as chaves pertencem ao modo atual: chaves 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: ligado. Desligue-o para aceitar pagamentos reais com as chaves de produção. Enquanto o modo de teste estiver ligado, a finalização de compra mostra TEST MODE - IntaSend sandbox, no real money is charged. abaixo do método de pagamento.

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.

As chaves secretas salvas e a frase de desafio do webhook nunca são mostradas novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo.

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, tanto no sandbox quanto em produção, abra Webhooks e adicione a URL exibida em Webhook URL nesta seção. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_intasend_pay/webhook, possivelmente com um código de idioma, como /en/. Copie a URL exatamente como as configurações a mostram. Informe ali uma frase de desafio e a mesma frase no módulo. Use uma única frase de desafio para o sandbox e para a produção.

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

Limpar segredos salvos: marque Sandbox secret key, Live secret key ou Webhook challenge e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

O módulo reage a estes estados de pagamento informados pela IntaSend. Cada vez, ele consulta a Payment Status API para obter o estado real antes de alterar qualquer coisa:

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.

Avançado

Debug log: registra os eventos de finalização de compra, retorno e webhook em logs/intasend_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Chaves de API e dados de clientes nunca são registrados. Padrão: desligado.

Log: mostra o tamanho e as últimas entradas do log. 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 log. As referências da IntaSend salvas para os pedidos são histórico de pagamentos e são sempre mantidas. Padrão: desligado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão IntaSend (M-Pesa, card)) e confirma. O módulo cria uma finalização de compra na IntaSend para o total do carrinho, na moeda do carrinho, e envia o cliente à finalização de compra hospedada pela IntaSend. Lá, o cliente paga com M-Pesa, cartão ou outro método ativado na sua conta IntaSend. O e-mail do cliente, além do nome, endereço, telefone e país do endereço de cobrança, é passado à IntaSend quando atende às regras de campos da IntaSend. Campos vazios ou inadequados são omitidos. Nesse ponto, ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago quando a IntaSend confirma: o módulo consulta a Payment Status API quando o cliente retorna e quando o webhook chega. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Se o pedido foi colocado em espera, a página 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 contatada naquele momento, uma página de 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 cria o pedido assim que a IntaSend confirma o pagamento.

Se o pagamento falhou, o cliente volta à finalização de compra com a mensagem The payment was not successful. Please try again or choose another payment method. (com o motivo informado pela IntaSend, se houver). 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 novamente. Cada tentativa recebe a sua própria referência da IntaSend.

Se a IntaSend não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com IntaSend could not start the payment: e o motivo informado pela IntaSend, ou com IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. Os detalhes são gravados no log. Um carrinho com total zero não pode ser pago com a IntaSend.

O webhook funciona mesmo com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja. Quando as URLs amigáveis estão desativadas, o cliente retorna pela página inicial da loja, porque a IntaSend não aceita alguns caracteres no endereço de retorno.

O módulo aceita apenas pagamentos únicos. Os reembolsos não são enviados à IntaSend pela loja, e não há cartões salvos, assinaturas nem formulário de pagamento integrado (pop-up). Links de finalização de compra antigos do mesmo carrinho não podem ser cancelados na IntaSend.

Pedidos

Status do pedido

No order yet: o cliente foi enviado à IntaSend e não pagou, ou a IntaSend ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: o pagamento foi confirmado. O pagamento é registrado com o ID da fatura da IntaSend como ID da transação, e uma nota mostra a fatura, o método de pagamento na IntaSend, o valor, o modo (sandbox ou produção) e como foi confirmado (webhook ou retorno do cliente).

IntaSend payment on hold: a IntaSend informou um valor ou uma moeda diferentes do total do carrinho, um pagamento parcial ou um pagamento que chegou depois de o pedido ter sido cancelado. A nota explica isso, e o valor cobrado pela IntaSend é registrado como pagamento quando está na moeda do pedido. Confira o pagamento no painel da IntaSend e atenda o pedido ou reembolse o pagamento. Se o pagamento correto chegar depois, o pedido passa para Payment accepted.

Se chegar um segundo pagamento 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 um duplicado. Um pagamento para um pedido reembolsado adiciona uma nota e não reabre o pedido.

Bloco de pagamento da IntaSend

A página do pedido mostra um bloco IntaSend payment com cada tentativa de finalização de compra do carrinho do pedido (data, referência, finalização de compra na IntaSend, ambiente, valor, fatura e resultado, com o motivo da falha) e as Invoices processed (fatura, estado na IntaSend, valor e resultado). O bloco é somente leitura.

Reembolsos

Os reembolsos não são enviados à IntaSend pela loja. Reembolse o pagamento no painel da IntaSend e registre o reembolso manualmente no PrestaShop.

Chave de licença

O módulo 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 de Modules > Module Manager > VibeFox IntaSend Pay 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 estão a linha Product: presta-payment-intasend e o link Manage licenses and domains in your account, que abre a sua conta 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 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 contatado, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere-a na sua conta 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. 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 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: 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 informada e depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo 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 o Enable/Disable está ligado e se as chaves do modo atual estão preenchidas e pertencem a esse modo: chaves sandbox (com _test) no modo de teste, chaves de produção (com _live) no modo produção. A moeda do carrinho precisa ser aceita. A caixa de status no topo da página de configurações mostra o que está errado. 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: as confirmações do M-Pesa podem levar um momento. O webhook cria o pedido 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 exibida em Webhook URL e se a frase de desafio ali é a mesma de Webhook challenge. O pedido também é criado quando o cliente volta à loja ou clica em Check again.

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

O webhook responde Invalid challenge: a frase de desafio na IntaSend e no módulo não coincidem, ou o webhook não tem frase de desafio.

O webhook responde Verification unavailable, retry later ou Busy, retry later: a IntaSend não pôde ser contatada naquele momento, o carrinho estava sendo confirmado por outra requisição, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). 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 essa fatura pertence ao carrinho. Nada é alterado.

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

O pedido está em IntaSend payment on hold: leia as notas do pedido. O valor ou a moeda pagos eram diferentes do carrinho, o pagamento foi parcial, ou chegou depois de o pedido ser cancelado. Confira o pagamento no painel da IntaSend.

O cliente vê um erro ao escolher a IntaSend: veja o campo Log na página do módulo (ative o 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. 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 carrinho. Se o cliente pagou, o webhook cria o pedido mesmo assim.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox IntaSend Pay 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 log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. As tentativas de finalização de compra e as faturas da IntaSend dos pedidos, assim como o status IntaSend payment on hold, são sempre mantidos. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.

IntaSend é uma marca de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela IntaSend.