Alipay+ DocsAlipay+ Docs
APIs & SDKs

Migration guide for AlipayCN to Alipay+

Features before & after the migration

Module

Item

Before

After

Business

Business contract

Sign the acquiring contract with AlipayCN.

  • Keep the signed acquiring contract with AlipayCN.
  • Sign with Alipay+ the integration contract, which covers the funds clearing service of AlipayCN.

Fees

  • Fee item: merchant discount rate (MDR)
  • Rule: percentage fee per transaction / Tiered fees

Alipay+ takes the fee accounting. Your experience remains the same.

Capability

APIs

Integrate the MAPIs.

Integrate the Alipay+ APIs.

Supported scenarios

  • Cashier Payment
  • Auto Debit
  • User-presented Payment
  • Merchant-presented Payment
  • Pre-authorization
  • Cashier Payment
  • Auto Debit
  • User-presented Payment
  • Merchant-presented Payment

Credit Pay Installment

Supported

Supported

Refundable transactions before the migration

Request AlipayCN to refund.

  • Request AlipayCN to refund.
  • Funds for refunds:
    • Increased settlement limit.
    • Alipay+ is compatible with history refunds.

Marketing capabilities

AlipayCN marketing capabilities

  • Keep AlipayCN marketing capabilities
  • Other Alipay+ wallets use Alipay+ marketing capabilities

Clearing & settlement

Clearing cycle

T+1

  • AlipayCN: T+1
  • Other Alipay+ wallets: T+2

Reports

Provided by AlipayCN.

Alipay+ provides two sets of reports:

  • One set for AlipayCN
  • One set for other Alipay+ wallets

Settlement

AlipayCN settles to the Acquiring Service Provider  (ACQP).

Alipay+ settles to the ACQP in two batches according to the two sets of reports:

  • One batch for AlipayCN
  • One batch for other Alipay+ wallets

Services for ACQPs

ACQP workbench

AlipayCN back end provides services:

  • Transaction inquiry and refund
  • Report inquiry and download
  • Contract inquiry and changing

Alipay+ back end provides services:

  • Transaction inquiry and refund (available)
  • Report inquiry and download (planned)
  • Contract inquiry and changing (planned)

Integration acceptance

AlipayCN provides the platform for AlipayCN integration acceptance.

Alipay+ provides the platform for the integration acceptance of both AlipayCN and other Alipay+ wallets.

Merchant registration

AlipayCN provides the service for merchants supporting AlipayCN via:

  • APIs
  • Back end

Alipay+ provides the service for merchants supporting AlipayCN and other Alipay+ wallets via:

  • APIs (available)
  • Back end (planned)

Integration differences between AlipayCN and Alipay+

Items

AlipayCN

Alipay+

Developer portal

https://isandbox.alipaydev.com/

https://developers.alipayplus.com/open/console/developer/app/list

Sandbox wallet app

https://isandbox.alipaydev.com/
Android version only

https://developers.alipayplus.com/open/console/developer/app/list
IOS and Android version

Sandbox wallet account info

https://isandbox.alipaydev.com/

https://developers.alipayplus.com/open/console/developer/app/list

ID type

partner_id

clientId

Acceptance Test

https://isandbox.alipaydev.com/
iValidate

https://developers.alipayplus.com/open/console/developer/app/list
Acceptance Test -> Test Suites

Signature type

MD5, RSA, RSA2

RSA256

Signature key setup

https://global.alipay.com/

https://developers.alipayplus.com/open/console/developer/app/list

Signature generation

Key value pair sets sorted in alphabetical order

<HTTP Method> <HTTP-URI-with-query-string>
<Client-Id>.<Request-Time>.<HTTP body>

API fundamental

key=value format in http request parameters

http header: client id & signature, http body: json api payload

Gateway

https://mapi.alipay.com/gateway.do
https://intlmapi.alipay.com/gateway.do
https://globalmapi.alipay.com/gateway.do

https://{host}/api/{restful_path}

