PayerMax Checkout Integration

Under the Hosted Checkout integration mode, after a user places an order, they are redirected to the H5 checkout page built by PayerMax to make the payment. The PayerMax H5 checkout page displays a list of optional payment methods, while supporting features such as adaptive screen size and multi-language. Under this integration mode, merchants do not need to develop a checkout page, which can greatly simplify merchant integration and shorten the launch cycle.

1. Interaction Flow

%%{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 Client as Merchant Client
    participant MServer as Merchant Server
    participant Checkout as PayerMax Cashier 
    participant PMServer as PayerMax Server
    participant Channel as Payment Channel
Wallet/Bank, etc.

    %% 1. Ordering Phase
    User->>Client: 1.1 Select product and place order
    Client->>MServer: 1.2 Place order
    MServer->>PMServer: 1.3 Create payment
Call Cashier checkout API
    PMServer->>PMServer: Create transaction
    PMServer-->>MServer: 1.4 Return payment creation response
Including PayerMax Cashier URL
    MServer-->>Client: 1.4 Return response
    Client->>Checkout: 2.1 Redirect to PayerMax Cashier page

    %% 2. Payment Phase
    User->>Checkout: 3.1 Select payment method
and submit payment
    Checkout->>PMServer: 3.2 Payment request
    PMServer->>Channel: 3.3 Payment request
    PMServer-->>Checkout: 3.4 Response
Including PayerMax payment result URL
    Checkout->>Checkout: 3.5 Redirect to PayerMax payment result page

    %% 3. Return to Merchant
    User->>Checkout: 4.1 User clicks [Return to Merchant]
    Checkout-->>Client: 4.2 Redirect to merchant-specified page

    %% 4. Obtain Payment Result
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: Obtain Payment Result
        
        Note over MServer, PMServer: Via Payment Result Notification
        PMServer->>MServer: 5.1 Asynchronous notification of payment result
        MServer->>MServer: 5.2 Update payment status
        MServer-->>PMServer: 5.3 Return response

        Note over MServer, PMServer: Via Payment Order Query
        MServer->>PMServer: 6.1 Query payment transaction
        PMServer-->>MServer: 6.2 Transaction details, including payment result
        MServer->>MServer: 6.3 Update payment status
    end

2. API List

Associated Interaction Sequence	Call Direction	API PATH
4.1 Create payment, call checkout order creation API	Merchant -> PayerMax	/orderAndPay
4.4 Payment result asynchronous notification	PayerMax -> Merchant	/collectResultNotifyUrl
4.4 Query payment transaction	Merchant -> PayerMax	/orderQuery

3. Environment Information

• Test environment request address：https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

• Production environment request address：https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

4. Integration Steps

4.1 Create Payment

Payments are created by calling the Create Payment/OrderAndPay API interface and initiating an HTTP POST request. Under the PayerMax checkout integration mode, merchants are allowed to customize the available payment methods for users to choose from. If the merchant does not specify the paymentDetail parameter, all contracted payment methods will be displayed by default.

Note:

Merchants can specify the payment close time in seconds for a single payment via the interface entry expireTime, the value must be greater than 1800 (30 minutes) and less than 86400 (24 hours). If the value passed in is less than 1800, the system will reset to the minimum value of 30min; if the value passed in is greater than 86400, the system will reset to the maximum value of 86400. If the merchant does not specify it, the exact time to close the payment will be different depending on the payment method used.

Create Payment/orderAndPay API example of an interface request:

{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-14T06:29:50.085+00:00",
    "appId": "testb427ca0ef77d19bd25c83",
    "merchantNo": "TEST081764",
    "data": {
        "outTradeNo": "PTEST93137249",
        "subject": "diamond 700",
        "totalAmount": 3.99,
        "currency": "USD",
        "country": "US",
        "userId": "1800110891",
        "language": "en", # Specifies the display language of the PayerMax checkout page
        "frontCallbackUrl": "https://your-payment.33t8y678tyy6rt.top/payment/front_callback?flag=ipaMbjQuest", # The merchant page to jump to after the user completes the payment
        "notifyUrl": "https://your-payment.33t8y678tyy6rt.top/payment/payment_callback", # Payment result callback notification URL. If not specified, the payment result callback notification address configured by the merchant on the PayerMax merchant platform will be used by default.
        "reference": "your special info", # Custom supplementary data, PayerMax will return this information to the merchant during the payment result callback.     
        "integrate": "Hosted_Checkout",
        "expireTime": "1200" # Set the expiration time of this payment to 1200 seconds, meaning if the user does not complete the payment within 20 minutes, the PayerMax system closes the order and determines that the payment failed.
    }
}'

If a merchant does not want to pass notifyUrl every time they make a payment, they can configure a unified payment callback result address through the PayerMax Merchant Platform. Create Payment/orderAndPay API example of an interface request:

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST081764&merchantAppId=testb427ca0ef77d19bd25c83&country=US&tradeToken=T2019051406423972799219&language=en&token=358746abf4754e1cba682d1391336734&amount=3.99&currency=USD&version=1.4&cashierId=T2019051406423972799219&frontCallbackUrl=https%3A%2F%2Fyour-payment.33t8y678tyy6rt.top%2Fpayment%2Ffront_callback%3Fflag%3DipaMbjQuest&pmaxLinkV=1",
        "outTradeNo": "PTEST93137249",
        "tradeToken": "T2019051406423972799219",
        "status": "PENDING"
    }
}

