7. NewPay H5 Payment Integration

1. Overview

This solution is designed for third-party merchants to implement payment functionality within the NewPay App using embedded H5 pages. Merchants build orders on the H5 side and invoke the native payment component via NewPay’s routing protocol.

2. Business Workflow

1. App Launch: NewPay App opens the merchant's H5 URL and injects identity parameters.

2. Order Creation: The H5 page collects parameters and calls the merchant’s backend to create an order.

3. Invoke Payment: The H5 page redirects to the NewPay Payment Center using the payment URL.

4. Callback/Return: Upon completion, the App automatically redirects back to the merchant’s specified redirectUrl.

5. Status Verification: The merchant’s backend queries the order's status API to confirm the actual payment result before providing the service.

3. Integration Steps

Step 1: User Authentication (Identity Sync)

When the NewPay App launches the merchant H5 page, it automatically appends the following parameters to the URL Query. Merchants must parse and store these for subsequent requests.

Parameter	Type	Description	Example
userToken	String	User session token for backend validation. More user info can be obtained by querying the user's interface.	eyJh...
userId	String	Unique User ID in the NewPay platform, used when creating order.	100234
lang	String	Language environment (e.g., zh-CN, en-US)	en-US

Merchants need to establish relationships between user platforms through userId, and when creating orders, they must provide user identification.

Step 2: Order Construction & Fetching payUrl

The merchant H5 triggers the Merchant’s Backend API:

1. The Merchant Backend calls the NewPay Payment Gateway (API call).

2. Retrieve the payUrl (payReference in API response) provided by NewPay.

The payUrl follows a specific internal protocol format, start with "newpay://", like

newpay://openApi/?orderNo={orderNo}&type={type}.

Step 3: Invoking the Native Payment Page

After obtaining the payUrl, the merchant H5 must use the urltool protocol to redirect the user. This ensures the native payment module is correctly triggered.

Step 4: Final Status Query (Crucial for Business Logic)

Once the user is redirected to your redirectUrl, your system need to check the order's status to decide the next business step.

1. Check order status: Your H5/Backend calls your own server, which then queries the NewPay Order Inquiry API.

2. Branching Logic:

   • SUCCESS: Proceed with order fulfillment (e.g., show "Thank You" page, unlock digital content).

   • PENDING: Show a "Processing" screen and poll the status again after a few seconds.

   • FAIL/CANCEL: Guide the user back to the checkout page to try again.

4. Parameter Reference

Payment Invocation (NewPayAppOpenApiPage)

Field	Required	Description
payUrl	Yes	The raw payment URL obtained via API.
redirectUrl	Yes	The merchant landing page URL to return to after the payment process (Success/Fail/Cancel).