Huawei Pay provides a sandbox environment. You can start debugging Huawei Pay integration without actually completing merchant registration. This sandbox environment simulates the Huawei Pay transaction process in a real environment. This allows you to get involved in solution design and joint debugging development in advance, improving integration efficiency.
-
Currently, the sandbox environment supports debugging of only some capabilities and APIs. For details, please refer to Sandbox Environment API Requests and Supported Dimensions.
-
When the sandbox environment is used to verify the payment scenario, no actual fee deduction occurs upon successful payment.
-
Currently, there is no clear sandbox verification identifier for orders created in the sandbox environment and orders in the real environment. You need to distinguish sandbox verification orders from real orders by yourself (for example, by adding a sandbox identifier to the merchant order ID or adding an identifier through the payload field in the pre-ordering scenario).
-
Currently, payment orders in the sandbox environment do not support allocation, generation, query, and download of bills.
[h2]Obtaining Sandbox Environment Configurations
Before sandbox verification, you need to generate sandbox environment configurations (such as the merchant ID, certificate ID, user account, and payment password) for debugging. Currently, you are not allowed to generate sandbox environment configurations. Contact Huawei engineers to obtain the configurations. For any consultation, click here or submit a ticket online to contact us.
To generate sandbox environment configurations, you need to provide the following information.
| Configuration Item | Mandatory | Description |
|---|---|---|
| Merchant model (mercNo) | Yes | Merchant model used for sandbox verification. - DIRECT: direct merchant (common) - AGENT: service provider - PLAT_AGENT: platform merchant |
| Application ID (appId) | Yes | App ID. (To obtain the app ID, sign in to AppGallery Connect, click Development and services, find the desired project in the project list, and obtain the app ID in the App information area on the Project settings > General information page.) The generated sandbox verification configuration needs to be associated with your app. |
| Huawei ID (hwAccount) | Yes | Your HUAWEI ID. It is used to generate the test account, payment password, and other test information. |
| Email address | Yes | Your email address. It is used for receiving subsequent configurations or other information. |
| Service description | Yes | Brief service introduction to your app (screenshots of the app are allowed). |
[h2]Building an App with a Debug Signature
Your app can enter the sandbox environment in test scenarios only when it is in debug mode.
To build a debug-signature app, perform the following steps:
-
Follow the instructions in Managing Certificates and Fingerprints to request an app debug certificate, register a debug device, and request a debug profile.
-
Follow instructions in Configuring Signature Information to configure the signing information in DevEco Studio.
-
Configure the app signing certificate fingerprint in AppGallery Connect.
Sandbox Environment API Requests and Supported Dimensions
REST API request description:
-
Use the following site to debug open APIs in the sandbox environment: https://petalpay-developer-sandbox.cloud.huawei.com.cn
-
The method of requesting REST APIs in the sandbox environment is the same as that in the real environment, with only different configurations. (For details, please refer to Sandbox Environment Debugging Configurations.) For details about API calling, please refer to the common description of REST APIs and the corresponding API description.
Sandbox debugging supports the following capability dimensions.
| Operation Layer | Capability Dimension Description |
|---|---|
| Users | User sign-in: Allows users to sign in with their HUAWEI IDs during payment. Bank card payment: Allows users to select a bank card for payment on the Huawei Pay checkout screen. (By default, a test bank card is bound in test configurations. Currently, users cannot proactively bind a bank card.) Balance payment: Allows users to select balance payment on the Huawei Pay checkout screen. (The balance is preset and cannot be topped up. No fee is deducted after payment.) Password-based payment: Allows users to enter the payment password to complete payment on the Huawei Pay checkout screen. (The payment password cannot be changed.) |
| Merchant (developer) | Launching the checkout screen: Allows your app or atomic service to obtain the prepayment ID (prepayId) through the pre-ordering API, construct the orderStr parameter, and call the requestPayment API to launch the Huawei Pay checkout screen. Calling REST APIs for order query, refund, and others: - Direct merchant: - Pre-ordering: The merchant can call this API to submit Huawei Pay order information and obtain the Huawei Pay pre-order ID. - Payment result callback notification: After a user completes payment, the Huawei Pay server sends a key payment event notification to the developer's server through the callback notification URL (callbackUrl) passed in the API request for pre-ordering. - Payment order query: The merchant can call this API to query the status of a transaction order. - Refund request: The merchant can call this API to refund the order amount to the user. - Refund result notification: After a user completes payment, the Huawei Pay server sends a key payment event notification to the developer's server through the callback notification URL (callbackUrl) passed in the API request for refund. - Refund order query: After requesting a refund successfully, the merchant can call this API to query the refund order status. - Platform merchant/Service provider: - Pre-ordering: The platform merchant/service provider can call this API to submit Huawei Pay order information and obtain the Huawei Pay pre-order ID. - Payment result callback notification: After a user completes payment, the Huawei Pay server sends a key payment event notification to the developer's server through the callback notification URL (callbackUrl) passed in the API request for pre-ordering. - Payment order query: The platform merchant/service provider can call this API to query the status of a transaction order. - Refund request: The platform merchant/service provider can call this API to refund the order amount to the user. - Refund result notification: After a user completes payment, the Huawei Pay server sends a key payment event notification to the developer's server through the callback notification URL (callbackUrl) passed in the API request for refund. - Refund order query: After requesting a refund successfully, the platform merchant/service provider can call this API to query the refund order status. |
Basic Payment Verification
Supported merchant models: direct merchant, platform merchant, and service provider
-
If sandbox verification conditions are met (the sandbox environment debugging configurations have been obtained), you can use the sandbox environment configurations to call the pre-ordering API for direct merchants/pre-ordering API for platform merchants/service providers to obtain the prepayment ID (prepayId), construct the orderStr parameter, call the requestPayment API to launch the Payment Kit checkout screen. (For details about the development procedure, please refer to the basic payment scenario.)
-
The payment process in the sandbox environment is the same as that in the real environment. Related configurations (such as mercNo and authId) needs to be replaced with the site and configurations of the sandbox environment.
-
When the sandbox environment is used, the sandbox environment identifier sandbox_flag needs to be passed in the constructed orderStr. The following is an example:
{"app_id":"101831***","merc_no":"101610000***","prepay_id":"12507011723580897591704***","timestamp":"1751361838042","noncestr":"6f18060eee669126b98e474407cc0682","sign":"OeS+xINxcEoClk+WlsLdnZqL0aIJ5qV734StxULDIgnwz8********************qURxBMzdT2NqdwNefGfrcB5kWVic0RuLz8wqrUPoQBrcl83VVzw59jmgrupitpHMD9sHDpja92H4AMP2SBOdFR2a58qexJves26iTO2f2hsSKFSUEUlHYEW/bgZmVv83GOTo4wIaIbN94gBjkou0kBInTqP2Ht0R9gzVCdB0pYLK+PM4nCY72TkeglyuYHjzD6GlqKMO3UZmuUoqYi8=","auth_id":"101610000031***","reserved":"{\"sandbox_flag\": true}"} -
If the user has not signed in, the system will launch the HUAWEI ID sign-in screen, asking the user to sign in first. Use the sandbox environment account to sign in.
-
-
After the user completes the payment (no actual fee deduction will occur), you will receive a callback notification. You need to handle the callback event. You can also proactively call the order query, refund, and other APIs to complete the entire payment process, including order query and refund.
The payment experience in the sandbox environment, where the payment screen is launched to complete the order payment, is the same as that in the real environment. For details about the screen example, please refer to the basic payment scenario.