360Pay – Pagamentos por Carteiras Móveis para MasterStudy

By hmorais

0+ active installationsVersion 1.5.0

Receba pagamentos por M-Pesa, e-Mola e mKesh diretamente no checkout do MasterStudy LMS, sem precisar do WooCommerce.

Description

O 360Pay permite que os seus alunos paguem cursos do MasterStudy LMS com a carteira móvel, no próprio checkout do site. O aluno escolhe a carteira, escreve o número de telefone e confirma o pagamento no telemóvel. Assim que a carteira confirma, o acesso ao curso é libertado automaticamente.

Foi pensado para escolas, formadores e plataformas de ensino em Moçambique.

Principais funcionalidades

  • Checkout nativo do MasterStudy – não precisa do WooCommerce. As encomendas são criadas no próprio MasterStudy.
  • Várias carteiras móveis – M-Pesa (Vodacom) já incluída. e-Mola, mKesh ou outra carteira com API podem ser configuradas manualmente.
  • Pagamento confirmado no servidor – a encomenda fica pendente até a API da carteira confirmar o pagamento. Referência, valor, moeda, aluno, curso e estado são validados antes de libertar o acesso.
  • Matrícula automática – o aluno é inscrito no curso logo após a confirmação.
  • Confirmação por callback e verificação automática – recebe as notificações da carteira através da REST API e, se alguma falhar, verifica o estado sozinho através do WP-Cron.
  • Faturas em PDF – emissão automática de fatura com os dados da sua empresa (NUIT, endereço, logótipo e assinatura) e envio por e-mail ao aluno.
  • Painel de gestão completo – transações com filtros, pesquisa, paginação e exportação para CSV, registos técnicos e página de diagnóstico.
  • Seguro por defeito – o site nunca pede o PIN nem códigos da carteira; chaves e dados sensíveis aparecem mascarados no painel e nos registos.

Como funciona

  1. O aluno escolhe “Carteiras móveis” no checkout e seleciona a sua carteira.
  2. Escreve o número de telefone associado à carteira.
  3. Recebe no telemóvel o pedido de pagamento e confirma com o PIN, na própria carteira.
  4. O 360Pay recebe a confirmação, conclui a encomenda e inscreve o aluno no curso.

Aviso legal

Este é um plugin independente, desenvolvido pela Agência +360º. Não é afiliado, aprovado nem patrocinado pela MasterStudy LMS / StylemixThemes nem pela Vodacom / M-Pesa. “MasterStudy” e “M-Pesa” são marcas dos respetivos proprietários e são usadas aqui apenas para identificar os serviços com que o plugin se integra.

Serviços externos

Para iniciar e confirmar pagamentos, o plugin comunica com as APIs das carteiras móveis. Dados de cartão, PIN ou códigos de confirmação nunca passam pelo site.

1. API M-Pesa da Vodacom Moçambique (carteira incluída)

  • O que é e para que serve: a plataforma oficial de pagamentos M-Pesa da Vodacom Moçambique. É usada para enviar o pedido de pagamento C2B (Cliente para Empresa) para o telemóvel do aluno e para confirmar o estado da transação, de modo a libertar o curso apenas depois de o pagamento ser confirmado no servidor.
  • Que dados são enviados e quando: o número de telefone do cliente (MSISDN), o valor, a moeda e uma referência única da transação. São enviados (a) quando o aluno clica em “Pagar” no checkout e (b) depois, nas verificações automáticas do estado do pagamento (WP-Cron).
  • Endereços utilizados: https://api.vm.co.mz:18352 (produção) e https://api.sandbox.vm.co.mz:18352 (testes) para o pedido de pagamento; https://api.vm.co.mz:18353 e https://api.sandbox.vm.co.mz:18353 para a consulta do estado da transação.
  • Termos e condições: https://www.vm.co.mz/artigo/termos-e-condicoes
  • Política de privacidade: https://www.vm.co.mz/privacidade
  • Portal de programadores: https://developer.mpesa.vm.co.mz/