Initiate the payment

alipay.acquire.overseas.spot.pay
alipay.acquire.precreate

alipay.acquire.create
jsapi:tradePay

/aps/api/v1/payments/pay

Refund

Sync, async

Sync only

Refund query

alipay.acquire.refund.query

N/A

notifyRegistrationStatus

N/A

/aps/api/v1/payments/notifyRegistrationStatus

Merchant onboarding

API, global merchant portal

API

Reconciliation

T+1 daily available

T+1 daily available

Settlement

T+1 subject to holiday/weekends

CN: T+1, Alipay+: T+2, subject to holiday/weekends

Sftp reports

Transaction file x1
Settlement file x1

Transaction file x2 (summary + details)
Fee file x1
Settlement file x1

Migration solutions from AlipayCN to Alipay+

Cashier Payment

Migrate existing merchants to Alipay+

AlipayCN SDK is integrated into the merchant app

AlipayCN integration document link: Cross-border APP Payment

Before: The merchant sends the order to the ACQP to obtain the orderstr parameter and uses the orderstr parameter to call the AlipayCN SDK's pay method to process the payment.

After: The merchant sends the order to the ACQP to obtain the schemeUrl parameter, and uses the schemeUrl parameter to redirect the user to the AlipayCN app to process the payment. The merchant handles the redirection to the AlipayCN app on its own.

Migration guide for AlipayCN to Alipay+

AlipayCN SDK is not integrated into the merchant app

AlipayCN integration document link: Cross-border APP Payment

Before: The merchant sends the order to the ACQP to obtain the WAP redirection URL that leads to a WAP page, where the user can open the AlipayCN app, download the AlipayCN app, or log in to pay.

After: The merchant sends the order to the ACQP to obtain the schemeUrl parameter, and uses the schemeUrl parameter to redirect the user to the AlipayCN app to process the payment. The merchant handles the redirection to the AlipayCN app on its own.

Migration guide for AlipayCN to Alipay+

Cashier Payment for Merchant WAP page

AlipayCN integration document link: Cross-border WAP Payment

Before: The ACQP constructs the redirection URL that leads to a WAP page, where the user can open the AlipayCN app, download AlipayCN app, or log in to pay. The AlipayCN page handles the subsequent process.

After: The merchant sends the order to the ACQP to obtain the schemeUrl parameter, and uses the schemeUrl parameter to redirect the user to the AlipayCN app to process the payment.

Migration guide for AlipayCN to Alipay+

Cashier Payment for Merchant WEB page

AlipayCN integration document link: Cross-border Website Payment

Scenario 1

Before: The merchant sends the order to the ACQP, the ACQP constructs the redirection URL to the AlipayCN Web page (that supports login-to-pay) and returns the redirection URL to the merchant. The merchant then redirects the user to the AlipayCN Web page.

After: After the merchant sends the order to the ACQP, the ACQP sends the order to Alipay+. Alipay+ returns the redirection URL to the Alipay+ cashier page, which supports scan-to-pay. The user can use the AlipayCN app to scan and pay, without login to the Web page.

Migration guide for AlipayCN to Alipay+

Scenario 2

Before: After the merchant sends the order to the ACQP, the ACQP returns its own QR code to the merchant. The merchant displays the QR code to the user, who scans the code with the AlipayCN app to invoke the app's cashier page.

After: No change on the merchant side. The ACQP needs to identify the wallet's User Agent (UA) and routes the order to Alipay+. The ACQP must send its domain name to Alipay+ to be added to a whitelist.

Fastest migration solution of Cashier Payment for merchants

  • For both SDK and non-SDK scenarios, the ACQP provides the same payment API to the merchant, so the merchant need not be concerned about the parameters after placing the order.
  • The payment API that the ACQP provides to the merchant does not disclose the wallet channel and packages all the redirection URLs for different terminals as one parameter.
  • The only change on the merchant side is that, after sending the order and receiving the response, the merchant opens the AlipayCN app directly by using the returned URL scheme, instead of using the SDK to invoke the AlipayCN app. See sample code below:
