# Site Builder Assistant Integration

Under the Site Builder Integration mode, users select products, enter recharge account information and complete payment on the PayerMax-hosted branded recharge site. PayerMax will send callbacks to the merchant server at key stages including account verification, order verification and successful payment. The merchant only needs to provide an HTTPS callback address and return corresponding results according to `bizType`. No frontend page or cashier page development is required.

## 1. Interaction Flow

In the diagram below, **solid lines** stand for requests and **dashed lines** stand for responses. Steps marked with `bizType` are PayerMax callbacks to the merchant, which are interfaces that the merchant needs to implement.

```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 User
    participant MServer as Merchant Server
    participant PMax as PayerMax / SITE

    Note over User, PMax: Phase 1 · Order Validation
    User->>PMax: 1. Select product, enter account, click purchase
    PMax->>MServer: 2. Account validation
user.validation
    MServer->>MServer: Verify account validity
    MServer-->>PMax: 3. Return nickname / character list
    PMax->>MServer: 4. Top-up pre-validation
topup.validation
    MServer->>MServer: Validate product, region and amount
Validation only, no order creation
    MServer-->>PMax: 5. Return order-allowed result
    PMax-->>User: 6. Display order confirmation page

    Note over User, PMax: Phase 2 · Payment & Fulfillment
    User->>PMax: 7. Confirm and complete payment
    PMax->>PMax: Accept payment and confirm fund receipt
    PMax->>MServer: 8. Fulfillment notification
topup.notifyResult
    MServer->>MServer: Execute delivery with idempotency by orderNo
Response required within 5 seconds
    MServer-->>PMax: 9. Return deliveryStatus
    PMax-->>User: 10. Display transaction result

    Note over MServer, PMax: Exception Flow
    PMax->>MServer: Active query on timeout or unknown status
topup.queryDelivery
    MServer-->>PMax: Return delivery status for re-delivery judgment
```

`app.queryServer` only needs to be implemented for sharded/server-separated applications and is invoked when the user selects a server. `topup.queryDelivery` is triggered only when the fulfillment notification times out or the delivery status is unknown.

## 2. API List

All APIs below are callbacks initiated by PayerMax to the merchant. The merchant only needs to provide one callback URL. PayerMax distinguishes business scenarios via `bizType` in the common request parameters.

| Corresponding Sequence Step                                     | Call Direction       | bizType               | Integration Requirement |
| --------------------------------------------------------------- | -------------------- | --------------------- | ----------------------- |
| When user selects a server (sharded/server-separated apps only) | PayerMax -> Merchant | `app.queryServer`     | Optional                |
| 2. Account Validation                                           | PayerMax -> Merchant | `user.validation`     | Required                |
| 4. Top-up Pre-validation                                        | PayerMax -> Merchant | `topup.validation`    | Required                |
| 8. Fulfillment Notification                                     | PayerMax -> Merchant | `topup.notifyResult`  | Required                |
| Exception Branch · Delivery Status Query                       | PayerMax -> Merchant | `topup.queryDelivery` | Required                |

## 3. Environment Information

- Callback URL for test environment: Configured by the merchant on the Open Platform for joint debugging.

- Callback URL for production environment: Configured by the merchant on the Open Platform, and launched to production after acceptance.

Open Platform URL: https://developer-site.payermax.com/welcome

## 4. Integration Steps

### 4.1 Configure Signature

All callback requests and responses must be signed with `SHA256WithRSA`. The key adopts PKCS8 format with a length of 2048 bits. The signature value is placed in the HTTP Header field `sign`. Responses for API errors must also carry a valid signature. PayerMax verifies the signature first before processing business data.

Key Generation Tool: https://developer.payermax.com/devtool/generate

### 4.2 Implement Account Validation

After the user enters the game ID on the top-up site, PayerMax calls `user.validation`. The merchant verifies whether the account is valid and returns the nickname and character list for user confirmation.

Sharded/server-separated applications also need to implement `app.queryServer` to return the server list for user selection.

### 4.3 Implement Top-up Pre-validation

Before the user submits an order, PayerMax calls `topup.validation`. The merchant validates the account, product, region and amount, and returns whether the order can be placed.

Note: This API only performs validation and will NOT create an order.

### 4.4 Implement Fulfillment Notification

After the user completes payment, PayerMax calls `topup.notifyResult`. The merchant processes delivery and returns `deliveryStatus` (0 – Delivering, 1 – Delivery Succeeded, 2 – Delivery Failed).

Notes:

- Implement idempotency based on `orderNo` to avoid duplicate delivery for repeated notifications.

- Response must be returned within 5 seconds; timeout will trigger retries.

### 4.5 Implement Delivery Status Query

When the fulfillment notification times out or the delivery status is unknown, PayerMax calls `topup.queryDelivery` to query the delivery result by `orderNo`, which is used for reconciliation and redelivery judgment.

For full parameters, request & response samples and response codes of each API, please refer to the API document: [PayerMax SITE Service Integration API Doc](https://payermax.feishu.cn/wiki/VHOfwquY6iGvNrk6Zd4cCBbJnkb?fromScene=spaceOverview)

## 5. Joint Debugging & Go-Live

- Complete joint debugging of all callback APIs in the test environment. Signature Tool: https://developer.payermax.com/devtool/rsa-sign

- Complete acceptance with at least one real delivery transaction in the production environment. Go live officially after confirming successful delivery and correct order status.