2. Outras carteiras configuradas pelo administrador (opcional)

  • O que é e para que serve: o plugin só comunica com outras carteiras (por exemplo e-Mola, mKesh ou uma carteira personalizada) se o administrador do site as ativar e configurar, indicando os endereços e as credenciais do fornecedor. São usadas para o mesmo fim: pedir o pagamento e confirmar o seu estado.
  • Que dados são enviados e quando: os mesmos dados (telefone, valor, moeda e referência), enviados ao endereço configurado pelo administrador, nos mesmos momentos descritos acima.
  • Termos e privacidade: dependem do fornecedor escolhido. O administrador é responsável por ler e cumprir os termos e a política de privacidade desse fornecedor antes de o ativar.

Para programadores

Endpoints REST:

  • Callback da carteira: /wp-json/ms-wallet-payments/v1/callback/{wallet_slug}
  • Estado de uma transação: /wp-json/ms-wallet-payments/v1/status/{transaction_reference}
  • Reprocessar callback (apenas administradores): /wp-json/ms-wallet-payments/v1/reprocess/{transaction_reference}
  • Iniciar pagamento: /wp-json/ms-wallet-payments/v1/start
  • Carteiras ativas: /wp-json/ms-wallet-payments/v1/wallets

Filtros disponíveis para adaptar o checkout, a criação e conclusão da encomenda e a matrícula:

  • mswp_masterstudy_checkout_context
  • mswp_masterstudy_create_pending_order
  • mswp_masterstudy_complete_order
  • mswp_masterstudy_enroll_user
  • mswp_masterstudy_mark_order_not_paid
  • mswp_admin_parent_slug – coloca o menu do 360Pay dentro de outro menu (por exemplo o do MasterStudy).

Shortcodes de recurso, para testes:

  • [mswp_wallet_checkout course_id="123" amount="1500" currency="MZN"] – botão de pagamento.
  • [mswp_payment_status] – estado do pagamento.