copy
Before: call the SDK to open the AlipayCN app.
-(void)payOrder:(NSString *)orderStr fromScheme:(NSString *)schemeStr callback:(CompletionBlock)completionBlock;

After: Open the AlipayCN app directly.
NSString *applinkUrl = @"Your AppLinkUrl";
NSString *schemeUrl = @"Your SchemeUrl";
NSString *normalUrl = @"Your NormalUrl";
NSString *targetUrl;

UIApplication *application = [UIApplication sharedApplication];

if ([application canOpenURL:[NSURL URLWithString:schemeUrl]]) {
    targetUrl = schemeUrl;
} else if ([application canOpenURL:[NSURL URLWithString:applinkUrl]]) {
    targetUrl = applinkUrl;
} else {
    targetUrl = normalUrl;
}


// applink or scheme
if (@available(iOS 10.0, *)) {
    [application openURL:[NSURL URLWithString:targetUrl] options:@{} completionHandler:^(BOOL success) {
        if (success) {
            // do something.
        }
    }];
} else {
    [application openURL:[NSURL URLWithString:targetUrl]];
}

Auto Debit

AlipayCN integration document link: Auto-debit Payment

Before: AlipayCN's authorization API provides the auth ID (the agreement_no parameter) with which the merchant can use for funds capture.

After: Alipay+ uses Oauth2.0, which is different from the authorization process of AlipayCN. See the following notes for details:

Notes on migration from AlipayCN to Alipay+:

  • When AlipayCN users initiate an unbinding, AlipayCN will not call the consultUnbindng API to ask the merchant for permission, but process the unbinding directly.
    • It is recommended that the merchant completes the due capture before providing the actual merchandise/service, or limits the user's overdraft amount.
    • Since AlipayCN can complete the unbinding independently, the ACQP needs to integrate the authNotify API to obtain information about the unbinding.
  • AlipayCN does not have a WAP page for the authorization. If the user starts the authorization from the merchant's WAP page with a browser other than the user's default browser, the redirection back from AlipayCN to the merchant will fail, so the authorization fails. To ensure the authorization success, the ACQP must integrate the authNotify API to obtain the authCode.
Migration guide for AlipayCN to Alipay+

Third-party Merchant QR Code Payment

AlipayCN integration document link: Third-party Merchant QR Code Payment

Before: The ACQP routes the order to AlipayCN according to AlipayCN's UA.

  • Before the merchant migration (merchants use the AlipayCN channel for transaction before, but after migration, they use the Alipay+ channel), identify AlipayCN according to AlipayCN's UA.

Change: The ACQP routes the order to Alipay+ according to the Alipay+ wallet's UA. Alipay+ wallet's UA includes AlipayCN.

  • After the merchant migration, identify Alipay+ wallets according to AlipayCN's UA and Alipay+ wallet's UA.

Alipay+ wallet's UA: AlipayConnect, KAKAOTALK, and PAYAPP

AlipayCN's UA: AlipayClient

The routing strategy differs according to the wallets, migration progress, merchant's willingness, and Alipay+ services:

  • For transactions with wallets using the UAs above:
    • For ACQPs that have integrated AlipayCN
      • AlipayCN transactions
        • Meet all of the conditions: The ACQP has migrated from AlipayCN to Alipay+; the merchant has migrated; the Alipay+ channel is opened.
          • Route transactions to Alipay+.
        • Meet one of the conditions: The ACQP has not migrated from AlipayCN to Alipay+; The merchant has not migrated; the Alipay+ channel is not opened.
          • Route transactions to AlipayCN.
      • Transactions with wallets other than AlipayCN: Route transactions to Alipay+.
    • For ACQPs that have no integrated AlipayCN: Route all transactions to Alipay+.
  • For transactions with wallets not using the UAs above: The ACQP handles transactions according to the wallet's routing rules. Try to avoid conflicts.

