VibeFox IntaSend for WooCommerce — Ajuda

Requisitos

WordPress: 6.2 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

HTTPS: a IntaSend exige HTTPS para pagamentos em produção e para webhooks. A página de configurações avisa quando o modo de produção está ativado e o endereço da 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 a IntaSend sobre 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 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_intasend_pay para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > IntaSend > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Cole suas chaves IntaSend de sandbox e/ou de produção, adicione o webhook no painel da IntaSend e insira a mesma frase de desafio no plugin (veja Configuração).

6. Ative Enable/Disable. Teste um pagamento com Test mode ativado e depois desmarque Test mode para aceitar pagamentos reais.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > IntaSend. 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 incorretas (o método de pagamento fica oculto na finalização de compra), quando a moeda da loja não é aceita, quando não há frase de desafio do webhook e quando o modo de produção é usado sem HTTPS. Na lista de métodos de pagamento, a IntaSend aparece como "precisa de configuração" até que as chaves do modo atual estejam corretas. As chaves coladas são limpas de espaços ao salvar.

Geral

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. Padrão: IntaSend (M-Pesa, card).

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 de sandbox e no de produção. O modo de teste usa as chaves e a API de sandbox; o modo de produção usa as chaves e a API de produção. O plugin 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 de sandbox contêm _test, chaves de produção contêm _live. Se não pertencerem, o método de pagamento fica oculto e a caixa de status explica o motivo.

Test mode: Use the IntaSend sandbox (no real money is charged). Padrão: ativado. Desmarque para aceitar pagamentos reais com as chaves de produção. Enquanto o modo de teste estiver ativado, 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 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 API de Status de Pagamento.

Live publishable key: começa com ISPubKey_live.

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

Webhook

O webhook informa à sua loja que um pagamento foi feito, mesmo quando o cliente não volta para a loja (navegador fechado, M-Pesa confirmado depois). No painel da IntaSend, no sandbox e em produção, abra Webhooks e adicione a URL mostrada nesta seção das configurações. Ela tem este formato: https://your-site/wc-api/intasend_pay/. Informe ali uma frase de desafio e a mesma frase no plugin. Use uma única frase 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ão confirmados somente quando o cliente volta para a 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.

O plugin reage aos estados de pagamento informados pela IntaSend. Cada vez, ele consulta a API de Status de Pagamento para saber o estado real antes de alterar o pedido:

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 OK e são ignoradas, para que a IntaSend não desative o webhook.

Avançado

Debug log: Log checkout, return and webhook events em WooCommerce > Status > Logs, origem wcp_intasend_pay. Erros são sempre registrados. Chaves de API e dados de clientes nunca são registrados. Padrão: desativado.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. As referências da IntaSend salvas nos pedidos são histórico de pagamentos e são sempre mantidas. Desativar o plugin nunca apaga nada. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão IntaSend (M-Pesa, card)) e faz o pedido. O plugin cria uma finalização de compra na IntaSend para o total do pedido, na moeda do pedido, 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. E-mail, nome, endereço, telefone e país de cobrança são passados à IntaSend quando atendem às regras de campo dela. Campos vazios ou inadequados são omitidos.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago quando a IntaSend confirma: o plugin consulta a API de Status de Pagamento quando o cliente retorna e quando o webhook chega. Se o pagamento ainda não estiver confirmado, a página de pedido recebido 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. Se o pedido foi colocado em espera, ela mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed.

Se o pagamento falhou ou o cliente voltou sem pagar, ele retorna à finalização de compra (ou à página Pay for order) com a mensagem The payment was not successful. Please try again or choose another payment method. (com o motivo da IntaSend, se houver) ou The payment was not completed. Please try again or choose another payment method. O cliente pode pagar o pedido novamente. Cada tentativa recebe uma referência própria da IntaSend.

Se a IntaSend não conseguir iniciar o pagamento, o cliente vê IntaSend could not start the payment: com 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.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita apenas pagamentos únicos. Os reembolsos não são enviados à IntaSend pelo WooCommerce, 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 pedido não podem ser cancelados na IntaSend.

Pedidos

Status do pedido

Pending payment: o cliente foi enviado à IntaSend e ainda não pagou, ou a IntaSend ainda não confirmou o pagamento.

Processing or Completed: o pagamento foi confirmado. O WooCommerce define o status usual de um pedido pago. A nota do pedido 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). O ID da transação é o ID da fatura da IntaSend.

On hold: a IntaSend informou valor ou moeda diferentes do total do pedido, um pagamento parcial ou um pagamento que chegou depois de o pedido ter sido cancelado. A nota do pedido explica. Verifique o pagamento no painel da IntaSend e conclua o pedido ou reembolse o pagamento.

Failed: a última tentativa de pagamento falhou. A nota mostra o motivo informado pela IntaSend. O cliente pode tentar de novo.

Se um segundo pagamento chegar para um pedido já pago, o pedido não é alterado novamente. Uma nota pede que você o reembolse no painel da IntaSend, se for uma duplicata. Um pagamento para um pedido reembolsado adiciona uma nota e não reabre o pedido.

Reembolsos

Os reembolsos não são enviados à IntaSend pelo WooCommerce. Reembolse o pagamento no painel da IntaSend e registre o reembolso manualmente no WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > IntaSend. 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 inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um único 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, a IntaSend não é mostrada 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. Os gerentes da loja conectados ainda veem o método 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. 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 precisam de renovação. O status é verificado novamente de forma automática em segundo plano.

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 de produção. A moeda da loja precisa ser aceita. A caixa de status no topo da página de configurações mostra o que está errado.

O pagamento foi feito, mas o pedido continua em Pending payment: as confirmações do M-Pesa podem levar um momento. O webhook confirma 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 mostrada nas configurações e se a frase de desafio lá é a mesma de Webhook challenge.

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

O webhook responde Invalid challenge: a frase de desafio na IntaSend e no plugin são diferentes.

O webhook responde Verification unavailable, retry later ou Busy, retry later: a IntaSend não pôde ser acessada naquele momento, ou o pedido estava sendo confirmado por outra requisição. A IntaSend tenta o webhook novamente.

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

O pedido está On hold: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido, o pagamento foi parcial ou chegou depois de o pedido ser cancelado. Verifique o pagamento no painel da IntaSend.

O cliente vê um erro ao fazer o pedido: ative o Debug log e veja WooCommerce > Status > Logs, origem wcp_intasend_pay. O total do pedido precisa ser maior que zero. 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 ou um parâmetro de idioma nele.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver 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 no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o 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 somente se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

IntaSend é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela IntaSend.