来福权益 H5 产品统一入口 API

版本：v1.3 / 更新时间：2026-10-08 / 环境：118测试先行，正式环境以发布通知为准。mobile 真实手机号要求于 2026-09-07 生效（A 类收货/核销/出行/票务/话费产品传非 11 位手机号将返回 400）。

接口入口

项目	说明
请求地址	`POST https://api.laifuagi.cn/openapi/v1/h5/access`
Content-Type	`application/json`
签名方式	HMAC-SHA256，Base64 URL-safe，去除末尾 `=`
能力边界	本接口只生成 H5 访问地址。地址返回成功代表应用鉴权、产品授权、入口路由通过；不代表已支付、已履约或已完成异步通知。

请求头

Header	必填	说明
`app_id`	是	开放平台应用 ID。
`timestamp`	是	秒级时间戳。
`nonce`	是	随机字符串，建议每次请求唯一。
`sign`	是	按签名串计算得到的签名。

签名规则

POST
/openapi/v1/h5/access
{timestamp}
{nonce}
{rawJsonBody}

第 5 行必须是实际发送的原始 JSON 字符串，不能改字段顺序、不能重新格式化、不能使用 body 哈希。

sign = Base64UrlNoPadding(HMAC-SHA256(appSecret, 签名串))

请求参数

字段	必填	说明
`typeCode`	是	产品编码，见“已开放 H5 产品”。
`interfaceTypeCode`	是	接口产品编码，必须与产品编码匹配。
`outTradeNo`	是	商户请求号，建议全局唯一。
`mobile`	按品类	收货/核销/出行/票务/话费类产品（美团外卖、美团团购、小象超市、叮咚、京东、打车、火车票、机票、景区、电影、酒店、蛋糕、水电燃气等）必填 11 位真实手机号，上游页面会做手机号校验；大牌到店、中石化中石油展码付等品类可传渠道标识或留空。传非 11 位手机号将被拒绝，见“常见错误”。
`userId`	建议	商户侧用户标识，用于订单商户归属识别与回调定位；建议必传且同一用户保持稳定（如会员编号、用户编号），同一用户勿频繁变化。
`callbackUrl`	否	H5 页面跳回地址；异步通知地址以商户应用配置的 notifyUrl 为准。

{"typeCode":"FoodH5","interfaceTypeCode":"food_bigbrand_h5_interface","outTradeNo":"mch202608040001","mobile":"13800138000","userId":"user_10001","callbackUrl":"https://merchant.example.com/return"}

响应字段

字段	说明
`code`	业务状态码，`200` 表示请求成功。
`msg`	业务提示。
`data.h5Url`	H5 访问地址。商户前端可跳转到该地址。
`data.typeCode`	产品编码。
`data.interfaceTypeCode`	接口产品编码。
`data.orderCreated`	是否已在平台侧创建订单。入口烟测通常为 false 或为空，具体以产品流程为准。

已开放 H5 产品（122入口烟测通过，含中石化中石油展码付）

typeCode	interfaceTypeCode	产品	路由	风险级别
`AirTicketH5`	`domestic_air_tickets_h5_interface`	飞机票H5	chinadao_h5	medium
`BestwayHotel`	`bestway_hotel_interface`	锦江酒店	chinadao_h5	medium
`Cake`	`cake2_interface`	蛋糕外卖	chinadao_h5	low
`Cakecategory`	`cake_interface`	蛋糕	chinadao_h5	low
`FoodH5`	`food_bigbrand_h5_interface`	大牌到店H5	chinadao_h5	medium
`FreshMart`	`mt_maicai_interface`	小象超市H5	chinadao_h5	low
`Hotel`	`hotel_two_interface`	酒店	chinadao_h5	medium
`HotelH5`	`hotel_h5_interface`	酒店H5	chinadao_h5	medium
`MarketDD`	`ding_dong_interface`	叮咚买菜	chinadao_h5	low
`MarketJD`	`jd_mall_interface`	京东	chinadao_h5	low
`MarketJDH5`	`jd_mall_h5_interface`	京东H5	chinadao_h5	low
`MeituanTuan`	`mt_canyin_interface`	美团团购H5	chinadao_h5	low
`MovieThree`	`movie_three_interface`	电影V3	chinadao_h5	medium
`Scenic`	`scenic_spot_interface`	景区门票	chinadao_h5	medium
`Taxi`	`taxi_interface`	打车	chinadao_h5	low
`UnionGas`	`union_gas_interface`	中石化中石油展码付	chinadao_h5	medium
`TrainH5`	`train_h5_interface`	火车票H5	chinadao_h5	medium
`Weg`	`weg_interface`	水电燃气	chinadao_h5	high
`MeituanWaimaiCD`	`mt_waimai_cd_interface`	美团外卖(中国道)	chinadao_h5	low
`MeituanWaimai`	`mt_waimai_interface`	美团外卖H5	SHILU_MEITUAN	low

以上为入口 URL 层通过清单；支付、履约、退款、异步通知需按产品另行验收。

