Download the PHP package brilliantmind/mkesh without Composer

brilliantmind/mkesh

Pacote PHP para a integração MKESH / PagamKesh através do Agregador Ericsson EWP (API "XML over HTTP"), com suporte nativo para Laravel.

O pacote constrói e interpreta todo o XML por si e expõe objectos tipados de pedido/resposta. Autenticação HTTP Basic, transporte PSR-18 (Guzzle por omissão).

Acabou de instalar? Comece aqui

Não há ficheiros para copiar. Models, webhook, job de reconciliação e a própria rota vêm registados no pacote. Falta-lhe fazer três coisas:

1. Instalar e migrar

2. Preencher o .env (detalhe em 3.1)

3. Reagir ao pagamento — em AppServiceProvider::boot():

E já pode cobrar, de qualquer sítio:

O pacote grava o registo, agenda a reconciliação, recebe o callback, responde ao agregador e dispara o evento acima quando o pagamento fecha.

Falta ainda dar ao provedor o URL do webhook — POST /api/mkesh/callback, já registado — e garantir que tem php artisan queue:work a correr.

Três coisas que poupam horas se as ler primeiro:

Índice

1. Requisitos
2. Instalação
3. As duas FRIs de um débito
4. Como funciona o fluxo C2B
5. Guia rápido Laravel — do zero ao primeiro pagamento
6. Usar numa classe Laravel — controller, service, job, command
7. Operações em detalhe — payloads completos
8. Enums
9. Erros
10. Base de dados
11. TLS, IP de origem e cliente HTTP
12. Testes e resolução de problemas

examples/usage.php é um guia anotado com tudo isto num só ficheiro de código.

1. Requisitos

• PHP 8.1+
• Extensões ext-dom e ext-libxml
• Um cliente HTTP PSR-18 (o Guzzle vem incluído)
• Laravel 10, 11 ou 12 (opcional — o pacote funciona em PHP puro)

2. Instalação

Em Laravel o MkeshServiceProvider e a facade Mkesh são registados automaticamente. Publique a configuração:

As migrations vêm dentro do pacote e correm directamente com migrate. Só precisa de as publicar se quiser alterar o schema:

3. Configuração

3.1 Variáveis de ambiente

Referência completa (ficheiro pronto a copiar em .env.example):

3.2 Três regras rígidas do agregador

• O prefixo é obrigatório. Todo o externaltransactionid / referenceid tem de começar pelo seu token de parceiro (ex.: ACME). Defina-o uma vez na configuração e passe ids simples — o pacote prefixa-os, de forma idempotente.
• Os ids têm de ser únicos por service provider. Reutilizar um dá REFERENCE_ID_ALREADY_IN_USE. Use $config->newTransactionId() e grave o valor antes de enviar o pedido.
• O endpoint do callback é registado do lado do provedor, não vai em cada pedido. Dê-lhes o URL; o pacote não coloca <callbackurl> no payload do débito a não ser que active sendCallbackUrl: true.

3.3 Armadilhas na configuração

Estas seis já partiram integrações reais. Vale a pena lê-las antes de preencher o .env.

1. Uma FRI nunca é um URL

Todos os campos *_FRI levam sempre a forma FRI:<valor>/<TIPO>. Nunca um endereço. Os únicos campos que levam https:// são MKESH_BASE_URL e MKESH_CALLBACK_URL.

Sintoma:

2. MKESH_SP_FRI é fixo, é do provedor, e não é o cliente

É a carteira que recebe o dinheiro — o <tofri> do débito. Vem do provedor e não muda de transacção para transacção. Quem se engana aqui costuma pôr lá o número do cliente, e depois todas as cobranças vão parar à conta errada (ou falham com ACCOUNTHOLDER_WITH_FRI_NOT_FOUND).

3. O cliente não vai à configuração

O <fromfri> — quem paga — é construído automaticamente a partir do MSISDN que passa ao pedido. Nunca está no .env:

4. Os *_PATH são caminhos, não URLs

Deixe-os vazios para usar os valores por omissão — só os altere se o seu agregador diferir.

