> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 前端组件（Element）的支付会话与订阅会话

> 解答用 Waffo Element SDK 收款时后端会话接口的常见问题：先调哪个接口、请求体怎么传、会话何时过期、改价时如何更新会话，以及与 Tokenization tokenSessionId 的区别。

本页回答用 Waffo Element SDK 在你自己的页面里收款时，后端要调用的会话接口：先调哪个、会话多久过期、改了价格怎么办。SDK 的安装和前端用法见官网 [前端组件 - 组件使用](https://waffo.com/docs/zh/developer-docs/integration/elements/usage.md)。

## 用前端组件收款，后端要先调哪个接口？

先由你的后端创建一个会话，拿到 `sessionId` 交给前端的 Element SDK：

| 场景 | 创建会话 | 更新会话 |
| - | - | - |
| 一次性支付 | `POST /api/v1/order/session/create` | `POST /api/v1/order/session/update` |
| 订阅 | `POST /api/v1/subscription/session/create` | `POST /api/v1/subscription/session/update` |

四个接口都是带签名的服务端接口，签名和请求头与其他 API 相同，不要从浏览器直接调用。是否能在你的账户上使用，请先和 Waffo 技术支持确认。

## 会话的请求体要传什么？

* 支付会话：请求体和 `/api/v1/order/create` 相同。
* 订阅会话：请求体和 `/api/v1/subscription/create` 相同，金额按首个计费周期报价。

字段规则、必填项和校验都沿用对应的下单或创建订阅接口，可以直接复用你已有的请求组装代码。

## 创建会话时订单或订阅已经生成了吗？

没有。创建会话只做报价和准备，不创建订单，订阅会话也不创建订阅。用户在页面上完成支付后才会产生订单或订阅，之后的状态以支付结果通知和订单查询（或订阅查询）为准。

## 会话多久过期？

响应只有两个字段：

| 字段 | 说明 |
| - | - |
| `sessionId` | 会话 ID，交给前端 Element SDK 使用 |
| `expiresAt` | 过期时间，毫秒时间戳，为创建后 1 小时 |

过期后不能再用这个 `sessionId`，需要重新创建会话。用户可能在页面上停留较久时，在前端判断 `expiresAt`，临近过期时重新创建。

## 用户改了数量或币种，要重新创建会话吗？

不用。调用对应的 update 接口：请求体和创建会话相同，另加原来的 `sessionId`。

* 支付会话 update 用于改价、换币种或刷新报价。
* 订阅会话 update 用于更换套餐、金额或计费周期，或刷新报价。
* update 后 `sessionId` 和过期时间都不变，金额按新的请求重新计算。update 不会延长会话有效期。

## 和 Tokenization 的 tokenSessionId 有什么区别？

两者用途不同，不能混用：

| | Element 会话 `sessionId` | Tokenization `tokenSessionId` |
| - | - | - |
| 用途 | 在你的页面里完成一次支付或开通订阅 | 只绑卡、生成 token，不扣款 |
| 后端接口 | `order/session/create`、`subscription/session/create` | `/api/v1/tokenization/generate` |
| 前端用法 | Element SDK，以官网前端组件页为准 | `tokenizationSubmit` |

只绑卡的流程见[Tokenization 与卡支付 FAQ](https://waffo.com/docs/zh/support/tokenization-faq.md)。

## 去哪看完整字段？

* [Create payment session](https://waffo.com/docs/api-reference/payment-session-create/create-payment-session.md)
* [Update payment session](https://waffo.com/docs/api-reference/收单商户api接口/update-payment-session.md)
* [Create subscription session](https://waffo.com/docs/api-reference/收单商户api接口/create-subscription-session.md)
* [Update subscription session](https://waffo.com/docs/api-reference/收单商户api接口/update-subscription-session.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.