4.2 Jump to PayerMax checkout page

Create Payment/orderAndPay API The interface response redirectUrl represents the PayerMax checkout page URL, and after receiving the response, the merchant can redirect to jump to the PayerMax checkout page, where the user completes the payment.

4.3 Jump to payment result page

After the user completes the payment, the PayerMax Cashier page redirects to jump to the PayerMax Payment Results page.The PayerMax Payment Results page displays the results of the payment (as shown in the image below), and the page contains Close or Back button, when the user clicks on it, it jumps to the page frontCallBackUrl specified by the merchant.

Merchants should ensure that the frontCallBackUrl they pass in is available to external browsers. The differences between the different frontCallBackUrl forms of the jump are as follows:

frontCallBackUrl form	Jump flow after payment completion	Recommended or Not	Advantages	Disadvantages
Ordinaryh5 (http/https)	Stay in the system browser and display the H5 page	No	/	Does not have the ability to evoke an app
Built-in active evoke APP logic h5 (http/https)	Display this H5 page, and at the same time, the logic within the page actively recognizes the scenario for merchant app evocation action, or stays on this page	Yes	Flexible logic and controlled processes	Complex development, to evoke the APP still need to use URL Scheme or AppLink/Universal Link
URL Scheme (Customized scheme://)	The system automatically tries to evoke the APP specified by Scheme. If the APP exists and has permission, it can open the corresponding APP; If the APP does not exist or has no permission, it stays in the system browser and displays a blank page;	No	Easy to develop	No degradation logic, will show a blank page when APP is not evoked
AppLink/Universal Link (http/https)	The system automatically tries to evoke the APP specified by Scheme. If the APP exists and has permission, it can open the corresponding APP; If the APP doesn't exist or doesn't have permission, it stays in the system browser and displays the content of the degraded H5 page	Yes	Development logic is relatively simple, can be downgraded to use H5 to deal with business logic

The URL back to Merchant consists of two parts, the first part is theCreate Payment/orderAndPay API frontCallbackUrlof the interface request,the second part is the extra parameters attached to PayerMax. Below is a complete example of a jump URL:

The additional parameters attached to PayerMax include:

• outTradeNo：Merchant Order Number;

• tradeToken：PayerMax order number;

• status：Order Status. In particular, please do not use this value to update the merchant order status directly, you should follow Step 4: Get Payment Result as the basis for processing as a way to ensure the accuracy of the transaction status.

4.4 Get Payment Result

4.4.1 Adoption of notification of payment results

See 链接要更新Get Payment Result Integration - Adoption of Payment Result Notification.

4.4.2 Inquiry via Payment Orders

See 链接要更新Get Payment Result Integration - Inquiry via payment order.