Poket / MedX — API de Integração

Introdução A API REST da Poket para integrar carteira, pagamentos, depósitos, levantamentos e KYC.

A Poket (rede MedX) é uma carteira digital em Moçambique. Esta API permite a apps e sistemas externos autenticar utilizadores, consultar saldos, depositar e levantar via M-Pesa, transferir, cobrar por QR e gerir KYC/KYB. Todas as respostas são JSON; toda a comunicação é sobre HTTPS.

Base URL	https://api.medx.co.mz
Formato	JSON (UTF-8). Uploads de KYC usam `multipart/form-data`.
Autenticação	JWT `Bearer` (ver Autenticação)
Moedas	MZN (Metical) · MEDX (token da rede)
Ambiente	Produção. Não há sandbox público — peça credenciais de parceiro.

Acesso de parceiro. A maioria dos endpoints exige um utilizador autenticado. Para integrações servidor-a-servidor (parceiros), contacte a equipa Poket para obter credenciais e âmbito. Endpoints de administração/staff não fazem parte desta API pública.

Início rápido

Registar / autenticar o utilizador → obtém um accessToken (JWT).

Enviar o token em todos os pedidos: Authorization: Bearer <accessToken>.

Chamar os endpoints de carteira, depósito, transferência, etc.

Renovar o token com /api/auth/refresh quando expirar (~15 min).

# 1) Login
curl -X POST https://api.medx.co.mz/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"+258841234567","pin":"123456"}'

# 2) Usar o token
curl https://api.medx.co.mz/api/wallet \
  -H 'Authorization: Bearer eyJhbGciOi...'

Autenticação

A API usa JWT. O accessToken dura ~15 minutos; use o refreshToken para renovar sem novo login. O login pode exigir OTP por SMS (configurável); a resposta indica requiresOtp.

POST/api/auth/register/personalpúblico

Registar utilizador pessoal. Cria conta + carteiras + perfil KYC nível 1.

POST/api/auth/register/enterprisepúblico

Registar empresa (conta MERCHANT) + perfil KYB. Ver Enterprise.

POST/api/auth/loginpúblico

POST/api/auth/login/verify-otppúblico

Confirmar o código OTP enviado por SMS.

POST/api/auth/login/resend-otppúblico

Reenviar o OTP.

POST/api/auth/refreshpúblico

Trocar o refreshToken por um novo accessToken.

POST/api/auth/logoutBearer

Terminar a sessão atual.

POST/api/auth/change-pinBearer

Alterar o PIN do utilizador.

GET/api/auth/sessionsBearer

Listar sessões ativas. DELETE /api/auth/sessions/{id} revoga uma.

Login → resposta

POST /api/auth/login
{ "identifier": "+258841234567", "pin": "123456" }

// requiresOtp = false → login direto
{
  "userId": "uuid", "userType": "PERSONAL", "role": "ROLE_USER",
  "token": "eyJ...", "refreshToken": "eyJ...",
  "expiresIn": 900, "sessionId": "uuid", "requiresOtp": false
}
// requiresOtp = true → confirmar com /login/verify-otp { sessionId, otp }

O identifier aceita email ou telefone (com ou sem +258 / +27). Números são normalizados no servidor.

Convenções & erros

Cabeçalhos	`Authorization: Bearer <token>` · `Content-Type: application/json`
Datas	ISO-8601 UTC (`2026-06-09T19:45:06Z`)
Montantes	Decimais como string/número; `assetCode` indica a moeda (`MZN`/`MEDX`)
Paginação	`?page=0&size=50` (quando aplicável)
Idempotência	Pagamentos usam uma `reference` única; repetir a mesma referência não duplica a operação

Códigos HTTP

Código	Significado
`200 / 201`	Sucesso
`400`	Pedido inválido (validação)
`401`	Token ausente/expirado
`403`	Sem permissão / KYC insuficiente
`404`	Não encontrado
`409 / 422`	Conflito / regra de negócio (ex.: saldo insuficiente, limite excedido)

// erro típico
{ "timestamp":"2026-06-09T19:45:06Z", "status":422,
  "error":"Saldo insuficiente", "path":"/api/withdrawals" }

Carteira

Cada utilizador tem carteiras por moeda (MZN, MEDX), cada uma com endereço on-chain e saldos available/locked.

GET/api/walletBearer

Listar carteiras + saldos do utilizador. (Alias: /api/wallets, /api/me/wallets.)

GET/api/wallet/{assetCode}Bearer

Carteira de uma moeda específica.

GET/api/wallet/balances/fullBearer

Saldos detalhados (disponível, bloqueado, on-chain).

