# Migration Guide for AMS to Alipay+

> This guide is designed to facilitate your migration journey from 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.

![幻灯片1.PNG](https://cdn.nlark.com/yuque/0/2022/png/12884741/1671082718860-fa8cf5ef-d7e8-4aad-8144-b6b593f94a1c.png)

**After migration**: ACQPs use **Alipay+ APIs** to connect directly to Alipay+ to enable Alipay+ payments.

  ![幻灯片2.PNG](https://cdn.nlark.com/yuque/0/2022/png/12884741/1671082772730-b965c96b-3a74-4860-8c3e-dc4ae097cb62.png)

**Let's start. The journey from AMS to Alipay+ has two main steps:**

1.  Integrate Alipay+ APIs.
2.  Migrate your existing merchants and business from AMS to Alipay+.

# General Features Before & After Migration

| **Modu****le** | **Item** | **AMS** | **Alipay+** |
| --- | --- | --- | --- |
| Business | Business contract | - B15 Acquiring contract | - Alipay+ PA |
| Business | Fee items | - Merchant discount rate: charged during payment and refundable | - Interchange fee (also known as interpartner fee): charged during payment and refundable - Service fee: charged during payment and non-refundable |
| Product capability | APIs | - AMS API standard | - Alipay+ API standard |
| Product capability | Supported scenarios | - Online: Cashier Payment & Auto Debit - Offline: User-presented Mode & Merchant-presented Mode | - Online: Cashier Payment & Auto Debit - Offline: User-presented Mode & Merchant-presented Mode |
| Product capability | Marketing capabilities | - Alipay+ standard marketing capabilities | - Alipay+ standard marketing capabilities |
| Clearing & settlement | Clearing cycle | - T+4 | - T+2 |
| Clearing & settlement | Clearing calender | - Subject to several country's bank holidays | - Subject to several country's bank holidays |
| Clearing & settlement | Reports | - Reports based on wallets | - Alipay+ unified reports (no distinction among wallets) |
| Clearing & settlement | Settlement | - Settlements based on wallets | - Alipay+ unified settlements (no distinction among wallets) |
| Services for ACQPs | ACQP workbench | - Transaction inquiry and refund - Basic information on ACQPs | - Transaction inquiry and refund |
| Services for ACQPs | Integration acceptance | - AMS integration acceptance capability | - Alipay+ integration acceptance capability |
| Services for ACQPs | Merchant registration | - Register via email | - Register via API - Register via email |

# General Differences & Commonalities

| **Item** | **AMS** | **Alipay+** |
| --- | --- | --- |
| **Differences** | **Differences** | **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 IOS and Android version |
| Sandbox wallet account info | The account is provided in [Test wallet](https://global.alipay.com/docs/ac/ref/testwallet). | Log in with the same account used for Docs Center and Developer Center. |
| Gateway | **URL format:** https://<domain\_name><endpoint> **Domain Name:** North America: open-na.alipay.com Asia: open-sea.alipay.com Europe: open-eu.alipay.com **Endpoint:** /ams/api/v1/payments/pay | **URL format:** https://<domain\_name><endpoint> **Domain Name:** 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: - summary - items | One clearing fee file One settlement file Two clearing transaction files: - summary - details |
| **Commonalities** | **Commonalities** | **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](https://global.alipay.com/open/console/developer/app/list) | Go to the [Developer Center](https://connect.alipayplus.com/account/signin) |
| Signature generation | The syntax of Content\_To\_Be\_Signed: <HTTP Method> <URL> <Client-Id>.<Request-Time>.<HTTP body> | The syntax of Content\_To\_Be\_Signed: <HTTP Method> <URL> <Client-Id>.<Request-Time>.<HTTP body> |
| Signature algorithm | RSA256 | RSA256 |
| Sandbox acceptance testing | Go to the **Test Suites** page under **Acceptance Test** on the [Developer Center](https://global.alipay.com/open/console/developer/app/list) for sandbox acceptance testing. | Go to the **Test Suites** page under **Acceptance Test** on the [Developer Center](https://connect.alipayplus.com/account/signin) 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** | **Differences** | **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** | **Commonalities** | **Commonalities** |
| inquiryPayment | inquiryPayment | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| notifyPayment | notifyPayment | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| refund | refund | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| registration | registration | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| inquiryRegistrationStatus | inquiryRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| notifyRegistrationStatus | notifyRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| inquiryDeclareRequests | inquiryDeclareRequests | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). |
| declare | declare | Names and features remain the same. Slight differences may exist in parameters, see [API list for Cashier Payment](../integration_cashier_acq_tile/api). 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](../redirection_acq_tile/redirection_acq_beta).

## Auto Debit

The differences and commonalities between AMS and Alipay+ in terms of Auto Debit APIs are illustrated below.

| **AMS** | **Alipay+** | **Description** |
| --- | --- | --- |
| **Differences** | **Differences** | **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** | **Commonalities** | **Commonalities** |
| pay | pay | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| applyToken | applyToken | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| inquiryPayment | inquiryPayment | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| notifyPayment | notifyPayment | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| refund | refund | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| registration | registration | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| inquiryRegistrationStatus | inquiryRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| notifyRegistrationStatus | notifyRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| inquiryDeclareRequests | inquiryDeclareRequests | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). |
| declare | declare | Names and features remain the same. Slight differences may exist in parameters, see [API list for Auto Debit](../integration_auto_debit_acq_tile/api). 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 Priv****ate 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** | **Differences** | **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** | **Commonalities** | **Commonalities** |
| pay | pay | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \| [MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |
| inquiryPayment | inquiryPayment | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \|[MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |
| refund | refund | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \| [MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |
| notifyPayment | notifyPayment | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \| [MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |
| registration | registration | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \| [MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |
| inquiryRegistrationStatus | inquiryRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \| [MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |
| notifyRegistrationStatus | notifyRegistrationStatus | Names and features remain the same. Slight differences may exist in parameters, see API lists for [UPM](../integration_user_mode_acq_tile/api) \| [MPM Entry](../integration_merchant_mode_entry_code_acq_tile/api) \| [MPM Order](../integration_merchant_mode_order_code_acq_tile/api) \| [MPM Private Order](../integration_merchant_mode_private_order_code_acq_tile/api) |

# 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 | 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 | 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 | 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+.](../migration_tile/migrate_cn-aps) |

To further discuss the migration plan with us, please contact our solution architect team.