Multibanco (Referência MB)

Gera uma referência multibanco com entidade + referência. O cliente paga em qualquer caixa ATM ou via homebanking. A referência é válida por 3 dias.

Usa o SDK oficial. Descarrega em Integrações. Chamadas HTTP directas sem X-VP-Trace são rejeitadas com 403.

Como funciona

Inicias a transacção com customer + items (createPayment).
Geras a referência (generateMultibanco).
Mostras ao cliente: Entidade, Referência e Valor.
O cliente paga na ATM/homebanking.
Recebes um webhook payment.success.

Gerar a referência

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)
const mb = await xpend.generateMultibanco(payment.transactionId)
// mb.entity, mb.reference (contínuo), mb.amount, mb.expiresAt
// Formata referência na UI: "123 456 789" (espaços só na apresentação)

Resposta

{
  "entity": "24000",
  "reference": "123456789",
  "amount": 120.50,
  "expiresAt": "2026-05-13T14:32:00Z"
}

A API devolve reference contínuo. Formata na UI com espaços (ex. 123 456 789) só para leitura — envia o valor exacto de amount ao cliente.

Mostrar ao cliente

Tradicionalmente apresenta-se assim:

Pagamento Multibanco

Entidade

24000

Referência

123 456 789

Valor

120,50 €

Válido até 13/05/2026

Validade

A referência expira em 3 dias a partir do momento em que é gerada. O campo expiresAt vem na resposta de generateMultibanco — não no createPayment.

💡 Boa prática: guarda entity, reference e expiresAt no teu pedido para os mostrares novamente caso o cliente regresse.