1. Overview
HaiPay has launched a brand-new Key Configuration Panel, designed to provide merchants with a more convenient and more secure key management experience. The new panel is compatible with the original configuration logic and adds the following core features:- One-click key pair generation — Merchants can generate RSA 2048 public/private key pairs directly on the platform side, without installing additional tools
- Flexible business ID mapping — Supports configuring different public keys for different business IDs (appIds), as well as one-click configuration for “All” business IDs
- Batch key replacement — Intuitively manage the mapping between business IDs and keys through a transfer box
- Multi-dimensional key viewing — Merchant public keys, HaiPay public keys, and encrypted fields are managed in separate tabs
Role of Public and Private Keys
In HaiPay’s communication architecture, public and private keys provide the core security guarantee for request signing and response verification:2. Prerequisites
Before using the key configuration panel, make sure you have completed the following preparations:Obtain a merchant platform account
Log in to the Merchant Management Platform
Enter Development Configuration
3. Panel Overview
After entering “Development Configuration” - “Key Configuration”, you will see the following panel. At the top of the panel there are three tabs, each managing a different type of key:
Key Display and Copy
The key content in the panel is long, so it is displayed with ellipsis in the middle for readability. Click a key field to copy the full content to the clipboard.
4. Business ID Filter
At the top of the panel, the Business ID filter supports single-select dropdown search. You can search all appIds associated with the merchant to filter the view.
- If all of a user’s appIds use the same key, the appId column displays “All”
- No matter which appId the user searches for, the row with the “All” option is always displayed
- When the appId is “All”, businesses added later are automatically configured with this public key
5. Add/Replace Keys
Click the “Add/Replace Key” button in the upper-right corner of the panel to open the key configuration dialog. In this dialog, you can select the key generation method and the business ID mapping scope.
Select the key replacement method
- Recommended Generate all public/private keys with HaiPay — the platform generates an RSA 2048 key pair, the private key is copied to the clipboard, and only the public key is stored on the platform
- Use your own public/private keys — manually enter a pre-generated public key
Select the business ID mapping scope
- All — the key applies to all business IDs
- Specific Business IDs — opens a transfer box to configure the public key for specific business IDs
Generate or enter the key
Confirm the replacement
6. Key Generation Methods
Method 1: One-Click Generation by HaiPay Recommended
This is the simplest method. After you click “Generate”, the HaiPay platform will directly generate an RSA 2048 public/private key pair for you.
Select the generation method
Click the "Generate" button
Click "Add/Replace and Copy Private Key"
Secondary confirmation
- The private key is not stored on the platform — it is only copied to the clipboard this once. Make sure to save it immediately; it cannot be retrieved again after closing the page.
- After replacing a key, the original key becomes invalid immediately, and requests signed with the old key will fail signature verification.
- Perform this operation during off-peak business hours, and make sure the new key has been configured in your system before replacing.
Method 2: Use Your Own Public/Private Keys
If you already have a key pair or prefer to manage the key generation process yourself, you can choose this method. A text box will appear, asking you to enter the public key.
OpenSSL
Online generation tool
Code generation
7. Business ID Mapping
In the Add/Replace Key dialog, “Mapped Business IDs” provides two options: “All” and “Specific Business IDs”. Your choice determines how the key is associated with business IDs.7.1 Keep the Default Mapping (Select “All”)
When “All” is selected, the new public key applies to all business IDs under the merchant. Businesses added later are automatically configured with this public key as well.
7.2 Change Key Mapping (Select “Specific Business IDs”)
When “Specific Business IDs” is selected, a transfer box opens, where you can select which business IDs to map the public key to.

8. Key Overwrite Reminders
When you submit a configuration in the Add/Replace Key dialog, if the new mapping scope would overwrite the association of existing public keys, the system will automatically pop up a key overwrite reminder, informing you which business IDs will be affected. This is designed to prevent signature verification failures caused by accidental operations.8.1 Partial Mapping Overwrite
When your changes affect only some of the mapped business IDs, the system pops up a “Key Overwrite Reminder” dialog that clearly lists the specific affected business IDs. The dialog contains the following:- Title: Key Overwrite Reminder
- Warning message: “This change will overwrite the keys associated with the following business IDs, and the old keys will become invalid immediately. Continue?”
- Affected business IDs: The system lists all affected appIds line by line (e.g., 1122, 3344, 5566)
- Action buttons: “Cancel” (returns to the dialog) / “Confirm Replacement” (proceeds to secondary confirmation)

