# 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](https://newpay-api-document.gitbook.io/newpay-api-document/5.-apis-v2/5.1-unified-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](https://newpay-api-document.gitbook.io/newpay-api-document/5.-apis-v2/5.2-query-order) 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   | <p>User session token for backend validation.<br><br>More user info can be obtained by <a href="5.-apis-v2/5.5-query-user">querying the user</a>'s interface.</p> | `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`     |

{% hint style="info" %}
Merchants need to establish relationships between user platforms through `userId`, and when creating orders, they must provide user identification.
{% endhint %}

### 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](https://newpay-api-document.gitbook.io/newpay-api-document/5.-apis-v2/5.1-unified-order)).
2. Retrieve the `payUrl` (payReference in API response) provided by NewPay.

{% hint style="info" %}
The `payUrl` follows a specific internal protocol format, start with "newpay://", like &#x20;

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

### 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](https://newpay-api-document.gitbook.io/newpay-api-document/5.-apis-v2/5.2-query-order).
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). |