MB WAY

O MB WAY é o método de pagamento mais usado em Portugal — o cliente recebe uma notificação push no telemóvel e confirma o pagamento em segundos.

Como funciona

Inicias a transacção (POST /api/v1/payments/init).
Pedes ao cliente o número de telemóvel (formato 9XXXXXXXX).
Disparas a notificação (POST /api/v1/payments/mbway).
O cliente confirma na app MB WAY (4 minutos para confirmar).
Recebes um webhook payment.success.

Implementação completa

// 1. Iniciar transacção
const init = await fetch("https://vorkpay.com/api/v1/payments/init", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VORKPAY_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    orderId: "ORDER-" + Date.now(),
    amount: 49.90,
  }),
}).then(r => r.json())

// 2. Disparar notificação MB WAY
await fetch("https://vorkpay.com/api/v1/payments/mbway", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VORKPAY_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    transactionId: init.transactionId,
    phoneNumber: "912345678",
  }),
})

// 3. (No teu webhook handler) confirmar pagamento
// Vê /docs/webhooks

Validação do telemóvel

O número tem de ser um telemóvel português válido com o formato 9XXXXXXXX (9 dígitos, começa por 9). Se enviares qualquer outro formato recebes 400:

{
  "error": "phoneNumber must be a Portuguese 9-digit mobile (9XXXXXXXX)"
}

Erros comuns

Erro	Causa
`Transaction not found`	O `transactionId` não pertence a esta conta
`Transaction is paid, cannot trigger MB WAY`	A transacção já foi paga ou expirou
`Failed to trigger MB WAY`	Erro a comunicar com a rede bancária — o detail traz a razão

💡 Boa prática: mostra ao cliente um spinner e usa polling em GET /api/v1/payments/status, ou — preferencialmente — espera pelo webhook payment.success.