Multibanco

O Multibanco é a rede portuguesa de caixas eletrônicos e de vouchers de pagamento pelo home banking. A Moonip 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 Moonip devolve o pagamento: id, mbEntity / mbReference / mbExpiresAt, checkoutUrl
2. Mostre Entidade, Referência, Valor e validade para o cliente
3. O cliente paga em qualquer caixa eletrônico ou pelo home banking
4. O webhook charge.paid chega no seu endpoint (1–3 dias úteis depois)

#1. Criar a cobrança

Endpoint POST /v1/payments

bash

curl -X POST https://api.moonip.io/v1/payments \
  -H "Authorization: Bearer $MOONIP_API_KEY" \
  -H "Idempotency-Key: ORD-3311" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500,
    "currency": "EUR",
    "paymentMethods": ["MULTIBANCO"],
    "customerName": "Rui Mendes",
    "customerEmail": "rui@example.com",
    "metadata": { "orderId": "ORD-3311" }
  }'

Idempotência. O POST /v1/payments aceita o cabeçalho Idempotency-Key (preferido) ou o campo de corpo idempotencyKey como alternativa quando o cabeçalho está ausente; envie pelo menos um. Se enviar os dois, eles precisam ser iguais — valores divergentes são 400, e nenhum dos dois também é 400 nesta rota. Qualquer string não vazia, com escopo por lojista ((merchant, key)): repetir a mesma chave e o mesmo corpo devolve a resposta guardada (a mesma Entidade/Referência).

Corpo — os campos compartilhados por todo POST /v1/payments (os artefatos de cada método voltam na resposta):

Campo	Observação
`amount`	Inteiro > 0 na menor unidade (centavos). `12500` = € 125,00.
`currency`	3–8 caracteres, padrão `"BRL"` (Multibanco paga em `EUR`).
`paymentMethods`	`["MULTIBANCO"]` aqui. A API aceita `PIX`, `CRYPTO`, `CREDIT_CARD`, `BOLETO`, `MBWAY`, `MULTIBANCO`, `IDEAL`, `BANCONTACT`, `SEPA`, `BIZUM`, `SWAP_NOW`.
`checkout`	Slug opcional de template de checkout (1–80). Slug desconhecido → `404`; restringe `paymentMethods` aos métodos do template.
`customerName` / `customerDocument` / `customerEmail` / `customerPhone`	Campos de cliente planos. `customerEmail` precisa ser um e-mail; `customerPhone` é texto livre (E.164 recomendado).
`customer`	Alternativa aninhada `{ name?, document?, email?, phone? }`; é achatada nos campos acima (os campos planos vencem).
`expectedPayerDocument`	CPF/CNPJ esperado do pagador, só dígitos; vira a trava de pagador onde o provedor a aplica.
`metadata`	Chave/valor livre. `metadata.returnUrl` / `metadata.cancelUrl`, se existirem, precisam ser URLs http(s).
`returnUrl`	Para onde mandar o cliente depois do fluxo. URL http(s) sem fragmento.
`cancelUrl`	Para onde mandar o cliente se ele desistir. Mesma regra de URL; exige `returnUrl`.
`items`	Opcional `{ name, quantity, unitPrice, totalPrice }[]`, inteiros > 0.
`webhookUrl`	Override opcional de webhook por transação.
`idempotencyKey`	Alternativa de corpo para o cabeçalho `Idempotency-Key`.
`country`	Opcional, 2–3 caracteres; entrada de roteamento de conta do provedor.
`riskTier`	Opcional `LOW`, `MEDIUM` ou `HIGH`.
`environment`	Opcional `SANDBOX`, `STAGING`, `PRODUCTION` (padrão `PRODUCTION`).
`expiresIn`	Opcional, expiração em segundos, 60–604800 (a expiração devolvida pelo provedor vence).

Resposta 201 Created — os artefatos do voucher já vêm aqui; não é preciso um GET depois para vê-los.

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",
  "checkoutUrl": "https://checkout.moonip.io/d4e5f6a7-b8c9-4012-9def-012345678901",
  "createdAt": "2026-04-25T16:00:11.000Z"
}

Com o SDK oficial (o mesmo pacote neutro para qualquer marca — configure-o com https://api.moonip.io):

node	python	php	dotnet
`client.payments.create(input, { idempotencyKey })`	`client.payments.create(input, idempotency_key)`	`$client->payments->create($input, $idempotencyKey)`	`client.Payments.CreateAsync(input, idempotencyKey)`
`client.payments.retrieve(id)`	`client.payments.retrieve(id)`	`$client->payments->retrieve($id)`	`client.Payments.RetrieveAsync(id)`
`client.payments.list(query)`	`client.payments.list(**query)`	`$client->payments->list($query)`	`client.Payments.ListAsync(query)`

payments.list devolve o envelope de página { data, total, page, limit }.

#2. Buscar o voucher

O GET /v1/payments/{id} relê o mesmo voucher (e o checkoutUrl):

bash

curl https://api.moonip.io/v1/payments/d4e5f6a7-b8c9-4012-9def-012345678901 \
  -H "Authorization: Bearer $MOONIP_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",
  "checkoutUrl": "https://checkout.moonip.io/d4e5f6a7-b8c9-4012-9def-012345678901",
  "createdAt": "2026-04-25T16:00:11.000Z"
}

Campo	Descrição
`mbEntity`	Entidade (Entity) da Moonip, 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

{
  "id": "evt_00000000000000000000000000000001",
  "object": "event",
  "api_version": "2026-07-23",
  "type": "charge.paid",
  "created_at": "2026-04-26T11:32:18.000Z",
  "data": {
    "object": {
      "id": "ch_d4e5f6a7-b8c9-4012-9def-012345678901",
      "object": "charge",
      "status": "paid",
      "amount": 12500,
      "currency": "EUR",
      "payment_method": "multibanco",
      "settlement": {}
    }
  }
}

#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@moonip.io 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 charge.paid. Se já passou de 48h, fale com suporte@moonip.io.

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 Moonip.

#Próximo

→ Referência da API · Plano do sandbox