GET /api/wallet
[
  { "wallet": { "assetCode":"MZN", "blockchainAddress":"0x…" },
    "balance": { "available":"1250.00", "locked":"0.00" } },
  { "wallet": { "assetCode":"MEDX", "blockchainAddress":"0x…" },
    "balance": { "available":"300.00", "locked":"0.00" } }
]

Transferências

Transferência interna instantânea entre utilizadores Poket, por telefone, email ou ID.

GET/api/transfers/recipientBearer

Resolver o destinatário (nome) por telefone/email antes de enviar.

POST/api/transfers/initiateBearer

Iniciar a transferência (devolve resumo + se exige OTP/PIN).

POST/api/transfers/confirmBearer

Confirmar com PIN/OTP → executa.

GET/api/transfers/{id}Bearer

Detalhe/estado de uma transferência.

POST /api/transfers/initiate
{ "recipient":"+258841234567", "assetCode":"MEDX",
  "amount":"100.00", "description":"Pagamento" }

POST /api/transfers/confirm
{ "transferId":"uuid", "pin":"123456" }   // ou { otp:"123456" }

Depósitos

Carregar a carteira via M-Pesa (C2B). O utilizador recebe um pedido de pagamento M-Pesa no telefone; ao confirmar, a carteira é creditada.

POST/api/depositsBearer

Iniciar um depósito M-Pesa (C2B).

GET/api/deposits/meBearer

Listar os depósitos do utilizador.

GET/api/deposits/{id}Bearer

Detalhe de um depósito.

GET/api/deposits/{id}/mpesa/statusBearer

Consultar o estado M-Pesa do depósito.

GET/api/deposits/mpesa/customer-nameBearer

Validar o nome do titular M-Pesa de um número.

POST /api/deposits
{ "channel":"MPESA", "amount":"500.00", "msisdn":"+258841234567" }
// → { "id":"uuid", "status":"PENDING", "reference":"PR-…" }

Levantamentos

Retirar saldo para M-Pesa (B2C, instantâneo) ou conta bancária (liquidação manual). No M-Pesa o token MEDX correspondente é queimado on-chain na liquidação.

POST/api/withdrawalsBearer

Iniciar levantamento (channel: MPESA | BANK).

GET/api/withdrawalsBearer

Listar levantamentos do utilizador.

GET/api/withdrawals/{id}Bearer

Detalhe/estado de um levantamento.

GET/api/bank-accountsBearer

Listar contas bancárias guardadas. POST adiciona (NIB).

// M-Pesa (instantâneo)
POST /api/withdrawals
{ "channel":"MPESA", "assetCode":"MZN", "amount":"20.00",
  "payoutMsisdn":"+258851935325" }

// Banco (liquidação manual)
POST /api/withdrawals
{ "channel":"BANK", "assetCode":"MZN", "amount":"5000.00",
  "bankAccountId":"uuid" }

Os levantamentos respeitam os limites por nível de KYC e exigem saldo disponível.

QR & Pagamentos

Gerar QR para receber, ler QR para pagar, e pedidos de pagamento (push). Empresas têm QR estático próprio (ver Enterprise).

POST/api/qr/generateBearer

Gerar um QR de cobrança (valor opcional).

GET/api/qr/me/activeBearer

QR ativo do utilizador.

GET/api/qr/{token}/imagepúblico

Imagem PNG do QR (impressão/partilha).

POST/api/qr/{token}/scanBearer

Ler um QR → cria um pedido de pagamento.

GET/api/my/payment-requestsBearer

Pedidos de pagamento recebidos.

POST/api/payment-requests/{id}/confirmBearer

Pagar um pedido. /reject recusa.

POST/api/merchant/pay/{reference}Bearer

Pagar por referência de comerciante.

KYC / KYB

Verificação de identidade (pessoal: níveis 1–3) e de empresa (KYB: níveis 11–13). Cada nível tem documentos exigidos e limites de transação crescentes.

GET/api/kyc/meBearer

Estado KYC atual (nível, tier, status).

GET/api/kyc/me/requirementsBearer

Documentos exigidos para o próximo nível.

POST/api/kyc/documents/uploadBearer

multipart/form-data: documentType, documentNumber, file (PDF/JPG/PNG, ≤15 MB).

GET/api/kyc/documentsBearer

Documentos submetidos. /{id}/files lista ficheiros.

POST/api/kyc/me/submitBearer

Submeter para revisão de compliance.

GET/api/kyc/me/eventsBearer

Histórico de eventos KYC.

Pessoal	1 BASICO · 2 VERIFICADO · 3 PREMIUM
Empresa (KYB)	11 STARTER · 12 BUSINESS · 13 ENTERPRISE

