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.

Como funciona

  1. Inicias a transacção (POST /api/v1/payments/init).
  2. Geras a referência (POST /api/v1/payments/multibanco).
  3. Mostras ao cliente: Entidade, Referência e Valor.
  4. O cliente paga na ATM/homebanking.
  5. Recebes um webhook payment.success.

Gerar a referência

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-456", amount: 120.50 }),
}).then(r => r.json())

const ref = await fetch("https://vorkpay.com/api/v1/payments/multibanco", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VORKPAY_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ transactionId: init.transactionId }),
}).then(r => r.json())

console.log(ref.entity)     // "24000"
console.log(ref.reference)  // "123456789"
console.log(ref.expiresAt)  // "2026-05-13T..."

Resposta

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

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. Após esse prazo, o pagamento ainda pode ser feito mas o webhook pode chegar mais tarde — não confies só no expiresAt para fechar o pedido.

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