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.

Usa o SDK oficial. Descarrega em Integrações → Node.js ou PHP. O SDK assina cada pedido com X-VP-Trace — chamadas fetch ou curl directas devolvem 403.

Como funciona

Inicias a transacção com customer + items do checkout (createPayment).
Pedes ao cliente o número de telemóvel (formato 9XXXXXXXX).
Disparas a notificação (triggerMbway).
O cliente confirma na app MB WAY (4 minutos para confirmar).
Recebes um webhook payment.success.

Implementação (3 linhas no teu backend)

require('dotenv').config()
const xpend = require('./xpend')

const customer = {
  name: 'João Silva',
  email: 'joao@email.com',
  phone: '912345678',
  address: 'Rua das Flores 12',
  city: 'Lisboa',
  postalCode: '1000-001',
  country: 'Portugal',
}
const items = [
  { id: 'sku-1', name: 'Ténis Running', quantity: 1, priceInCents: 4990 },
]
// Captura fbclid/UTMs da URL do checkout (browser) ou repassa do teu funil
const trackingParameters = Object.fromEntries(
  [...new URLSearchParams(window.location.search)].filter(([k]) =>
    ['utm_source','utm_medium','utm_campaign','utm_content','utm_term','fbclid','gclid','ttclid','src','sck'].includes(k)
  )
)
const payment = await xpend.createPayment('ORDER-123', 49.90, customer, items, trackingParameters)
await xpend.triggerMbway(payment.transactionId, '912345678')
// O cliente confirma na app MB WAY (4 min). Preferir webhook payment.success.

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, sem +351 nem espaços). Se enviares qualquer outro formato recebes 400:

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

Erros comuns

Erro	Causa
`INTEGRATION_SIGNATURE_REQUIRED`	Pedido sem SDK / sem `X-VP-Trace`
`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

💡 Boa prática: espera pelo webhook payment.success em vez de polling. Ver /docs/webhooks.