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.

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

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.