建站助手集成

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

1. 交互流程

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

%%{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 文档

5. 联调与上线

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

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