5. O id tem de ser único por tentativa, não por encomenda

Se derivar o external_transaction_id de uma chave estável (nº de encomenda, id de factura), a segunda tentativa de pagamento da mesma encomenda é rejeitada com REFERENCE_ID_ALREADY_IN_USE. Junte sempre um sufixo aleatório:

6. Números mKesh começam por 82 ou 83

Em formato internacional: 2588 2… ou 2588 3…. Um número de outra operadora dá ACCOUNTHOLDER_WITH_FRI_NOT_FOUND — valide antes de cobrar:

3.4 As duas FRIs de um débito

Um débito envolve duas contas, e trocá-las é o erro mais caro da lista acima. Só uma delas está na configuração:

Num pagamento B2C (sptransfer) o sentido inverte-se, e a carteira de origem é outra configuração ainda — MKESH_SP_TRANSFER_FRI, que na folha do provedor é uma FRI diferente da creditada num débito:

3.5 PHP puro (sem Laravel)

Ou a partir de um array, com o mesmo formato do config/mkesh.php:

3.6 Checklist de onboarding

A folha do provedor deixa o bloco por ambiente em branco. Estes valores têm de ser acordados com eles separadamente para teste e produção:

4. Como funciona o fluxo C2B

Cobrar um cliente é assíncrono. A resposta do débito só diz que o pedido foi aceite — o dinheiro ainda não se moveu.

Na prática:

1. debit() devolve PENDING e um approvalid. Grave os ids e pare.
2. O cliente aprova no telemóvel. Não há sinal síncrono deste passo.
3. O agregador faz POST do debitcompletedrequest para o seu endpoint. Tem de responder <ResponseCode>SUCCESS</ResponseCode> — um 200 vazio não é aceite e o callback será reenviado.
4. Se o callback nunca chegar, consulte getTransactionStatus($referenceId) até o estado ficar liquidado.

Os pagamentos B2C (transfer()) são mais simples: uma sptransferresponse com sucesso significa que o dinheiro foi transferido.

5. Guia rápido Laravel

O que o pacote já faz por si

Não há ficheiros para copiar. Isto vem registado assim que instala:

Sobram-lhe quatro passos.

Passo 1 — instalar e configurar

Preencha o .env conforme a secção 3.1.

Passo 2 — dar o URL do webhook ao provedor

https://a-sua-app.co.mz/api/mkesh/callback — já está registado, confirme com php artisan route:list --name=mkesh. Eles configuram-no do lado deles. Confirme também que o IP de saída do seu servidor está autorizado.

Para mudar o caminho, ou registar o seu próprio endpoint:

Passo 3 — cobrar

Ou injectando, se preferir não usar facades:

Passo 4 — saber que foi pago

Este é o passo que se esquece. charge() devolve PENDING: o dinheiro ainda não se moveu e não há resposta síncrona a dizer que sim. O cliente ainda tem de aprovar no telemóvel.

Ponha a lógica de "foi pago" num listener, não à volta do charge():

O evento dispara uma única vez por transacção, venha o resultado do callback ou do job de reconciliação. Um callback reenviado não volta a disparar — é essa a rede de segurança contra entregar a encomenda duas vezes.

Passo 5 — mostrar o estado ao utilizador

O browser não recebe nada do MKESH. Devolva 202 com a referência e deixe o frontend consultar:

Isto consulta a sua base de dados, não o MKESH — o callback e o job já a mantêm actualizada. Não chame getTransactionStatus() a cada polling do browser.

Resumo do ciclo de vida

Antes de ir para produção

• [ ] MKESH_SP_FRI é uma FRI, não um URL nem o número do cliente (3.3)
• [ ] O IP de saída do servidor está autorizado pelo provedor
• [ ] O URL de callback está registado do lado deles e é acessível de fora
• [ ] O webhook devolve <ResponseCode>SUCCESS</ResponseCode> (teste com curl)
• [ ] A fila está a correr (php artisan queue:work) — sem ela o job de reconciliação nunca corre
• [ ] MKESH_VERIFY_SSL=true com o CA do provedor
• [ ] Os ids são únicos por tentativa, não por encomenda (3.3)

