Key Features and Changes of A+ Service Activation
Version
Version | Description | Effective time |
v1.4 | Barcode transaction updated remarks column on the user transaction details page | 2024.11.01 |
v1.3 | Acquirer/merchant cannot view/change RSA2 key on old portal. | 2024.10.14 |
v1.2 |
| 2024.03.11 |
v1.1 |
| 2024.01.22 |
v1.0 | Initial | 2023.12.12 |
Background
Merchants in Hong Kong (offline scenarios) can effortlessly onboard the A+ payment service, allowing A+ wallet users to make payments directly at stores in Hong Kong.
The following are detailed descriptions of the changes that occur after enabling A+ payment. In summary, A+ payment service enablement is specifically designed for offline payment scenarios.
- After enabling A+ wallet payment, AlipayHK will provide a new portal. This new portal will display all transactions, including HK wallet, CN wallet, and A+ wallets. Meanwhile, the old portal will still remain accessible.
- New portal: https://merchant.alipay.hk/merchant/login/link?tntInstId=ALIPW3HK
- After system upgrade, settlement/transaction data of the old portal may be inaccurate. As old portal data were limited to transactions in HK&CN wallets only and A+ wallet transactions are not visible, it is strongly recommended institutions/merchants use the new portal
- After enabling A+ wallet payment, AlipayHK will settle all transactions together, including HK wallet, CN wallet, and A+ wallets. The transaction files and settlement files will also include all wallets, without a separate settlement specifically for A+ wallets.
- The settlement bank account on the AlipayHK side will be changed to CITIHK.
- The existing APIs used by institutions/merchants can still be utilized, and there is no need for extra development work to support A+ wallets in offline scenarios.
- 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.
- If users are using A+ wallet instead of HK&CN wallets, certain values in the response message will be different. The details of these changes are as follows.
- When using the precreate API, the domain name of the qr_code field in the response message will different. The details of these changes are as follows.
- In the sandbox environment, A+ wallet is not available. However, the sandbox environment for HK&CN wallets remains unchanged and can still be accessed as before.
< This steamless A+ payment service onboarding is for offline scenarios only. The daily operations and technical integration for online scenarios will remain 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 | Onboard the A+ Payment Service Allowing A+ wallet users to make payments at stores in Hong Kong After the PID is cutovered, users can use A+ wallets for payments. | |||
HK&CN Wallet | A+ 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. However, as the old portal data were limited to transactions in HK&CN wallets only and A+ wallet transactions are not visible, it is recommended that institutions/merchants use the new portal. | The new portal was launched in January 2024. After onboarding the A+ payment service, 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. | No contract confirmation is required through the portal for onboarding A+ payment service. | ||
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 AlipayHMTtechsupport@service.alipay.com for assistance. The new portal currently does not support setting a security email for account information. *The portal system function will be updated gradually, and the capability to set a security email for account information will be supported after the upgrade. | ||
A.1.4. Viewing/Changing Key Information | The acquirer/merchant cannot view or make changes to the RSA2 key on the old portal. *If any key view or changes are required, please contact AlipayHMTtechsupport@service.alipay.com for assistance. | The new portal does not support viewing or changing the secret key. *If any key changes are required, please contact AlipayHMTtechsupport@service.alipay.com for assistance. **The secret key used for the A+ wallet needs to be consistent with the existing secret key used for the HK&CN wallet. All wallets are using the same keys | ||
A.1.5. View PID information | The acquirer/merchant can still use the existing old portal to view PID information | No need to confirm PID information through the portal for A+ wallet onboarding as there are no changes to existing 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 transaction information, but only for transactions using HK&CN wallets. A+ wallet transactions are not visible on old portal, it is recommended that institutions/merchant use the new portal to view transaction information. | The acquirer/merchants can use the new portal to view transaction information, including transactions in HK&CN Wallet and A+ Wallet *For HK&CN wallet transactions, you can view transactions after January 1, 2023 *A+ wallet transactions show the real A+ Wallet name | |
A.2.2. View settlement information | Please check the settlement information on the new portal as it will display both HK&CN wallets' and A+ wallets' transactions settled together. | The acquirer/merchants can use the new portal to view detail settlement information, including HK&CN wallet and A+ wallet transactions. The total To-be-Settled Amount is not availabile *A+ wallet transactions show the real A+ wallet name | ||
A.2.3. Refunds | The acquirer/merchant can still use the existing old portal to perform refund, but only for transactions in HK&CN wallets. A+ wallet transactions are not visible on old portal, it is recommended that institutions/merchant use the new portal to view transaction information. | The acquirer/merchants can use the new portal to perform refund, including HK&CN wallet, as well as A+ wallet transactions *A+ wallet transactions show the real A+ wallet name | ||
A.3. File Downloads | A.3.1. Settlement and Transaction | Since the data in the old portal may be inaccurate after the system upgrade and does not include A+ wallet transactions, it is recommended institutions/merchant use the new portal to download bills. | The acquirer/merchants can use the new portal to download settlement and transaction documents, including HK&CN wallets, as well as transactions in A+ wallets (this feature will be available at the end of Jan 2024). *A+ wallet transactions will be marked as ALIPAY_HK transactions | |
A.3.2. Transaction Details | Since the data in the old portal may be inaccurate after the system upgrade and does not include A+ wallet transactions, it is recommended institutions/merchant use the new portal to download bills. | The acquirer/merchants are temporarily unable to download transaction details files through the new portal for specific date ranges. However, you can view the details of all transactions *The portal system function will be updated gradually, and this capability will be supported after the upgrade. | ||
A.4. Merchant QR Code | The acquirer/merchant can still use the existing old portal to apply for a static Merchant QR Code. The Merchant QR Code will support HK&CN wallet and A+ wallet users | The A+ wallet does not have a separate Merchant QR Code. The acquirer/merchants cannot apply for a Merchant QR Code through the new portal. If you need a Merchant QR Code, please log in to the old portal. | ||
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. The transactions from both HK&CN wallets and A+ wallets will be consolidated into a single file. A+ transactions will be marked as ALIPAY_HK in the files. (Please use the new domain name https://isftp-sea.alipayplus.com when connecting to SFTP). Regarding the secondary merchant information display on SFTP files, we have made the following upgrades: When initiating a transaction request, pass the parameters secondary_merchant_industry/secondary_merchant_id/secondary_merchant_name/store_id/store_name, the presenting logic on the SFTP files will be follow:
Therefore, on the scenario #2: it will be different on the file when merchant initiating a transaction request merchant's name don't match with on-boarding information merchant's name. There's a discrepancy between old and new file. It unaffected if merchant does not consume the secondary merchant name or MCC information | |
B.1.2 ISV Rebate Files | The existing channels for receiving rebate files remain unchanged (A+ transactions will be included to the files which will be marked as ALIPAY_HK ). 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. | AlipayHK will settle all transactions together, including HK wallet, CN wallet, and A+ wallets. Hence there will be no separate settlement limit for A+ wallet | |
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 APIs | C.2.1 API Categories | All existing APIs are available * Pricing currency for the transaction can't be CNY as usual | No need for extra development work to support A+ wallets in offline scenarios. Below payment approach could be supported: Barcode Payment (dynamic QR): alipay.acquire.overseas.spot.pay Merchant QR Code (static QR ): alipay.commerce.qrcode.create Transaction QR Code (dynamic QR): alipay.acquire.precreate * Pricing currency for the transaction can't be CNY as usual | |
C.2.2 Pre-Ordering | The domain name returned by the pre-order API (alipay.acquire.precreate ) will be changed from https://qr.alipay.com/ or https://qr.alipay.hk/ to https://qr-acquire.alipay.hk The code value of the QR code will be changed to CGCP format, for example, 28100404049490oR1kpN70dFoW7RL1K49kAJ The definition of the response field of the pre-order API remains unchanged | |||
C.2.3 Barcode Payment | No change in CN wallet Barcode transaction in HK wallet updated remarks column on the user transaction details page (Display memo value, if empty will display trans_name value) | The remarks field will not be displayed in A+ wallet | ||
C.3. Asynchronous Notification Response | C.3.1. Wallet User Information | Remains the same | Below return values for transactions in the A+ wallet will be fixed buyer_email: alipaygnbuyer@email.com buyer_id: 2088000000000000 The actual return values will display desensitized values. buyer_email: alip***@email.com buyer_id: 2088000000000000 | |
C.3.2. Wallet Category (field payment_inst ). | Remains the same | Since A+ wallet transactions will simulate the AlipayHK transactions, the payment_inst field will return ALIPAY_HK *After the backend system upgrade, it will support returning the actual A+ wallet name, such as GCASH. It is essential for acquirers/merchants to confirm if any special requirements for processing this field in their downstream systems to avoid any potential system handling issues due to the new A+ wallet names. If your system is unable to process A+ wallet name, please contact our SA in advance for special configuration handling. | ||
C.3.3. Exchange Rates (field forex_rate ). | Remains the same | Since the A+ wallet will simulate the AlipayHK wallet transactions, the forex_rate field will return a fixed value of 1 | ||
C.3.4. Payment Instruments (field paytools_pay_amount). | Remains the same | For A+ wallet transactions that simulate AlipayHK transactions, the paytools_pay_amount field will be similar to: [{"ALIPAYACCOUNT": "12494.99"}]. In this case, the amount represents the order amount. *After the backend system upgrade, it will support returning the actual A+ wallet name, e.g. [{"GCASH":"123.9"}]. It is essential for acquirers/merchants to confirm if any special requirements for processing this field in their downstream systems to avoid any potential system handling issues due to the new A+ wallet names. If your system is unable to process A+ wallet name, please contact our SA in advance for special configuration handling. | ||
C.4. Barcode Payment Response | C.4.1. Wallet User Information | Remains the same | Below return values for transactions in the A+ wallet will be fixed alipay_buyer_login_id: alipaygnbuyer@email.com alipay_buyer_user_id: 2088000000000000 alipay_buyer_mobile_no: 852-10000000 The actual return values will display desensitized values. alipay_buyer_login_id: alip***@email.com alipay_buyer_user_id: 2088000000000000 alipay_buyer_mobile_no: 852-****0000 | |
C.4.2. Wallet Category (field payment_inst ). | Remains the same | Since A+ wallet transactions will simulate the AlipayHK transactions, the payment_inst field will return ALIPAY_HK *After the backend system upgrade, it will support returning the actual A+ wallet name, such as GCASH. It is essential for acquirers/merchants to confirm if any special requirements for processing this field in their downstream systems to avoid any potential system handling issues due to the new A+ wallet names. If your system is unable to process A+ wallet name, please contact our SA in advance for special configuration handling. | ||
C.5. Query Response | C.5.1. Wallet User Information | Remains the same | Below return values for transactions in the A+ wallet will be fixed alipay_buyer_login_id: alipaygnbuyer@email.com alipay_buyer_user_id: 2088000000000000 The actual return values will display desensitized values. alipay_buyer_login_id: alip***@email.com alipay_buyer_user_id: 2088000000000000 | |
C.5.2. Wallet Category (field payment_inst ). | Remains the same | Since A+ wallet transactions will simulate the AlipayHK transactions, the payment_inst field will return ALIPAY_HK *After the backend system upgrade, it will support returning the actual A+ wallet name, such as GCASH. It is essential for acquirers/merchants to confirm if any special requirements for processing this field in their downstream systems to avoid any potential system handling issues due to the new A+ wallet names. If your system is unable to process A+ wallet name, please contact our SA in advance for special configuration handling. | ||
C.6. Notification | C.6.1 Payment Results | Remains the same | Payment result notification supports notify_url and SMS | |
C.7. Sandbox Environment | Remains the same | There is no sandbox environment for A+ wallets verification. You can contact SA to retrieve a shared-PID for A+ wallet verification. If acquirer/merchant has its own UAT PID, please contact SA to confirm whether the corresponding PID supports A+ wallet | ||
FAQ
1. What does the mentioned A+ wallet refer to?
The A+ wallet mentioned above specifically refers to the Alipay Plus wallet excluding HK&CN wallet. For a detailed wallet list, please find the information below:
https://www.alipayplus.com/mobile-payment-provider-list
2. Do existing merchants need to re-register to support A+ wallet?
No need. After the backend system is upgraded, existing merchants on the institution/merchant side will support A+ wallets automatically. New merchants can register with original way. It is recommended to use API to register secondary merchants.
3. 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.
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 Q1 2024. If your PID still does not support A+ wallet after Q1 of 2024, please contact our commercial service team HKMerchant@alipay.com