美团外卖双通道说明：MeituanWaimai/mt_waimai_interface 由十鹿(SHILU_MEITUAN)履约；MeituanWaimaiCD/mt_waimai_cd_interface 为中国道(ChinaDao)履约，两者为独立商品，按需选择其一或并存接入。

暂不开放产品

typeCode	interfaceTypeCode	产品	状态	原因
`AudiovisualTwoH5`	`audiovisual_two_h5_interface`	虚拟会员H5	preview	未达入口商用门禁，暂不开放
`Book`	`book_v2_interface`	图书	preview	未达入口商用门禁，暂不开放
`VideoH5`	`audiovisual_h5_interface`	影音会员H5	preview	未达入口商用门禁，暂不开放

H5 订单与收银闭环

步骤	责任方	说明
1. 获取 H5 地址	商户服务端 → 来福	商户调用 `/openapi/v1/h5/access`，来福校验应用、产品授权和签名后返回 `h5Url`。
2. H5 创建待支付单	上游 H5 → 来福	用户在 H5 内选择商品后，上游回调来福创建订单；来福落本地 `WAIT_PAY` 订单并返回商户收银台地址（`cashierUrl`），该地址带收银台令牌 `token`。商户收银台用 token 调用统一验单接口 `GET https://api.laifuagi.cn/openapi/v1/sdk/cashier-token?token=cst_xxx` 换取订单信息。令牌有效期 30 分钟；返回字段含 `merchantId / orderNo / amount / status / userId` 等，其中 `userId` 为商户下单时传的原始用户标识，未传或取值失败时该字段不返回。token 过期或不存在时返回 `收银台令牌已过期，请重新下单`。
3. 商户端收银	下游商户	收银台在下游商户端。商户可按预充值/余额模式向用户收银，来福不直接替商户收款。
4. 支付成功通知来福	商户服务端 → 来福	商户收银成功后，调用来福支付成功通知接口。来福验签、校验金额/订单/幂等后推进订单。
5. 提交上游并扣款	来福 → 上游	来福按产品模型调用上游支付确认，上游确认后推进履约。
6. 异步通知商户	来福 → 商户 notifyUrl	订单成功、失败、退款/关闭等终态由来福按商户应用配置的 `notifyUrl` 异步通知下游商户；失败进入补偿重试。

大牌到店 H5 履约凭证字段

大牌到店 H5（FoodH5/food_bigbrand_h5_interface）的入口接口只返回服务访问地址，取餐码/二维码不在入口阶段返回。用户在 H5 内下单并完成支付、上游状态回调到达来福后，来福会在订单详情和异步通知中透出履约凭证字段。

订单详情 fulfillment 字段

履约成功后，调用订单详情接口 GET /openapi/v1/sdk/order-detail?merchantId={merchantId}&orderNo={orderNo}，返回的 data.fulfillment 可能包含：

字段	类型	说明
`voucherCode`	string	取餐/核销提示文本；来源于上游回调 `other.data.codes`
`pickupCode`	string	取餐码；与 `voucherCode` 同语义，便于商户端按取餐码字段展示
`redeemCode`	string	二维码/核销码内容；来源于上游回调 `other.data.qrCodes`
`qrCode`	string	二维码；与 `redeemCode` 同语义，便于商户端按二维码字段展示
`orderCode`	string	上游订单号/服务方订单号；来源于上游回调 `other.orderCode`

异步通知字段

平台向商户 notifyUrl 推送订单成功/履约结果时，大牌到店 H5 成功通知 payload 会同步携带：

字段	类型	说明
`voucherCode`	string	取餐/核销提示文本
`pickupCode`	string	取餐码（与 `voucherCode` 同语义）
`redeemCode`	string	二维码/核销码内容
`qrCode`	string	二维码（与 `redeemCode` 同语义）
`orderCode`	string	上游订单号/服务方订单号

{
  "event": "UPSTREAM_CALLBACK",
  "typeCode": "FoodH5",
  "orderStatus": "SUCCESS",
  "voucherCode": "预计取单时间：15:57",
  "pickupCode": "预计取单时间：15:57",
  "redeemCode": "QR-CODE-XYZ",
  "qrCode": "QR-CODE-XYZ",
  "orderCode": "UP_ORDER_123"
}

字段可能因上游返回内容为空而为空；商户端应按 orderStatus=SUCCESS 判断履约成功，按上述凭证字段展示取餐/核销信息。大牌到店 H5 取餐码/二维码仅部分品牌返回（如二维码仅瑞幸返回），无该凭证时为 null 或空。

常见错误

提示	含义
签名错误或应用不存在	检查 `app_id`、密钥、签名串、时间戳和 nonce。
interfaceTypeCode 与 typeCode 不匹配	产品编码和接口编码不属于同一产品。
该H5产品暂未达到商用状态	产品未通过入口门禁，当前商户暂不可开放。
未授权该产品	当前商户未开通该产品。
该品类需真实手机号：mobile 必须为 11 位手机号	当前产品属收货/核销/出行/票务/话费类，上游要求真实手机号；`mobile` 请传用户真实 11 位手机号，勿传渠道标识、商户编号或留空。