MB WAY

MB WAY 是葡萄牙的移动钱包。客户输入手机号码后，会在其 MB WAY 应用上收到推送通知，点击即可授权——资金当天结算。

#流程概览

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. 创建支付

端点 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" }
  }'

幂等性。 POST /v1/payments 接受 Idempotency-Key 请求头（推荐）。请求头缺失时，也可使用请求体字段 idempotencyKey 作为备选；两者至少发送其一。如果两者都发送，其值必须一致：值不一致将返回 400，两者都不发送则在此路由上返回 400。

字段	说明
`amount`	单位为分。`4500` = € 45,00。MB WAY 每笔交易最高支持 € 750。
`currency`	必须为 `"EUR"`。
`paymentMethods`	`["MBWAY"]`
`customerPhone`	E.164 格式的葡萄牙手机号码（`+351XXXXXXXXX`）。MB WAY 必填。平台通过此字段转发推送。
`metadata.customerPhone` / `metadata.alias` / `metadata.phone`	旧版的按服务商区分的备选字段，部分适配器仍会读取——不属于接口契约。如果商户被路由到其他服务商，这些字段将无法触发推送。请始终发送 `customerPhone`。

响应 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"
}

推送会在几秒内发送到客户的应用。

使用官方 SDK（所有品牌共用同一个中立的包——通过 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)`

在 input 中发送 customerPhone——SDK 会将其原样作为传输字段 customerPhone 发送。

#2. 显示“等待”界面

此流程没有二维码，也没有重定向——客户的手机正在振动提醒。请向客户显示加载状态，并附带 5 分钟倒计时。每 3 秒轮询一次 GET /v1/payments/{id}，仅用于改善用户体验：

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();

后端履约仍必须以 webhook 为依据，绝不能依据轮询结果。

#3. 通过 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": {}
    }
  }
}

#生命周期

text

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

#边缘情况与常见问题

问：客户输错了手机号码怎么办？ 答：推送会被静默丢弃，扣款请求将在 5 分钟后过期。请使用更正后的号码创建新交易。

问：客户需要葡萄牙银行账户吗？ 答：需要。MB WAY 仅支持葡萄牙发行的银行卡/账户。

问：可以重试同一笔交易吗？ 答：不可以——交易一旦进入 EXPIRED 状态即已关闭。请创建新交易。

问：最高金额是多少？ 答：每笔交易 € 750，每位客户每天 € 2 500（这是 MB WAY 的规则，并非 Liqfy 的限额）。

问：客户说“已付款”，但我这边已经显示 WAITING_PAYMENT 一个小时了。 答：这是服务商/MB WAY 清算端的延迟。请提供交易 ID 联系 suporte@liqfy.com.br——我们将根据结算文件进行对账。

#下一步

→ Multibanco · API 参考