Key Features and Changes of Online Merchant Migration
Version
Version | Description | Effective time |
v1.0 | Initial | 2025.08.04 |
Background
In order to comply with regulatory requirements, the backend system of AlipayHK needs to be migrated. Merchants in Hong Kong (online scenario) need to follow the changes starting from September 15, 2025, and use the corresponding services accordingly.
Overall, there are the following points to note:
- After migration, AlipayHK will provide a new portal. This new portal will display all transactions, the old portal will still remain accessible.
- New portal: https://merchant.alipay.hk/merchant/login/link?tntInstId=ALIPW3HK
- After the system upgrade, there may be inaccuracies in the settlement, pending settlement, and transaction data of the old portal. The data on the old portal is only available for querying data before migration. Therefore, it is strongly recommended that institutions/merchants use the new portal in the future.
- AlipayHK will settle all transactions together, including HK wallet and CN wallet.
- The existing APIs used by institutions/merchants can still be utilized. For unavailable api are detailed below.
- Since the settlement/transaction data of the old portal may be inaccurate after the system upgrade, please use the new portal to query relevant information.
- The sandbox environment for HK&CN wallets remains unchanged.
*To ensure a seamless transition and avoid disruption to the downstream system of the acquirer/merchant after stream switching or migration, it is crucial to consider the following details. If the acquirer/merchant side has specific handling for the response values of AlipayHK APIs, such as verifying the number of response parameters, limiting the length of return values, or processing only the existing enumerated values, please take note of the following analysis. This will help maintain the smooth operation of the downstream system.
A List of Affected Items
Category | Online Merchant Payment Service Migration After the PID is cutovered, users can use new portal. | ||
HK&CN Wallet | |||
A. Merchant Portal | A.1. Merchant Account Management | A.1.1. Portal Login | The acquirer/merchant can continue using their existing account credentials to log in to the old portal. The functionality of the old portal remains unchanged. The new portal was launched already, acquirers/merchants can access the new portal. They can log in using their existing accounts and do not need to go through the process of re-registering. *To log in to the new portal for the first time, you will need to reset your password and receive a verification code via email. Please ensure that your sign-in email address is accessible and that you can receive the verification code information. |
A.1.2. Contract Confirmation | The acquirer/merchant can still confirm new or updated contracts in the old portal. | ||
A.1.3. Change of account information, including login password, email address and payment password | Acquirer/merchants can still use the old portal to maintain their accounts. *Account information in the old and new portals is not automatically synchronized. Changes made in the old portal will not affect the account information of the new portal, and vice versa. The account information for logging into the new portal temporarily does not support self-change for institutions/merchants. The username and password for the old and new portals will not automatically synchronize. *Any changes made to the account information on the new portal will not affect the old portal. *If any changes are required, please contact HKMerchant@alipay.com for assistance. | ||
A.1.4. Viewing/Changing Key Information | The acquirer/merchant cannot view or make changes to the RSA, RSA2 key on the old portal. Viewing and modifying MD5 is not supported. *If any key view or changes are required, please contact AlipayHMTtechsupport@service.alipay.com for assistance. | ||
A.1.5. View PID information | The acquirer/merchant can still use the existing old portal to view PID information | ||
A.2. Transaction Information | A.2.1. View transaction history, including transaction type, status, amount | The acquirer/merchant can still use the existing old portal to view old transaction information, but need to use new portal after migration for new transaction. | |
A.2.2. View settlement information | Please check the settlement information on the new portal. | ||
A.2.3. Refunds | The acquirer/merchant can still use the existing old portal to perform refund, but need to use new portal to perform refund after migration for new transaction. | ||
A.3. File Downloads | A.3.1. Settlement and Transaction | Since the data in the old portal may be inaccurate after the system upgrade, it is recommended institutions/merchant use the new portal to download bills. | |
A.3.2. Transaction Details | Since the data in the old portal may be inaccurate after the system upgrade, it is recommended institutions/merchant use the new portal to download bills. | ||
B. Financial Operations | B.1. Reconciliation Files | B.1.1 Settlement of Transaction Files | The transaction files and settlement files sent via SFTP will maintain the existing format and distribution channels. The login credentials for SFTP server will remain unchanged. (Please use the new domain name https://isftp-sea.alipayplus.com when connecting to SFTP). |
B.1.2 ISV Rebate Files | The existing channels for receiving rebate files remain unchanged. Rebate files can be downloaded through the new portal *Please log in using the PID account associated with the ISV role. | ||
B.2. Settlement | B.2.1 Settlement Limits | During the internal cutover, temporary adjustments will be made to the settlement limits. These adjustments will be in effect during the migration period. Once the migration is completed, the limits will be restored to their normal value. Please note that the expected impact duration is around 2-3 days before and after the migration. | |
C. Technology | C.1. Key Updates (See A.1.4. above.) ） | The acquirer/merchant can still access key information through the old portal, but they cannot make changes to the RSA2 key on the portal.. *If any key changes are required, please contact AlipayHMTtechsupport@service.alipay.com for assistance. | |
C.2. Payment/Query/Refund APIs | C.2.1 API Categories | All existing APIs are available * Pricing currency for the transaction can't be CNY as usual | |
C.3. Document Download APIs | C.3.1. Transaction File Download API forex_compare_file | Only support query day T-1 data. (T as transaction date) The transaction file for day T-1 is generated at 02:00 AM on day T. It is recommended to call the interface to retrieve the file after 02:00 AM, otherwise an error will be reported. The settlement time (column 5) will no longer be returned, and the settlement status (column 8) will always return "P" (paid). (2025/09/15 Effected) | |
C.3.2. Settlement File Download API forex_liquidation_file | Return Error (2025/07/20 Effected) | ||
C.3.3. Exchange Rates File Download API forex_rate_file | Return Error (2025/07/20 Effected) | ||
C.7. Sandbox Environment | Remains the same | ||
FAQ
1. Any affect on merchant transactions during the upgrade?
No affect. This upgrade was AlipayHK's backend upgrade, which is transparent to the institution/merchant, and no service interruption during the upgrade. Please refer to the above content for change point. The changes point fouse on merchant portal and returned fields with specific interfaces.
2. Do existing merchants need to re-register?
No need.
4. How do I know my PID has completed the upgrade?
AlipayHK will gradually upgrade based on PID level. Please note that the prerequisite for upgrade was the request should using new domain name and no longer from old domaines. Old domain names include: http://mapi.alipay.com/ http://www.alipay.com. If you are still using the old domain name, please upgrade to the new domain name as soon as possible: https://api-sea-global.alipayplus.com
The expected upgrade time is Q3 2025. Please contact our integration team hk_integration_support_case@service.alipay.com if you have any question.