Multibanco

Multibanco es la red de cajeros automáticos y vouchers de banca en línea de Portugal. Liqfy devuelve un triplete Entidad + Referencia + Importe que el cliente paga en cualquier cajero automático, en la app de su banco o mediante banca en línea. Liquidación: 1–3 días hábiles.

#Resumen del flujo

1. POST /v1/payments  ──────▶  Liqfy returns the payment: id, mbEntity / mbReference / mbExpiresAt, checkoutUrl
2. Display Entity, Reference, Amount, and expiry to the customer
3. Customer pays at any ATM or via home-banking
4. Webhook charge.paid arrives at your endpoint (1–3 business days later)

#1. Crear el pago

Endpoint POST /v1/payments

curl -X POST https://api.liqfy.com.br/v1/payments \
  -H "Authorization: Bearer $LIQFY_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" }
  }'

Idempotencia. POST /v1/payments acepta la cabecera Idempotency-Key (preferida) o el campo del cuerpo idempotencyKey como alternativa cuando falta la cabecera; envía al menos uno de los dos. Si envías ambos, deben coincidir: los valores divergentes devuelven 400, y no enviar ninguno devuelve 400 en esta ruta. Se admite cualquier cadena no vacía, con ámbito por comercio ((merchant, key)): repetir la misma clave y el mismo cuerpo devuelve la respuesta almacenada (la misma Entidad/Referencia).

Cuerpo — los campos comunes a toda creación de /v1/payments (los artefactos específicos del método vuelven en la respuesta):

Respuesta 201 Created — los artefactos del voucher ya están aquí; no necesitas un GET posterior para verlos.

{
  "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.liqfy.com.br/d4e5f6a7-b8c9-4012-9def-012345678901",
  "createdAt": "2026-04-25T16:00:11.000Z"
}

Con el SDK oficial (el mismo paquete neutro para todas las marcas; configúralo con https://api.liqfy.com.br):

payments.list devuelve el sobre de página { data, total, page, limit }.

#2. Obtener el voucher

GET /v1/payments/{id} vuelve a leer el mismo voucher (y checkoutUrl):

curl https://api.liqfy.com.br/v1/payments/d4e5f6a7-b8c9-4012-9def-012345678901 \
  -H "Authorization: Bearer $LIQFY_API_KEY"

{
  "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.liqfy.com.br/d4e5f6a7-b8c9-4012-9def-012345678901",
  "createdAt": "2026-04-25T16:00:11.000Z"
}

#3. Mostrar el voucher

El cliente necesita los tres valores. Diseño de interfaz recomendado:

┌─────────────────────────────────────────┐
│  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.

Los correos de confirmación deben incluir los mismos tres valores más el importe: los clientes portugueses esperan este formato.

#4. Confirmar mediante webhook

{
  "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

WAITING_PAYMENT  ──▶  PAID      ✓ fulfill order
                 ──▶  EXPIRED   voucher window passed (default 7 days)

No existe REFUSED: el voucher se paga o caduca.

#Casos límite y preguntas frecuentes

P: ¿Cuánto tiempo tiene el cliente para pagar? R: 7 días por defecto. Escribe a suporte@liqfy.com.br para ampliarlo hasta 30 días.

P: ¿Puede el cliente pagar un importe diferente? R: No. Los vouchers Multibanco exigen coincidencia exacta de importe y referencia. Un importe incorrecto se rechaza en el cajero.

P: Mi cliente pagó, pero el webhook todavía no se ha disparado. R: Los archivos de liquidación de Multibanco se procesan por lotes: cuenta con hasta 24 h entre el pago en el cajero y el webhook charge.paid. Si han pasado más de 48 h, contacta con suporte@liqfy.com.br.

P: ¿Puedo generar el mismo voucher dos veces? R: Usa el mismo valor de idempotencyKey y recibirás la transacción original (con la Entidad/Referencia originales). Emite una nueva transacción solo si quieres un voucher nuevo.

P: ¿Comisiones bancarias para el cliente? R: Los pagos en cajero suelen ser gratuitos. La banca en línea puede cobrar una pequeña comisión de procesamiento según el banco, algo que está fuera del control de Liqfy.

#Siguiente

→ Referencia de la API · Plan de sandbox