MB WAY

MB WAY es la billetera móvil de Portugal. El cliente introduce su número de teléfono, recibe una notificación push en su app de MB WAY y toca para autorizar; los fondos se liquidan el mismo día.

#El flujo de un vistazo

text

1. POST /v1/payments  ──────▶  Liqfy returns transactionId
2. Customer enters their MB WAY phone number on your checkout
3. Liqfy pushes the request to the customer's MB WAY app (5-min window)
4. Customer taps "Pay" in their app
5. Webhook charge.paid arrives at your endpoint

#1. Crear el pago

Endpoint POST /v1/payments

bash

curl -X POST https://api.liqfy.com.br/v1/payments \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Idempotency-Key: ORD-2034" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "currency": "EUR",
    "paymentMethods": ["MBWAY"],
    "customerName": "Ana Pereira",
    "customerEmail": "ana@example.com",
    "customerPhone": "+351912345678",
    "metadata": { "orderId": "ORD-2034" }
  }'

Idempotencia. POST /v1/payments acepta la cabecera Idempotency-Key (preferida) o el campo del cuerpo idempotencyKey como alternativa cuando la cabecera no está presente; envía al menos uno. Si envías ambos, deben coincidir: los valores divergentes devuelven 400, y no enviar ninguno devuelve 400 en esta ruta.

Campo	Notas
`amount`	Céntimos. `4500` = € 45,00. MB WAY admite hasta € 750 por transacción.
`currency`	Debe ser `"EUR"`.
`paymentMethods`	`["MBWAY"]`
`customerPhone`	Móvil portugués en formato E.164 (`+351XXXXXXXXX`). Obligatorio para MB WAY. Es el campo que la plataforma reenvía para la entrega.
`metadata.customerPhone` / `metadata.alias` / `metadata.phone`	Alternativas heredadas por proveedor que algunos adaptadores aún leen; no forman parte del contrato. Un comercio enrutado a otro proveedor no obtiene ninguna entrega a partir de ellas. Envía siempre `customerPhone`.

Respuesta 201 Created

json

{
  "id": "c3d4e5f6-a7b8-4901-9cde-f01234567890",
  "status": "WAITING_PAYMENT",
  "amount": 4500,
  "currency": "EUR",
  "paymentMethods": ["MBWAY"],
  "createdAt": "2026-04-25T15:55:11.000Z"
}

La notificación push a la app del cliente se envía en cuestión de segundos.

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

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)`

Envía customerPhone en input; el SDK lo transmite como el campo de la petición customerPhone.

#2. Mostrar una pantalla de "espera"

No hay código QR ni redirección: el teléfono del cliente está vibrando. Muéstrale un estado de carga con una cuenta atrás de 5 minutos. Consulta GET /v1/payments/{id} cada 3 segundos solo para la experiencia de usuario:

const poll = async () => {
  const res = await fetch(`/api/payments/${txId}`); // server proxies to Liqfy
  const tx = await res.json();
  if (tx.status === 'PAID') return showSuccess();
  if (['REFUSED', 'EXPIRED', 'CANCELLED'].includes(tx.status)) return showFailure(tx.status);
  setTimeout(poll, 3000);
};
poll();

El cumplimiento del pedido en el backend debe basarse siempre en el webhook, nunca en la consulta periódica.

#3. Confirmar mediante webhook

json

{
  "id": "evt_00000000000000000000000000000001",
  "object": "event",
  "api_version": "2026-07-23",
  "type": "charge.paid",
  "created_at": "2026-04-25T15:56:02.000Z",
  "data": {
    "object": {
      "id": "ch_c3d4e5f6-a7b8-4901-9cde-f01234567890",
      "object": "charge",
      "status": "paid",
      "amount": 4500,
      "currency": "EUR",
      "payment_method": "mbway",
      "settlement": {}
    }
  }
}

#Ciclo de vida

text

WAITING_PAYMENT  ──▶  PAID         ✓ fulfill order
                 ──▶  REFUSED      customer rejected on the app
                 ──▶  EXPIRED      no response within 5 minutes
                 ──▶  CANCELLED    customer hit Cancel

#Casos límite y preguntas frecuentes

P: El cliente escribió mal su número de teléfono. R: La notificación push se descarta sin aviso y el cobro caduca a los 5 minutos. Crea una nueva transacción con el número corregido.

P: ¿Necesita el cliente una cuenta bancaria portuguesa? R: Sí. MB WAY solo funciona con tarjetas/cuentas emitidas en Portugal.

P: ¿Puedo reintentar la misma transacción? R: No: una vez en EXPIRED, la transacción queda cerrada. Crea una nueva.

P: ¿Cuál es el importe máximo? R: € 750 por transacción y € 2 500 por día por cliente (normas de MB WAY; no son límites de Liqfy).

P: El cliente dice "Pagado", pero yo llevo una hora con WAITING_PAYMENT. R: Se trata de un retraso en la compensación por parte del proveedor/MB WAY. Contacta con suporte@liqfy.com.br indicando el id de la transacción y la conciliaremos a partir del archivo de liquidación.

#Siguiente

→ Multibanco · Referencia de la API