Alipay+ DocsAlipay+ Docs
APIs & SDKs

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.

幻灯片1.PNG

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

  幻灯片2.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

Module

Item

AMS

Alipay+

Business

Business contract

  • B15 Acquiring contract
  • Alipay+ PA

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

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

Marketing capabilities

  • Alipay+ standard marketing capabilities
  • Alipay+ standard marketing capabilities

Clearing & settlement

Clearing cycle

  • T+4
  • T+2

Clearing calender

  • Subject to several country's bank holidays
  • Subject to several country's bank holidays

Reports

  • Reports based on wallets
  • Alipay+ unified reports (no distinction among wallets)

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

Integration acceptance

  • AMS integration acceptance capability
  • Alipay+ integration acceptance capability

Merchant registration

  • Register via email
  • Register via API
  • Register via email

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
IOS and Android version

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:
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

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>
<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 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:

Alipay+ Cashier Payment supports two modes: Bundle Mode and Tile Mode. In the 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.