Multibanco

O Multibanco é a rede portuguesa de caixas eletrônicos e de vouchers de pagamento pelo home banking. A OkanePay devolve o trio Entidade + Referência + Valor, que o cliente paga em qualquer caixa eletrônico, no app do banco ou pelo internet banking. Liquidação: 1–3 dias úteis.

#O fluxo, de relance

text

1. POST /v1/payments  ──────▶  a OkanePay devolve o transactionId
2. GET  /v1/payments/{id} ───▶  em ~1 s, mbEntity / mbReference / mbExpiresAt vêm preenchidos
3. Mostre Entidade, Referência, Valor e validade para o cliente
4. O cliente paga em qualquer caixa eletrônico ou pelo home banking
5. O webhook payment.completed chega no seu endpoint (1–3 dias úteis depois)

#1. Criar a cobrança

Endpoint POST /v1/payments

bash

curl -X POST https://okanepay.vip/v1/payments \
  -H "apikey: $OKANEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500,
    "currency": "EUR",
    "paymentMethods": ["MULTIBANCO"],
    "customerName": "Rui Mendes",
    "customerEmail": "rui@example.com",
    "metadata": { "orderId": "ORD-3311" },
    "idempotencyKey": "ORD-3311"
  }'

Resposta 201 Created

json

{
  "id": "d4e5f6a7-b8c9-4012-9def-012345678901",
  "status": "WAITING_PAYMENT",
  "amount": 12500,
  "currency": "EUR",
  "paymentMethods": ["MULTIBANCO"],
  "createdAt": "2026-04-25T16:00:11.000Z"
}

#2. Buscar o voucher

bash

curl https://okanepay.vip/v1/payments/d4e5f6a7-b8c9-4012-9def-012345678901 \
  -H "apikey: $OKANEPAY_API_KEY"

json

{
  "id": "d4e5f6a7-b8c9-4012-9def-012345678901",
  "status": "WAITING_PAYMENT",
  "amount": 12500,
  "currency": "EUR",
  "paymentMethods": ["MULTIBANCO"],
  "mbEntity": "12345",
  "mbReference": "987 654 321",
  "mbExpiresAt": "2026-05-02T16:00:11.000Z",
  "createdAt": "2026-04-25T16:00:11.000Z"
}

Campo	Descrição
`mbEntity`	Entidade (Entity) da OkanePay, com 5 dígitos.
`mbReference`	Referência (Reference) com 9 dígitos — específica de cada pagamento.
`mbExpiresAt`	Validade do voucher. Depois dela, o status passa para `EXPIRED`.

#3. Mostrar o voucher

O cliente precisa dos três valores. Layout de tela recomendado:

text

┌─────────────────────────────────────────┐
│  Pagamento Multibanco                   │
├─────────────────────────────────────────┤
│  Entidade        12345                  │
│  Referência      987 654 321            │
│  Valor           € 125,00               │
│  Validade        02 Maio 2026           │
└─────────────────────────────────────────┘

Pague em qualquer caixa Multibanco ou
através do seu home-banking até à data
de validade.

O e-mail de confirmação deve trazer os mesmos três dados, mais o valor — o cliente português espera esse formato.

#4. Confirmar pelo webhook

json

{
  "event": "payment.completed",
  "data": {
    "transactionId": "d4e5f6a7-b8c9-4012-9def-012345678901",
    "amount": 12500,
    "status": "PAID",
    "previousStatus": "WAITING_PAYMENT",
    "paidWith": "MULTIBANCO",
    "providerFee": 100,
    "platformFee": 125,
    "netAmount": 12275,
    "occurredAt": "2026-04-26T11:32:18.000Z"
  }
}

#Ciclo de vida

text

WAITING_PAYMENT  ──▶  PAID      ✓ libere o pedido
                 ──▶  EXPIRED   a janela do voucher passou (padrão: 7 dias)

Não existe REFUSED — o voucher ou é pago ou expira.

#Casos de borda e dúvidas

P: Quanto tempo o cliente tem para pagar? R: 7 dias por padrão. Escreva para suporte@okanepay.vip para estender até 30 dias.

P: O cliente pode pagar um valor diferente? R: Não. O voucher Multibanco exige valor e referência exatos. Um valor errado é recusado no caixa eletrônico.

P: Meu cliente pagou, mas o webhook ainda não chegou. R: Os arquivos de liquidação do Multibanco são processados em lote — conte com até 24h entre o pagamento no caixa eletrônico e o webhook payment.completed. Se já passou de 48h, fale com suporte@okanepay.vip.

P: Posso gerar o mesmo voucher duas vezes? R: Use o mesmo idempotencyKey e você recebe de volta a transação original (com a Entidade/Referência originais). Só crie uma transação nova se quiser um voucher novo.

P: O cliente paga tarifa bancária? R: Pagamento em caixa eletrônico normalmente é gratuito. O home banking pode cobrar uma pequena tarifa de processamento, dependendo do banco — fora do controle da OkanePay.

#Próximo

→ Referência da API · Plano do sandbox