Enterprise

Contas de empresa (ROLE_MERCHANT) gerem colaboradores, pagamentos agendados, folha de pagamento e QR empresarial. Registo via /api/auth/register/enterprise.

GET/api/enterprise/collaboratorsBearer

Colaboradores. POST cria, PUT/DELETE /{id} edita/desativa.

POST/api/enterprise/scheduled-paymentsBearer

Pagamentos únicos/recorrentes. Ações: /{id}/pause|resume|cancel|run-now.

POST/api/enterprise/payrollBearer

Folha de pagamento (paga todos os colaboradores ativos). Ações idem.

GET/api/enterprise/payments/executionsBearer

Histórico auditável de execuções (paginado).

POST/api/enterprise/qr/generateBearer

QR empresarial estático. /{token}/image, /{token}/scan.

GET/api/enterprise/by-nuit/{nuit}Bearer

Procurar empresa por NUIT. /search?q=, /{userId}/profile.

Documentação detalhada do registo e KYB empresarial: ver os guias Enterprise — Registo & KYB e Enterprise — Doc. Completa.

Bridge (on-chain)

Movimentar MEDX entre a rede privada (interna) e a rede pública (on-chain).

POST/api/bridge/transfer-publicBearer

Enviar MEDX para a rede pública (queima na privada).

POST/api/bridge/return-to-privateBearer

Trazer MEDX da rede pública para a carteira interna.

POST/api/bridge/withdrawBearer

Levantamento on-chain para um endereço externo.

GET/api/bridge/transactionsBearer

Histórico de operações de bridge.

Explorador (blockchain)

Consulta pública, só-leitura, da rede MedX.

GET/api/explorer/statspúblico

Estatísticas da rede.

GET/api/explorer/blockspúblico

Blocos recentes. /block/{number}, /block/latest.

GET/api/explorer/tx/{hash}público

Detalhe de uma transação on-chain.

GET/api/explorer/address/{address}público

Atividade de um endereço. /balance/{address}.

GET/api/explorer/transferspúblico

Transferências recentes.

Assets & Status

GET/api/assetspúblico

Moedas suportadas. /active, /{code}.

GET/api/statuspúblico

Estado da plataforma (manutenção): { maintenance, message }.

Histórico & Notificações

GET/api/historyBearer

Extrato unificado (transferências, depósitos, levantamentos).

GET/api/history/transfers/{id}Bearer

Detalhe. Idem /deposits/{id}, /withdrawals/{id}.

POST/api/notifications/tokenBearer

Registar o token de dispositivo (FCM) para push.

A plataforma notifica o utilizador por push (FCM) e WebSocket em eventos de depósito, transferência, levantamento e KYC.

Fluxo — Depósito M-Pesa

POST /api/deposits com {channel:"MPESA", amount, msisdn} → cria depósito PENDING.

O utilizador recebe o pedido M-Pesa no telefone e confirma (PIN M-Pesa).

A plataforma recebe o callback M-Pesa, credita a carteira e cunha MEDX on-chain.

Estado fica COMPLETED; consultar via GET /api/deposits/{id} ou push.

Fluxo — Transferência

GET /api/transfers/recipient → confirmar o nome do destinatário.

POST /api/transfers/initiate → resumo + se exige OTP/PIN.

POST /api/transfers/confirm com PIN/OTP → executa instantaneamente.

Ambas as carteiras são atualizadas; evento auditável + push.

Fluxo — Levantamento

POST /api/withdrawals (MPESA instantâneo ou BANK manual).

Verificação de saldo + limites de KYC; débito da carteira.

M-Pesa: disbursement B2C imediato + queima de MEDX on-chain. Banco: liquidação manual pela tesouraria.

Estado final em GET /api/withdrawals/{id} + push.

Fluxo — Pagamento por QR

Recebedor: POST /api/qr/generate (ou QR empresarial) → mostra o QR.

Pagador: POST /api/qr/{token}/scan → cria um pedido de pagamento.

Pagador confirma: POST /api/payment-requests/{id}/confirm (PIN).

Transferência executada; ambos notificados.

Fluxo — KYC / KYB

GET /api/kyc/me/requirements → documentos do próximo nível.

POST /api/kyc/documents/upload (multipart) por cada documento.

POST /api/kyc/me/submit → entra na fila de compliance.

Após revisão, o nível/limites são atualizados; GET /api/kyc/me + push.

Poket é a carteira digital da rede MedX. Esta documentação cobre a API pública de integração; endpoints de administração e operações internas não estão incluídos. Para credenciais de parceiro e suporte de integração, contacte a equipa Poket.