美团外卖 H5 API

1. 职责与价格

callbackUrl 仅用于浏览器回跳，不表示支付成功；notifyUrl 才是来福向下游发送订单状态的服务端地址。

2. 业务流程

3. 公共约定

正式地址：https://api.laifuagi.cn

数据格式：请求与响应均使用 application/json; charset=UTF-8。金额使用十进制字符串，单位为元，保留两位小数。

OpenAPI 请求头

OpenAPI 签名

签名原文 = METHOD + "\n"
         + URI + "\n"
         + timestamp + "\n"
         + nonce + "\n"
         + 原始 JSON 请求体

sign = Base64UrlWithoutPadding(
  HMAC-SHA256(appSecret, UTF8(签名原文))
)

调用入口时，METHOD 为 POST，URI 为 /openapi/v1/h5/access。JSON 的字段顺序、空格和转义必须与实际发送的原始请求体完全一致。

4. 获取美团 H5 入口

POST https://api.laifuagi.cn/openapi/v1/h5/access
Content-Type: application/json
app_id: {AppID}
timestamp: {Unix秒}
nonce: {唯一随机串}
sign: {OpenAPI签名}

{
  "typeCode": "MeituanWaimai",
  "externalUserId": "USER_10001",
  "phone": "13800138000"
}

成功响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "typeCode": "MeituanWaimai",
    "interfaceTypeCode": "mt_waimai_interface",
    "mode": "shiluIndependentH5",
    "h5Url": "https://{十鹿H5地址}"
  }
}

h5Url 应直接用于浏览器跳转。下游不得修改其中的签名、用户、模板或回调参数，也不得缓存为长期固定地址。

5. 下游支付确认

十鹿回调来福创建订单后，来福返回权益订单承接页。下游确认终端用户已在自有支付系统真实付款后，由服务端调用：

POST https://api.laifuagi.cn/openapi/v1/sdk/payment/notify?merchantId={商户ID}
Content-Type: application/json

{
  "merchantId": 10001,
  "orderNo": "H5202607250000001234",
  "quoteId": "",
  "amount": "100.00",
  "timestamp": "1784990000000",
  "nonce": "PAY_20260725_000001",
  "sign": "{支付通知签名}"
}

支付通知签名

payload = "merchantId=" + merchantId
        + "&orderNo=" + orderNo
        + ""eId=" + quoteId
        + "&amount=" + amount保留两位小数
        + "×tamp=" + timestamp
        + "&nonce=" + nonce

sign = SHA256_HEX(payload + "&key=" + appSecret + "&sandbox=false")

重复通知按 orderNo + sign 幂等处理，不会重复冻结余额或重复履约。验签失败、订单商户不匹配、金额不一致或余额不足时均失败关闭。

6. 来福异步通知下游

商户在后台配置 notifyUrl 后，来福以 HTTP POST 发送 JSON。通知头：

Content-Type: application/json
X-LYP-Event: ORDER_SUCCESS | ORDER_FAIL | ORDER_REFUND
X-LYP-Sign: HMAC-SHA256_HEX(apiSecret, 原始JSON请求体)

通知示例

{
  "event": "ORDER_SUCCESS",
  "orderNo": "H5202607250000001234",
  "merchantId": 10001,
  "typeCode": "MeituanWaimai",
  "orderStatus": "SUCCESS",
  "userPayAmount": 100.00,
  "merchantSettleAmount": 101.00,
  "merchantProfit": -1.00,
  "pricingMode": "h5",
  "upstreamOrderNo": "SL202607250001",
  "upstreamStatus": "PAID_NOTIFY",
  "timestamp": 1784990000000,
  "externalUserId": "USER_10001"
}

X-LYP-Sign 使用商户 SDK 的 apiSecret，不是 OpenAPI AppSecret。验签必须针对收到的原始 JSON 字节串计算，解析并重新序列化后再验签可能因字段顺序变化而失败。

下游应返回纯文本 success、包含 ok 的响应，或包含业务成功码 200 的响应。非成功响应会进入重试，最多 5 次，间隔按指数递增。

7. 状态与幂等

• 获取 H5 入口不会创建订单、扣减余额或触发履约。
• 同一上游订单按“商户 + 上游订单号”幂等，禁止跨商户复用。
• PROCESSING 不是最终成功，下游不得提前向用户承诺履约完成。
• 通知按 orderNo + event 幂等处理；重复通知必须返回成功，避免平台持续重试。

8. 错误处理

9. 上线检查

1. 商户已审核通过、权益已开通，OpenAPI 应用启用并配置正确的 IP 白名单。
2. 已授权 MeituanWaimai / mt_waimai_interface，且商户余额与结算规则已确认。
3. notifyUrl 使用 HTTPS，可校验 X-LYP-Sign，并按订单号与事件幂等。
4. 先在测试环境完成：入口获取、H5选品回调、待支付订单、支付确认、成功/失败通知、退款和余额流水核对。
5. 正式小额验证仅在明确授权后执行；成功后立即退款并核对账务。