Multibanco

Multibanco 是葡萄牙的 ATM 和网上银行凭证网络。Liqfy 会返回一组 Entity（实体号）+ Reference（参考号）+ Amount（金额）三元组，客户可在任意 ATM、其银行 App 或网上银行中完成支付。结算周期：1–3 个工作日。

#流程概览

text

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

端点 POST /v1/payments

bash

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

幂等性。 POST /v1/payments 接受 Idempotency-Key 请求头（推荐）；缺少该请求头时，也可使用请求体字段 idempotencyKey 作为备选。两者至少发送其一。如果同时发送，两者的值必须一致——值不一致时返回 400；在此路由上两者都未发送时返回 400。可使用任意非空字符串，作用域按商户隔离（(merchant, key)）：使用相同的键和请求体重放请求，将返回已存储的响应（相同的 Entity/Reference）。

请求体 — 所有 /v1/payments 创建请求共用的字段（特定支付方式的产物会在响应中返回）：

字段	说明
`amount`	大于 0 的整数，以最小货币单位（分）表示。`12500` = € 125,00。
`currency`	3–8 个字符，默认 `"BRL"`（Multibanco 以 `EUR` 支付）。
`paymentMethods`	此处为 `["MULTIBANCO"]`。API 接受 `PIX`、`CRYPTO`、`CREDIT_CARD`、`BOLETO`、`MBWAY`、`MULTIBANCO`、`IDEAL`、`BANCONTACT`、`SEPA`、`BIZUM`、`SWAP_NOW`。
`checkout`	可选的结账模板 slug（1–80 个字符）。未知 slug → `404`；会将 `paymentMethods` 限定为该模板支持的支付方式。
`customerName` / `customerDocument` / `customerEmail` / `customerPhone`	扁平的客户字段。`customerEmail` 必须为电子邮件地址；`customerPhone` 为自由格式（建议使用 E.164）。
`customer`	备选的嵌套 `{ name?, document?, email?, phone? }`；会被展开为上述字段（扁平字段优先）。
`expectedPayerDocument`	仅含数字的预期付款人 CPF/CNPJ；在提供方支持时将作为付款人锁定条件。
`metadata`	自由格式的键/值。`metadata.returnUrl` / `metadata.cancelUrl` 若存在，必须为 http(s) URL。
`returnUrl`	流程结束后将客户跳转到的地址。http(s) URL，不得包含片段（fragment）。
`cancelUrl`	客户中止时跳转到的地址。URL 规则相同；需要同时提供 `returnUrl`。
`items`	可选 `{ name, quantity, unitPrice, totalPrice }[]`，均为大于 0 的整数。
`webhookUrl`	可选，用于覆盖单笔交易的 webhook URL。
`idempotencyKey`	`Idempotency-Key` 请求头的请求体备选字段。
`country`	可选，2–3 个字符；用于提供方账户路由。
`riskTier`	可选 `LOW`、`MEDIUM` 或 `HIGH`。
`environment`	可选 `SANDBOX`、`STAGING`、`PRODUCTION`（默认 `PRODUCTION`）。
`expiresIn`	可选的过期时间（秒），60–604800（以提供方返回的过期时间为准）。

响应 201 Created — 凭证信息已包含在响应中；无需再调用 GET 即可查看。

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.liqfy.com.br/d4e5f6a7-b8c9-4012-9def-012345678901",
  "createdAt": "2026-04-25T16:00: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)`
`client.payments.list(query)`	`client.payments.list(**query)`	`$client->payments->list($query)`	`client.Payments.ListAsync(query)`

payments.list 返回分页信封 { data, total, page, limit }。

#2. 获取凭证

GET /v1/payments/{id} 会重新读取同一凭证（以及 checkoutUrl）：

bash

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

字段	描述
`mbEntity`	5 位 Liqfy 实体号（Entidade）。
`mbReference`	9 位参考号（Referência）——每笔支付唯一。
`mbExpiresAt`	凭证过期时间。过期后，状态变为 `EXPIRED`。

#3. 展示凭证

客户需要全部三个值。推荐的界面布局：

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.

确认邮件应包含相同的三个值以及金额——葡萄牙客户习惯这种格式。

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

#生命周期

text

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

不存在 REFUSED——凭证要么已支付，要么已过期。

#边缘情况与常见问题

问：客户有多长时间完成支付？ 答：默认 7 天。发送邮件至 suporte@liqfy.com.br 可延长至最多 30 天。

问：客户可以支付不同的金额吗？ 答：不可以。Multibanco 凭证要求金额和参考号完全匹配。金额错误会在 ATM 端被拒绝。

问：我的客户已付款，但 webhook 仍未触发。 答：Multibanco 结算文件是批量处理的——从在 ATM 付款到收到 charge.paid webhook 可能需要长达 24 小时。如果已超过 48 小时，请联系 suporte@liqfy.com.br。

问：我可以两次生成同一张凭证吗？ 答：使用相同的 idempotencyKey，即可取回原始交易（包含原始的 Entity/Reference）。仅当需要新凭证时才创建新交易。

问：客户需要支付银行手续费吗？ 答：ATM 支付通常免费。网上银行可能会根据银行收取少量手续费——这不在 Liqfy 的控制范围内。

#后续步骤

→ API 参考 · 沙箱方案