Merchant QR Code Payment

AlipayCN integration document link: Merchant QR Code Payment

Before: A merchant obtains the AlipayCN's static merchant QR code in advance and displays the code for customers to scan and pay.

After: Alipay+ does not provide merchant QR codes. Merchant-presented Mode Payment Entry Code is used instead.

Transaction QR Code Payment

AlipayCN integration document link: Transaction QR Code Payment

Before: The ACQP sends the order to AlipayCN to obtain an order code.

After: The ACQP sends the order to Alipay+ to obtain an order code.

No change on the merchant side for this scenario. The ACQP needs to migrate to Alipay+.

Barcode Payment

AlipayCN integration document link: Barcode Payment

Before:

AlipayCN

Alipay+

AlipayCN payment code is used. The transaction is routed to the original channel. Code value regular expression: /^(2[5-9]|30)\d{14,22}$/.

The ACQP is directly connected with AlipayCN. If the payment code starts with a number between 25~30, and has a length of 16~24 digits, route the transaction to AlipayCN.

  • Identify the 19-digit Alipay+ code and route the transaction to Alipay+. Code value regular expression: /^(2[5-9]|30)9\d{10}6\d{5}$/.
  • For other code values, try to decode them according to the ACQP's own logic.
  • If the ACQP cannot decode the code, use the backup logic: Route all CGCP codes that failed to be identified to Alipay+ for decoding. Code value regular expression: /^(2[5-9]|30)\d{14,22}$/.

After: Route all codes with a length of 16~24 digits and starting with 25~30 to Alipay+ after migration.

Note: For User-present Mode Payment, AlipayHK payment codes and AlipayCN payment codes are not processed differently, so before the transaction with AlipayHK can be started, the migration from AlipayCN to Alipay+ must be completed.

After the ACQP completes the migration, migrate the merchants in batches, according to their willingness, integration status, migration schedule, and registration status, so transaction flows directly connected with the AlipayCN channel are migrated to the Alipay+ channel.

Migration process for AlipayCN ACQPs to Alipay+

Preparations

For ACQPs that have integrated with AlipayCN, provide the following information to your Alipay+ Solution Architect (SA):

  • Decide your migration solution. If you meet any of the following scenarios:
    • MS (merchant ID and store ID) has changed.
    • Individual merchants need to be migrated.
    • You do not commission Alipay+ for the migration.

Then you need to submit a mapping table for the merchant's PMS (partner ID, merchant ID, and store ID) before & after the migration, and proactively register the merchants again. If no MS is changed, decide whether to commission Alipay+ for the migration. If Alipay+ is commissioned for the migration, you need to use an email to authorize Alipay+ to handle your data in AlipayCN.

  • Discuss with Alipay+ your schedule for the data migration.
  • Decide your refund solution.
  • Provide the new KYB information to Alipay+.
  • If you have integrated AlipayCN's Credit Pay Installment, ensure that you sign a new contract for Credit Pay Installment after the migration.
  • If multiple fee rates exist in your AlipayCN channel, you need to define the new fee rate IDs and fee rate values in advance.

Note: These preparations are skipped for ACQPs that have not integrated with AlipayCN before.

Onboarding

AlipayCN Onboarding

Prerequisites:

  • The ACQP completes the due diligence questionnaire.
  • Provide the KYB materials to AlipayCN's BD.

AlipayCN contact: BD

For ACQPs, after you receive the onboarding email, you must click the link in the email to change your new login account's password for the AlipayCN portal. Ensure that you save the login account information because the account will be used for integration and authorizations later. Do not mixedly use your old AlipayCN account and the new one.

Alipay+ Onboarding

Prerequisites:

  • The ACQP completes the due diligence questionnaire.
  • Provide the KYB materials to Alipay+'s BD.

Alipay+ contact: BD

For ACQPs, after you receive the onboarding email, you must click the link in the email to change your new login account's password for the Alipay+ portal. The account will be used for DIY services and integration & acceptance later. This account is different from your AlipayCN account. Do not use them mixedly.