6. Usar numa classe Laravel

6.1 Injecção no construtor (recomendado)

MkeshClient está registado no container como singleton — basta declarar o tipo:

6.2 Facade

Métodos disponíveis na facade:

6.3 Controller que inicia um pagamento

6.4 O webhook (já feito)

Não escreva um. O pacote regista o controller e a rota. Ele faz, dentro de uma transacção de base de dados:

1. interpreta o corpo — se não der, grava-o na mesma e devolve 400
2. bloqueia a linha correspondente com lockForUpdate
3. grava o payload cru em mkesh_responses, mesmo que não tenha correspondência
4. liquida a transacção e dispara MkeshTransactionSettled uma única vez
5. devolve <ResponseCode>SUCCESS</ResponseCode>

As três propriedades que isto garante, e que são fáceis de errar à mão:

• Reentrega não duplica. Duas entregas do mesmo callback dão dois registos de auditoria mas um só evento de negócio — a sua encomenda não é entregue duas vezes.
• Callback tardio não inverte o resultado. Um FAILED que chegue depois de um SUCCESSFUL é registado e ignorado.
• Acusa sempre a recepção quando consegue ler o corpo, mesmo sem correspondência local. Caso contrário o agregador reenvia para sempre.

Se precisar mesmo do seu próprio endpoint, desligue o do pacote e reutilize o handler — assim mantém as garantias acima:

6.5 Job de reconciliação (já agendado)

Cobre o ramo "sem resposta do MKESH". O Mkesh::charge() despacha-o sozinho — não tem de fazer nada:

Faz polling ao gettransactionstatus com backoff progressivo (1, 2, 5, 10, 15, 30, 60 minutos) e pára assim que a linha estiver liquidada — seja pelo callback, seja pelo próprio polling. Códigos retentáveis (ErrorCode::isRetryable(), sobretudo TRANSACTION_NOT_FOUND, que aqui significa "ainda não registado") libertam o job para nova tentativa.

Precisa de um worker. Sem php artisan queue:work a correr, uma transacção cujo callback se perca fica PENDING para sempre.

6.6 Command Artisan para reconciliar em lote

Agende-o em routes/console.php:

6.7 Testar sem tocar na rede

Injecte um cliente PSR-18 falso — não é preciso mais nada:

7. Operações em detalhe

Todos os ids mostrados já incluem o prefixo ACME, que o pacote aplica automaticamente a externaltransactionid / providertransactionid / referenceid.

7.1 Debit request — C2B (cobrar um cliente)

Pedido enviado (Content-Type: text/xml):

O referenceid assume por omissão o valor do id externo (como na folha do provedor) e é por ele que o getTransactionStatus() procura a transacção.

Resposta (PENDING) → DebitResponse:

7.2 SP transfer — B2C (pagar a um cliente)

A carteira de origem vem de spTransferSendingFri, que é muitas vezes uma FRI diferente da creditada num débito (FRI:47225552/MM vs FRI:pagamKesh/USER); se não estiver definida, usa a serviceProviderFri.

Pedido enviado:

Resposta → SpTransferResponse:

7.3 Get transaction status (recuperar um resultado)

Use o referenceid de uma operação anterior quando não houve resposta nem callback.

Pedido enviado:

Resposta (SUCESSO):

Resposta (FALHA) — repare que não traz providertransactionid:

7.4 Callback debit-completed

O agregador faz POST disto para o endpoint que registou junto do provedor.

Pedido recebido:

A resposta obrigatória. Um 200 vazio não é aceite e o callback será reenviado:

7.5 Callback transfer-completed (B2C)

O equivalente B2C é entregue da mesma forma:

8. Enums

Todos interpretam defensivamente: um valor desconhecido dá UNKNOWN em vez de lançar excepção, para que um valor novo da plataforma nunca parta o parsing.

8.1 TransactionStatus

Em Eloquent, faça cast directo para o enum:

8.2 ErrorCode

