Migration Guide for AMS to Alipay+
Overview
This guide is designed to facilitate your migration journey from AMS to Alipay+. You can find changes in terms of business, products, and API integration, as well as other important information about the migration.
AMS: Alipay Merchant Service, a set of APIs offered by Global Site for Acquiring Service Providers (ACQPs) to enable Alipay+ payments.
Alipay+: Alipay Partner Service, a set of APIs offered by Alipay+ for both ACQPs and Mobile Payment Providers (MPPs) to enable Alipay+ payments.
Before migration: ACQPs use AMS APIs to connect to our Global Site to enable Alipay+ payments.
After migration: ACQPs use Alipay+ APIs to connect directly to Alipay+ to enable Alipay+ payments.
Let's start. The journey from AMS to Alipay+ has two main steps:
- Integrate Alipay+ APIs.
- Migrate your existing merchants and business from AMS to Alipay+.
General Features Before & After Migration
Module | Item | AMS | Alipay+ |
Business | Business contract |
|
|
Fee items |
|
| |
Product capability | APIs |
|
|
Supported scenarios |
|
| |
Marketing capabilities |
|
| |
Clearing & settlement | Clearing cycle |
|
|
Clearing calender |
|
| |
Reports |
|
| |
Settlement |
|
| |
Services for ACQPs | ACQP workbench |
|
|
Integration acceptance |
|
| |
Merchant registration |
|
|
General Differences & Commonalities
Item | AMS | Alipay+ |
Differences | ||
Docs Center | https://global.alipay.com/docs/ | https://docs.alipayplus.com/alipayplus/ |
Developer Center | https://global.alipay.com/open/console/developer/app/list | https://developers.alipayplus.com/open/console/developer/app/list |
Sandbox wallet app | https://global.alipay.com/docs/ac/ref/testwallet iOS and Android version | https://developers.alipayplus.com/open/console/developer/app/list |
Sandbox wallet account info | The account is provided in Test wallet. | Log in with the same account used for Docs Center and Developer Center. |
Gateway | URL format: https://<domain_name><endpoint> Domain Name: Asia: open-sea.alipay.com Europe: open-eu.alipay.com Endpoint: /ams/api/v1/payments/pay | URL format: https://<domain_name><endpoint> open-sea.alipayplus.com Endpoint: /aps/api/v1/payments/pay |
inquiryRefund API | /ams/api/v1/payments/inquiryRefund | N/A |
notifyRegistrationStatus API | /ams/api/v1/payments/notifyRegistrationStatus | /aps/api/v1/payments/notifyRegistrationStatus |
pay API | /ams/api/vi/payments/pay | /aps/api/vi/payments/pay |
refund API | /ams/api/v1/payments/refund | /aps/api/v1/payments/refund |
Merchant onboarding | API Global Merchant Portal | API |
Settlement | AlipayCN: T+1 subject to holidays/weekends Alipay+: T+4 subject to holidays/weekends | AlipayCN: T+1 subject to holidays/weekends Alipay+: T+2 subject to holidays/weekends |
SFTP reports | One transaction file Two settlement files:
| One clearing fee file Two clearing transaction files:
|
Commonalities | ||
ID Type | Client-Id | Client-Id |
API structure | HTTP header: client-Id & signature, HTTP body: JSON payload | HTTP header: client-Id & signature, HTTP body: JSON payload |
Signature key setup | Go to the Developer Center | Go to the Developer Center |
Signature generation | The syntax of Content_To_Be_Signed: <HTTP Method> <URL> | The syntax of Content_To_Be_Signed: <HTTP Method> <URL> |
Signature algorithm | RSA256 | RSA256 |
Sandbox acceptance testing | Go to the Test Suites page under Acceptance Test on the Developer Center for sandbox acceptance testing. | Go to the Test Suites page under Acceptance Test on the Developer Center for sandbox acceptance testing. |
Reconciliation | Available on T+1 | Available on T+1 |
Alipay+ API Integration
This section shows the differences and commonalities between AMS and Alipay+ in terms of API Integration.
Cashier Payment
The differences and commonalities between AMS and Alipay+ in terms of Cashier Payment APIs are illustrated below.
AMS | Alipay+ | Description |
Differences | ||
pay | pay | In Alipay+, obtain the normal URL (instead of the redirect URL in AMS) to make proper redirection. |
N/A | consultPayment | New API Use this API to retrieve available wallets from Alipay+. Merchants can then dynamically display the available wallets on their checkout page. |
inquiryRefund | N/A | Alipay+ does not support inquiryRefund API. Instead, Alipay+ supports synchronous idempotent retries of the refund status of a submitted refund request. |
inquiryRegistrationInfo | N/A | APS does not support inquiries of the submitted merchant registration information. |
cancel | cancelPayment | Different names. Features remain the same. |
Commonalities | ||
inquiryPayment | inquiryPayment | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
notifyPayment | notifyPayment | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
refund | refund | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
registration | registration | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
inquiryRegistrationStatus | inquiryRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
notifyRegistrationStatus | notifyRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
inquiryDeclareRequests | inquiryDeclareRequests | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. |
declare | declare | Names and features remain the same. Slight differences may exist in parameters, see API list for Cashier Payment. The declare API is optional: only use it when customs declaration to Customs of China is needed. |
Notes:
In the Alipay+ Cashier Payment - tile mode, up to three URLs can be returned. Use them properly so you can create the best user experience possible. For more information, see Guide on redirections between the merchant and the digital wallet.
Auto Debit
The differences and commonalities between AMS and Alipay+ in terms of Auto Debit APIs are illustrated below.
AMS | Alipay+ | Description |
Differences | ||
N/A | consultPayment | New API Use this API to retrieve available wallets from Alipay+. Merchants can then dynamically display the available wallets on their checkout page. |
N/A | consultUnbinding | New API Use this API to consult whether the auth client allows the access token to be revoked from the wallet side. Exception: In AlipayCN, the access token can be directly revoked without the auth client's permission. |
inquiryRefund | N/A | Alipay+ does not support inquiryRefund API. Instead, Alipay+ supports synchronous idempotent retries of the refund status of a submitted refund request. |
inquiryRegistrationInfo | N/A | Alipay+ does not support inquiries of the submitted merchant registration information. |
consult | prepare | Different names. Features remain the same. |
revoke | cancelToken | Different names. Features remain the same.. |
cancel | cancelPayment | Different names. Features remain the same. |
Commonalities | ||
pay | pay | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
applyToken | applyToken | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
inquiryPayment | inquiryPayment | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
notifyPayment | notifyPayment | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
refund | refund | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
registration | registration | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
inquiryRegistrationStatus | inquiryRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
notifyRegistrationStatus | notifyRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
inquiryDeclareRequests | inquiryDeclareRequests | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. |
declare | declare | Names and features remain the same. Slight differences may exist in parameters, see API list for Auto Debit. The declare API is optional: only use it when customs declaration to Customs of China is needed. |
User-presented Mode Payment, Merchant-presented Mode Payment (Entry Code, Order Code, Private Order Code)
AMS and Alipay+ share the same payment scenarios as follows:
- User-presented Mode Payment (UPM)
- Merchant-presented Mode Payment - Entry Code (MPM Entry)
- Merchant-presented Mode Payment - Order Code (MPM Order)
After migration, the only difference is that Alipay+ supports Private Order Code in Merchant-presented Mode Payment, which is issued by ACQP instead of Alipay+.
- Merchant-presented Mode Payment - Private Order Code (MPM Private Order)
The user scans the QR code presented by the merchant to complete the payment. In this mode, the QR
code is a dynamic order code issued by ACQP.
Private Order Code has the following format: https://my.domain.com/{CGCP code}
Order Code (issued by Alipay+) is only the CGCP code
Notes: Try to avoid using Private Order Code unless necessary, because some Alipay+ wallets may not be able to recognize this type of code without app or configuration upgrade.
The differences and commonalities between AMS and Alipay+ in terms of User-presented and Merchant-presented Mode Payment APIs are illustrated below.
AMS | Alipay+ | Description |
Differences | ||
N/A | userInitiatedPay | New API Use this API in the Private Order Code scenario. |
inquiryRefund | N/A | Alipay+ does not support inquiryRefund API. Instead, Alipay+ supports synchronous idempotent retries of the refund status of a submitted refund request. |
inquiryRegistrationInfo | N/A | Alipay+ does not support inquiries of the registered merchant information |
cancel | cancelPayment | Different names. Features remain the same. |
Commonalities | ||
pay | pay | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM | MPM Entry | MPM Order | MPM Private Order |
inquiryPayment | inquiryPayment | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM |MPM Entry | MPM Order | MPM Private Order |
refund | refund | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM | MPM Entry | MPM Order | MPM Private Order |
notifyPayment | notifyPayment | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM | MPM Entry | MPM Order | MPM Private Order |
registration | registration | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM | MPM Entry | MPM Order | MPM Private Order |
inquiryRegistrationStatus | inquiryRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM | MPM Entry | MPM Order | MPM Private Order |
notifyRegistrationStatus | notifyRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API lists for UPM | MPM Entry | MPM Order | MPM Private Order |
Reports and Reconciliation
AMS and Alipay+ provide clearing transaction reports and settlement reports for reconciliation. Please pay attention to the following differences.
- In Alipay+, you can find transaction batches of the settlement in the settlement report. A settlement report refers to a piece of remittance to the ACQP's banking account. The settlement batch IDs index all the transaction details. Alipay+ does not provide the settlement items report which is provided by AMS.
- Alipay+ introduces the concept of fund direction: Credit and Debit. Credit refers to an addition to the to-be-settled amount, and Debit refers to a deduction from the to-be-settled amount.
- In Alipay+, fee items consist of a refundable interchange fee and a non-refundable service fee. Please note that the service fee is non-refundable.
- Alipay+ generates unified reports based on settlement currency instead of wallets.
The differences and commonalities between AMS and Alipay+ in terms of Reports and Reconciliation are illustrated below.
Report Type | AMS File Name | Alipay+ File Name | Description | |
Clearing | Transaction detail | Transaction Items | Clearing transaction report | All the transaction details to be cleared in a clearing cycle. |
Clearing summary | N/A | Clearing summary report | Summary for clearing data, for example, the total number of transactions in a clearing cycle, the amount for settlement, and so on. | |
Clearing fee | N/A | Clearing fee report | Fees charged for each transaction: interchange fee and service fee. | |
Settlement | Settlement items | Settlement items | N/A | Alipay+ does not provide settlement items but provides settlement batches. |
Settlement summary | Settlement summary | Settlement report | Summary of transactions of a settlement cycle |
Seamless Migration
Alipay+ can make your migration journey as smooth as possible with the following capabilities:
Item | Detail |
Refunds for historical transactions | Refundable historical transactions on AMS can be refunded on Alipay+. |
Existing merchants | Merchants registered with AMS are exempt from re-registration with Alipay+. |
Access token migration to Alipay+ | Alipay+ supports the migration of access tokens, minimizing the impact on merchants and users. (Access token is only applicable for Auto Debit) |
AlipayCN to Alipay+ migration | If your current AMS supports AlipayCN, take additional steps to migrate AlipayCN to Alipay+. |
To further discuss the migration plan with us, please contact our solution architect team.