# 建站助手集成

建站助手集成模式下，用户在 PayerMax 托管的品牌充值站内选择商品、填写充值账号并完成支付，PayerMax 在账号校验、下单校验与支付成功等节点回调商户服务端。商户只需提供一个 HTTPS 回调地址，按 `bizType` 返回对应结果，无需开发前端页面与收银台。

## 1. 交互流程

下图中**实线**为请求，**虚线**为响应；标注 `bizType` 的步骤为 PayerMax 回调商户，即商户需要实现的接口。

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as 用户
    participant MServer as 商户服务端
    participant PMax as PayerMax / SITE

    Note over User, PMax: 阶段一 · 下单校验
    User->>PMax: 1. 选择商品、填写账号、点击购买
    PMax->>MServer: 2. 账号校验
user.validation
    MServer->>MServer: 校验账号有效性
    MServer-->>PMax: 3. 返回昵称 / 角色列表
    PMax->>MServer: 4. 充值预校验
topup.validation
    MServer->>MServer: 校验商品、地区、金额
仅校验，不落单
    MServer-->>PMax: 5. 返回可下单结果
    PMax-->>User: 6. 展示订单确认页

    Note over User, PMax: 阶段二 · 支付发货
    User->>PMax: 7. 确认并完成支付
    PMax->>PMax: 受理支付、确认收款
    PMax->>MServer: 8. 通知发货
topup.notifyResult
    MServer->>MServer: 按orderNo幂等，执行发货
须5秒内响应
    MServer-->>PMax: 9. 返回 deliveryStatus
    PMax-->>User: 10. 展示交易结果

    Note over MServer, PMax: 异常分支
    PMax->>MServer: 超时或状态未知时，主动查询
topup.queryDelivery
    MServer-->>PMax: 返回发货状态，据此判定补发
```

`app.queryServer` 仅分区分服的应用需要实现，在用户选择服务器时调用；`topup.queryDelivery` 仅在通知发货超时或发货状态未知时触发。

## 2. 接口列表

以下接口均由 PayerMax 回调商户。商户只需提供一个回调 URL，PayerMax 通过公共请求参数中的 `bizType` 区分业务。

| 关联交互时序                       | 调用方向         | bizType               | 集成必要性 |
| ---------------------------------- | ---------------- | --------------------- | ---------- |
| 用户选择服务器时（仅分区分服应用） | PayerMax -> 商户 | `app.queryServer`     | 可选       |
| 2. 账号校验                        | PayerMax -> 商户 | `user.validation`     | 必接       |
| 4. 充值预校验                      | PayerMax -> 商户 | `topup.validation`    | 必接       |
| 8. 通知发货                        | PayerMax -> 商户 | `topup.notifyResult`  | 必接       |
| 异常分支·发货状态查询             | PayerMax -> 商户 | `topup.queryDelivery` | 必接       |

## 3. 环境信息

- 测试环境回调地址：商户在开放平台配置，用于联调。

- 生产环境回调地址：商户在开放平台配置，验收通过后对外投产。

开放平台地址：https://developer-site.payermax.com/welcome

## 4. 集成步骤

### 4.1 配置签名

所有回调的请求与响应都要用 `SHA256WithRSA` 签名，密钥格式 PKCS8，长度 2048 位，签名值放在 HTTP Header 的 `sign` 字段。接口报错时响应也必须带签名。PayerMax 会先验签，验签通过后才处理业务数据。

密钥生成工具：https://developer.payermax.com/devtool/generate

### 4.2 实现账号校验

用户在充值站填写游戏 ID 后，PayerMax 调用 `user.validation`。商户校验账号是否有效，并返回昵称和角色列表，供用户确认。

分区分服的应用还需要实现 `app.queryServer`，返回服务器列表供用户选择。

### 4.3 实现充值预校验

用户提交订单前，PayerMax 调用 `topup.validation`。商户校验账号、商品、地区和金额，返回能否下单。

注意：该接口只做校验，不落单。

### 4.4 实现通知发货

用户支付成功后，PayerMax 调用 `topup.notifyResult`。商户执行发货，并返回 `deliveryStatus`（0-发货中，1-发货成功，2-发货失败）。

注意：

- 按 `orderNo` 做幂等，重复通知时不能重复发货。

- 必须在 5 秒内响应，超时会触发重试。

### 4.5 实现发货状态查询

通知发货超时或发货状态未知时，PayerMax 调用 `topup.queryDelivery`，按 `orderNo` 查询发货结果，用于对账和补发判定。

各接口的完整参数、请求响应示例和响应码，请查看API 文档：[PayerMax SITE 服务集成 API 文档](https://payermax.feishu.cn/wiki/VHOfwquY6iGvNrk6Zd4cCBbJnkb?fromScene=spaceOverview)

## 5. 联调与上线

- 在测试环境完成全部回调接口联调。签名工具：https://developer.payermax.com/devtool/rsa-sign

- 在生产环境完成至少一笔真实发货验收，确认发货成功、订单状态正确后正式上线。