Cobre os códigos que mudam o que a aplicação faz, com a decisão já embutida em vez de ficar à mercê de comparações de strings:

Casos disponíveis, por família:

O enum não lista os 670 códigos de propósito — seria uma segunda cópia do ErrorCodes sem ganho nenhum. Qualquer código fora dele dá ErrorCode::UNKNOWN, enquanto getErrorCode() e ErrorCodes::description() continuam a funcionar sobre a string crua.

8.3 CallbackResponseCode

Na dúvida responda SUCCESS e reconcilie fora de banda com o gettransactionstatus — o tratamento de FAILURE do lado da plataforma não está especificado.

8.4 FriType e os value objects

9. Erros

Erros de negócio chegam como um envelope errorResponse e são lançados como ErrorResponseException.

Hierarquia — todas implementam a interface marcadora MkeshException:

Catálogo completo de códigos

Os 670 códigos da referência da plataforma estão em BrilliantMind\Mkesh\Error\ErrorCodes, e a descrição é acrescentada automaticamente à mensagem da excepção:

Os três erros que vai mesmo encontrar

10. Base de dados

Duas migrations e dois models acompanham o pacote. As migrations correm com php artisan migrate; os models estão em BrilliantMind\Mkesh\Laravel\Models\ e não precisam de ser copiados.

Chaves primárias são UUID

Ambas as tabelas usam UUID ordenado (HasUuids) em vez de auto-incremento. Estes ids saem da base de dados — vão em payloads de fila, logs e tickets de suporte — e um inteiro sequencial revelaria o volume de transacções e convidaria à enumeração. Sendo ordenados (ordenáveis no tempo), o índice não fragmenta como aconteceria com UUID v4 puro.

Consequência prática: onde passar a chave, é string:

payable_id é string, de propósito

A ligação polimórfica usa colunas string, não nullableMorphs():

Um pacote não deve impor o tipo de chave aos models da aplicação. nullableMorphs() forçaria unsignedBigInteger e partiria quem usa UUID ou ULID — com o erro Data truncated for column 'payable_id' assim que tentasse guardar uma chave não numérica. nullableUuidMorphs() teria o problema simétrico: partiria quem usa auto-incremento. string aceita int, UUID e ULID, sem o pacote precisar de saber qual deles usa.

Nomes de tabela e ligação

Migrations e models lêem os mesmos valores da config, por isso renomear num sítio chega:

mkesh_transactions — o livro-razão

A linha é criada antes do pedido sair, para reservar o id localmente.

Métodos e scopes do model:

settle() devolver false é a rede de segurança contra callbacks reenviados: o primeiro resultado nunca é sobrescrito.

mkesh_responses — a auditoria

Propositadamente não é única por transacção, porque os callbacks são reenviados. É precisamente isso que a torna útil: prova o que chegou, quando, e o que respondeu.

Ao apagar uma transacção, o mkesh_transaction_id fica a null mas o registo sobrevive — a prova do que chegou não se apaga com o livro-razão.

11. TLS, IP de origem e cliente HTTP

TLS

O agregador está publicado em HTTPS sobre um IP nu, por isso o certificado não corresponde ao hostname e a verificação por omissão falha. A verificação está ligada por omissão — aponte MKESH_SSL_CA_BUNDLE para o certificado que o provedor fornecer e só desligue (MKESH_VERIFY_SSL=false) contra o ambiente de testes.

IP de origem

O provedor faz whitelist do IP de origem: as chamadas têm de sair do host que registou junto deles. Uma máquina local ou um IP de saída diferente é rejeitado ao nível da rede, antes de qualquer XML ser interpretado.

Cliente HTTP personalizado

MkeshClient::create() liga o Guzzle por si. Para usar outro cliente PSR-18, injecte-o (com as factories PSR-17) pelo construtor:

12. Testes e resolução de problemas

Teste manual pela linha de comandos

Imprime o XML enviado e a resposta interpretada — é a forma mais rápida de resolver um desacordo com o provedor.

Problemas comuns

Licença

MIT — © 2026 BrilliantMind. Ver LICENSE.

Suporte: [email protected]