Contract signing

AlipayCN contract signing

Prerequisites:

  • The ACQP has signed and stamped the AlipayCN acquiring & settlement contract in the paper version.
  • The ACQP is onboard AlipayCN with a new PID.

AlipayCN contact: BD

Alipay+ contract signing

Prerequisites:

  • The ACQP is onboard Alipay+.
  • The ACQP is onboard AlipayCN.

AlipayCN contact: BD

For ACQPs: Use the account with the new AlipayCN PID to log in to AlipayCN open platform and commission Alipay+ for the AlipayCN integration. You can ask Alipay+'s SA for help with this.

Contract signing for Credit Pay Installment

Prerequisites:

  • The ACQP is onboard AlipayCN.
  • The ACQP uses Credit Pay Installment in the AlipayCN channel.

AlipayCN contact: BD

Integration

ACQP's PID mapping

Prerequisites:

  • The ACQP is onboard AlipayCN.
  • The ACQP has provided the mapping table of the old & new PIDs to Alipay+'s SA.

Alipay+ contact: SA

Commissioning Alipay+ for AlipayCN integration

Prerequisites:

  • The ACQP is onboard AlipayCN.
  • The ACQP has signed Alipay+'s technical integration contact.

Alipay+ contact: SA

The ACQP completes the following steps:

  1. In the email from AlipayCN, find your AlipayCN account information and set up a password:

image.png

  1. Alipay+ sends an email requesting commission for the AlipayCN integration, as shown below. The ACQP then logs in to the AlipayCN developer platform by using the link in the email (use the same browser in the process). This email is automatically sent to the ACQP after the ACQP has signed the integration contract with Alipay+.

image.png

  1. The ACQP user logs in to the AlipayCN open platform with the account from step 1 and register as a developer, and provide the required information. Overseas users do not need to provide a phone number. You must register a developer account so Alipay+ can use the AlipayCN APIs later.

image.png

  1. The ACQP user goes to the management center by clicking the 进入管理中心 button and then clicks the authorization button (确认选择).

image.png

image.png

  1. The ACQP user goes to the authorization page. By default, the ACQP user can confirm the authorization directly by clicking the confirm button (确认授权).

image.png

  1. Complete the authorization and returns to the Alipay+ page. If you see a page as shown below, the authorization is successfully completed.

image.png

Notes:

  • Use Alipay+ open platform for the exchange of encryption keys and signature configuration.
  • After the authorization is successfully completed, do not use the link in the email to retry another authorization.

Acceptance of the Alipay+ integration

Prerequisite: The ACQP is onboard Alipay+.

Alipay+ contact: SA

The ACQP must complete the integration with Alipay+ and completes the required test cases that include scenarios for AlipayCN.

Migration of registered merchant info to Alipay+

Apply for the Alipay+ risk control for merchant registration

Prerequisite:

  • The ACQP has an explicit intention to migrate the merchants.
  • The ACQP's AlipayCN PID before the migration is provided to Alipay+'s SA.
  • The ACQP's AlipayCN PID after the migration is generated.

Alipay+ contact: SA

ACQP registration

Prerequisite:

  • The mapping table for the ACQP's old & new PMS is provided.
  • The ACQP and Alipay+ have decided on the migration schedule.
  • The ACQP has gone live with Alipay+ and integration the Alipay+ registration API.
  • The ACQP has activated the Alipay+ risk controls for merchant registration.

Alipay+ contact: SA

The ACQP must:

  1. Provide the mapping table for the ACQP's old & new PMS.
  2. After Alipay+ imported the PMS mapping table, complete the merchant registration by using the Alipay+ registration API.

After completing the merchant registration, the merchant data can be used seamlessly for the Alipay+ system.

Attachment

Online pamyent API differences between AlipayCN & Alipay+

📎Online API Diff.xlsx

In-store pamyent API differences between AlipayCN & Alipay+

📎Offline API Diff.xlsx