8.2 Full Mapping Overwrite
When you change a public key that originally maps only some business IDs to “All” business IDs, this operation overwrites the key associations of all business IDs. The pop-up warns that all business IDs will be affected. The dialog contains the following:- Title: Key Overwrite Reminder
- Warning message: “This change will overwrite the keys associated with all business IDs, and the old keys will become invalid immediately. Continue?”
- Action buttons: “Cancel” (returns to the dialog) / “Confirm Replacement” (proceeds to secondary confirmation)

- The new private key has been saved securely and configured in all your business systems
- The operation is performed during off-peak business hours
- The relevant development/operations teams have been notified and are ready
8.3 Secondary Confirmation
Whether you click “Confirm Replacement” in the partial or full mapping overwrite reminder dialog, the system will show a secondary confirmation dialog as the last line of defense. The secondary confirmation dialog contains the following:- Title: Confirm Key Replacement?
- Warning message: “Replacing a key is a high-risk operation. Once the original key is invalidated, it can no longer be used. Proceed with caution.”
- Action buttons: “Cancel” (returns to the overwrite reminder dialog) / “Confirm Replacement” (executes the replacement; the key takes effect immediately)

8.4 Execution Logic After Confirmation
After you click “Confirm Replacement” in the secondary confirmation dialog, the system executes the key replacement immediately. The logic is as follows:9. Replace Key or Change Mapping Individually
In addition to using the “Add/Replace Key” button at the top for batch operations, you can also perform individual operations on a specific public key. In the “Actions” column of the data table, each row provides two action links:
- When replacing a key, the business ID mapping is fixed; only the key content is changed
- When changing the mapping, the public key is fixed and optional to modify; only the mapping scope is adjusted

10. Security Best Practices
- The private key is displayed only once — when the platform generates a key pair with one click, the private key is only copied to the clipboard and is not stored on the platform. It cannot be retrieved again after closing the page.
- merchantSecretKey and the merchant RSA private key are both sensitive information. Do not place them in frontend code, client applications, logs, or public repositories.
- Save the private key immediately — after generating a key, immediately save the private key to a secure key management system or encrypted storage.
- Key leakage response — if a key is accidentally leaked, update the key through the platform as soon as possible.
Signature Security Rules
null nor "", exclude the sign and sign_type fields, sort the remaining field names in ASCII ascending order, and concatenate each key and value in the format k1=v1&k2=v2&.... Append &key=merchantSecretKey (the merchant secret key) to form the string to be signed. The merchant signs the string to be signed with its RSA private key using the SHA256WithRSA algorithm.
11. Key Format Requirements
When uploading a public key to the HaiPay platform, note the following format requirements:12. FAQ
Q: Where is the private key stored after choosing HaiPay one-click generation?
Q: Where is the private key stored after choosing HaiPay one-click generation?
Q: Can the old key still be used after replacement?
Q: Can the old key still be used after replacement?
Q: What does it mean when a business ID shows 'All'?
Q: What does it mean when a business ID shows 'All'?
Q: Why are there multiple pop-up confirmations when replacing a key?
Q: Why are there multiple pop-up confirmations when replacing a key?
- First layer: key overwrite reminder — informs which business IDs will be affected
- Second layer: secondary confirmation dialog — final confirmation of the replacement
Q: How do I configure different public keys for different business IDs?
Q: How do I configure different public keys for different business IDs?
Q: What should I do if signature verification fails?
Q: What should I do if signature verification fails?
- Confirm that the private key you use and the public key uploaded to the platform belong to the same key pair
- Confirm that the signature string is sorted and concatenated in ASCII ascending order
- Confirm that the
signandsign_typefields are excluded - Confirm that parameters with a value of
nullor""are excluded from signing - Confirm that the string to be signed is UTF-8 encoded
- Confirm that loose empty checks (such as PHP
empty()or JS!value) are not used - When verifying response messages, confirm that all new valid fields are included in the verification

