怎么选

用户看到什么

员工从你们的福利入口点进来后，默认进入本机构专属商城首页（分类网格、banner、推荐；已开通的品牌图标）。货来自中台统一供给。首页默认由我方运营按开通单装修；若给你们开了商城后台账号，也可自行改本机构首页。

1. 你们的页面整页跳转（或 App webview）打开换票返回的 entryUrl
2. 免登成功：换票未传 target（或约定进商城）则逛 DIY 首页，不必再注册
3. 若书面开通了直达，换票可带 target，免登后进入对应品牌页（闪购/影票等仍走现网协议，不是换票接口本身）
4. 站内商品加购、下单；未走直达时，也可从首页已露出的品牌图标再进去
5. 站内单付款：默认走我们的收银台；书面约定「租户收银台」时整页跳你们收银页，付完由你们服务端通知我们入账

如何植入

完整商城域名、tenant 编号由运营书面下发。形态如下（参数必须写在 hash 后面，不要写到 # 前面）：

直达品牌时，返回的 entryUrl 可能还带 &target=TB_SHANGOU 等。

请只打开换票接口返回的 entryUrl，不要自己拼。ticket 约 3 分钟、只能打开一次；打开即作废。不要把长期身份写进可转发的链接。

免登换票（一期交付）

在用户已登录你们系统、即将跳转前，由你们服务端调用换票接口（浏览器不要持有 embed_secret）。

该接口在商城域名上，不是开放API 的 /open/api/v1。embed_app_key / embed_app_secret 与开放API 的 AppKey 不是同一套。

请求

target 取值

签名

1. 取 JSON 顶层非空标量（不含 sign、不含空字符串）+ Header 约定的 timestamp、app_key
2. 按 key 字母序拼接 k=v，用 & 连接
3. 末尾追加 &app_secret={embed_app_secret}
4. 对该字符串做 UTF-8 HMAC-SHA256（密钥为 embed_app_secret），结果小写 hex，放入 X-Sign
5. X-Timestamp 与服务器相差超过 300 秒会拒绝

响应

{
  "code": 200,
  "data": {
    "ticket": "...",
    "expireAt": "2026-09-14T18:00:00",
    "entryUrl": "https://{商城域名}/shop/#/?tenant=Txxxx&ticket=...",
    "target": "MALL"
  }
}

以 code === 200 且 data.entryUrl 有值为成功。message 可能是 success、空或没有该字段，不要用它判断成败。expireAt 是商城服务器本地时间，无时区后缀。

前端只打开返回的 entryUrl。ticket 约 3 分钟、一次性；用户打开后即作废，不要把同一张票转发给第二个人，也不要在打开后再把这张 ticket 拿去对照。

收银台

换票时若传了 returnUrl（域名须事先写入白名单），站内商城订单支付成功后会跳回该地址，并附带查询参数 orderNo。未传则留在商城支付结果页。闪购 / 影票等外链品牌不走本节，仍走现网各自链路。

以下仅「租户收银台」。密钥与换票同一套 embed_app_key / embed_app_secret（HMAC-SHA256，禁止 MD5，不要用开放API 的 AppKey）。金额一律整数分；时间戳 Unix 秒，允许 ±300 秒。

跳转收银（我们 → 你们页面）

待付单生成后整页跳你们书面登记的收银地址（已有 query 用 & 追加）。全部 query 做 URL 编码；验签用解码后的字段值。

你们调我们（支付 / 退款）

匿名、不依赖用户登录。Header 与换票相同。SaaS 多租户同一域名时请再带 X-Tenant: {租户编码}。

Body 为 application/json。金额字段传整数分的十进制字符串（如 "561"），不要传元。成功响应：

{ "code": 200, "message": "success" }

以 code === 200 为准。非 200 或网络失败：按单号幂等重试（建议 1s / 5s / 30s，最多 8 次）。已成功再通知仍回 200。常见拒绝：签名错误、金额不符、订单已过期或已取消、退款单不存在。

支付入账

{
  "outTradeNo": "orderxxxxxxxx",
  "amountFen": "561",
  "status": "SUCCESS",
  "payTradeNo": "你们的流水号",
  "payTime": "1728000000"
}

参与签名：Body 非空标量 + app_key + timestamp。

支付查询（对账用；改单只认 notify）

Header 同上。签名字段：outTradeNo + app_key + timestamp。返回 UNPAID / PAID / CANCELLED，以及 amountFen、payTradeNo、paidTime。

退款结果通知

售后是否同意、退多少由我们后台决定。我们会先 POST 你们书面登记的退款地址（带我方签发的 refundNo），你们退完再打本接口。没有我方 refundNo 的通知会被拒绝。

SUCCESS / FAILED 重复通知仍回 200。FAILED 不把已成功的单改回去；我们可能用同一个 refundNo 再申请一次。

退款查询

签名字段：refundNo + app_key + timestamp。返回 SENT / SUCCESS / FAILED。

我们调你们（退款申请 / 订单状态）

地址以开通书面为准。Header 同样是 X-App-Key / X-Timestamp / X-Sign，请按 HMAC 收，不要走登录态。我们认 HTTP 200，且 body 为空，或 JSON 无 code、或 code 为 200 / 0，且 success 不为 false。明确失败码（例如需登录）当失败并重试。

用户在商城申请售后时不会打你们。要等我们后台同意后才 POST 退款地址。拒绝售后不打。

退款申请 Body（非空字段都参与签名）：

code===200 只表示收下，已退款必须再打 refund/notify。超时或非 200 我们会用同一 refundNo 重试。

订单状态为异步通知，失败只重试，不改我们的单。Body 非空字段参与签名：

开通与验收

联系开通工单里的对接运营。请准备：机构名称、联系人、中台租户编号（没有则新建）、测试手机号、跳回域名（若需要 returnUrl）、希望首页出现的品类/品牌（闪购等需另开资质）。

开通嵌入前：走我方收银台须积分或支付宝至少一种可用；走租户收银台则登记你们的 HTTPS 收银地址（退款 / 状态回调测试环境允许 http）。

1. 运营开通托管商城、装修与供给，书面下发商城域名、tenant、embed 密钥；直达品牌以开通单勾选为准
2. 只嵌商城：换票不要传 target（或按你们约定固定传 MALL，两种签名不同，须写死一种），用测试手机号打开 entryUrl，确认免登进 DIY 首页
3. 要在首页露出闪购等：须开通对应入口且装修里已有该图标；未开通的图标不会出现在嵌入首页
4. 要换票直达某品牌：须开通单已包含该 target 后再联调；不要对未开通项自行验收
5. 我方收银台：走通一笔站内测试单；若传了 returnUrl，确认支付成功后回到你们页面且带 orderNo
6. 租户收银台：跳转链验签通过 → 服务端 notify 入账 → 只开 returnUrl 不能改单 → 后台同意退款后能收到 refundNo 并回 SUCCESS
7. 验收通过前不要把链接发给全部员工

文档版本 v0.7，2026-09-29。换票免登、可选 target、租户收银台（跳转验签、支付/退款通知与查询、退款申请与订单状态）。商城域名与密钥以书面为准；某家的收银/退款 URL 不写在本文。