Créditos

  • Fonte Manrope – SIL Open Font License 1.1.
  • Ícones baseados no Lucide (https://lucide.dev) – licença ISC.

Installation

  1. No painel do WordPress, vá a Plugins → Adicionar novo, pesquise por “360Pay” e clique em Instalar e depois Ativar. Em alternativa, envie a pasta mais360-mobile-wallet-payments-for-masterstudy para /wp-content/plugins/ e ative o plugin.
  2. Confirme que o MasterStudy LMS está ativo.
  3. Abra o menu 360Pay → Configurações, ative o gateway e escolha o ambiente (Sandbox para testes ou Produção).
  4. Em 360Pay → Carteiras, configure pelo menos uma carteira. Para o M-Pesa, introduza o Service Provider Code, a API Key e a Public Key do portal da Vodacom.
  5. Em 360Pay → Diagnóstico, copie o URL de callback de cada carteira e configure-o no portal do fornecedor.
  6. Faça um pagamento de teste em Sandbox antes de passar para Produção.

FAQ

Preciso do WooCommerce?

Não. O 360Pay funciona diretamente no checkout nativo do MasterStudy LMS e cria as encomendas no próprio MasterStudy.

Que carteiras móveis são suportadas?

O M-Pesa (Vodacom Moçambique) vem incluído. O e-Mola, o mKesh ou qualquer outra carteira com API podem ser adicionados e configurados manualmente.

O site pede o PIN da carteira?

Não. O aluno só escreve o número de telefone. O pagamento é confirmado no telemóvel, na própria carteira. O PIN e os códigos de confirmação nunca chegam ao site.

Quando é que o aluno tem acesso ao curso?

Só depois de a API da carteira confirmar o pagamento, seja pela notificação (callback) ou pela verificação automática. Até lá, a encomenda fica pendente.

Os planos de assinatura com período experimental funcionam?

Sim. Se o plano tiver período experimental e o aluno ainda não o tiver usado nesse plano, nada é cobrado: o acesso aos cursos do plano é libertado de imediato e termina no fim do período experimental. Para continuar, o aluno compra o plano de novo e paga com a carteira móvel.

Posso testar sem cobranças reais?

Sim. Escolha o ambiente Sandbox nas configurações e use as credenciais de teste do portal da carteira. Quando estiver tudo a funcionar, mude para Produção.

O que significa “serviço temporariamente indisponível (erro de gateway)”?

A API da carteira, ou um servidor intermédio, respondeu com um erro HTTP 5xx e o pedido não chegou ao serviço de pagamento. O plugin tenta de novo automaticamente uma vez e mantém a transação pendente; o aluno pode tentar outra vez dentro de momentos.

As faturas cumprem os requisitos em Moçambique?

A fatura inclui o NUIT, o endereço, o logótipo e a assinatura da sua empresa, com numeração sequencial e prefixo configurável. Confirme com o seu contabilista os requisitos fiscais aplicáveis ao seu negócio.

Screenshots

Changelog

1.5.0

  • Novo menu “360Pay” no painel, com o ícone do plugin e acesso direto a cada secção.
  • Interface de administração totalmente redesenhada, com a fonte Manrope e ícones próprios.
  • Configurações organizadas por secções, com interruptores e campos agrupados.
  • Transações e registos com separadores por estado, pesquisa, filtros recolhíveis e paginação.
  • Novo cartão de estado no Diagnóstico e página de detalhe da transação reorganizada.
  • Os avisos do WordPress e de outros plugins passam a aparecer por baixo do cabeçalho do 360Pay.
  • Descrição do plugin em português.
  • Pagamento em duas fases: o checkout mostra logo o progresso e acompanha o estado mesmo que a ligação ao M-Pesa demore ou seja cortada.
  • Temporizador com linha de contagem decrescente, definido pelo tempo para confirmar das configurações, e ecrãs claros de sucesso e de erro com o motivo (saldo insuficiente, pagamento cancelado, tempo esgotado, número inválido, etc.).
  • Correção: o pedido ao M-Pesa deixava de esperar ao fim de 30 segundos (“cURL error 28”) enquanto o cliente ainda confirmava no telemóvel; agora espera pelo menos 90 segundos e, sem resposta, confirma o estado na API de consulta do M-Pesa.
  • Correção: códigos de resposta do M-Pesa interpretados de acordo com a documentação oficial (ex.: INS-5 cancelado, INS-9 tempo esgotado, INS-2006 saldo insuficiente).
  • Período experimental dos planos de assinatura também com carteiras móveis: nada é cobrado, o aluno tem acesso aos cursos do plano até ao fim do período e o checkout mostra a data e o valor do plano depois disso. Cada aluno tem o período experimental de um plano apenas uma vez. A quem já o usou, o checkout deixa de mostrar “Free Trial” e 0 e passa a mostrar o preço do plano no resumo, no total e no botão Pagar.
  • Correção: assinaturas pagas por carteira móvel passam a durar um período completo do plano (antes terminavam no fim do período experimental).
  • Correção: o ID de um plano de assinatura deixa de poder ser confundido com o ID de um curso na matrícula.
  • Ao ativar uma assinatura (paga ou em período experimental), o aluno fica logo matriculado nos cursos do plano, incluindo os planos por categoria e de acesso total, e os cursos aparecem em “Cursos matriculados” ligados à assinatura; quando ela termina, o acesso é bloqueado pelo MasterStudy. As assinaturas já existentes são sincronizadas na próxima visita do aluno.
  • Quando a assinatura é cancelada, expira ou é apagada no painel, o acesso aos cursos do plano termina e esses cursos saem de “Cursos matriculados”. Corrige o caso em que o MasterStudy considerava um curso “comprado” por engano e mantinha o acesso.
  • “Valor a pagar” aparece logo ao abrir o checkout e é atualizado automaticamente ao aplicar ou remover um cupão.
  • Ícone do 360Pay nas configurações de métodos de pagamento do MasterStudy LMS.
  • Correção: cancelar uma assinatura paga com carteira móvel dava o erro “Invalid payment method”.
  • Quando a API de consulta de estado do M-Pesa não aceita ligações (comum no Sandbox), as consultas ficam suspensas por 10 minutos em vez de se repetirem a cada verificação.
  • Segurança: o valor a cobrar e os cursos libertados são sempre calculados no servidor, a partir do carrinho do MasterStudy; valores, cursos ou planos enviados pelo browser deixam de ser aceites.
  • O método de pagamento aparece como “Carteiras móveis”, sem texto entre parênteses.

1.4.3

  • Primeira versão pública no WordPress.org.
  • Seletor de carteiras com logótipos lado a lado e campo de telefone que se adapta à carteira escolhida.
  • Mensagem clara e nova tentativa automática quando a API da carteira devolve um erro HTTP 5xx.
  • O plugin deixa de gravar na opção de configurações do MasterStudy; o método de pagamento é exposto através de um filtro só de leitura.
  • A desinstalação remove também a opção interna de migração.