1. Overview

This document helps you understand the Alipay product integration phases, actions to take during the integration, and what support and tools are available during each phase. With the information in this document, you can also anticipate the required resources, works, and man power for the integration during each phase.

Note: This document is not applicable to new version products, such as Barcode Payment (New).

2. Main phases

This chapter introduces integration phases, actions to take during each phase, and the available support and tools. Alipay product integration consists of four phases:

1. Pre-integration
2. Integration
3. Go-live
4. Post go-live       

Note: Certain tasks in Integration phase such as obtaining integration resources and preparing keys can be performed independently, regardless of the progress of Pre-integration phase.

The following figure illustrates the integration process and available tools and supports:

1. Integration process

If you have any question, contact Alipay business developer (BD) or Technical Support (AlipayGlobalTechService@service.alipay.com) for help.

2.1 Pre-integration

Before you can integrate an Alipay product, first learn about the product and define the integration project, then sign the required contracts and onboard with Alipay.

Table 1 lists actions and supports during the pre-integration phase:

Table 1. Pre-integration phase

2.2 Integration

To integrate an Alipay product, configure the system and call the APIs first, then test the integration in sandbox environment, and finally, verify the integration quality with test cases.

Table 2 lists actions and support during the integration phase:

Table 2. Integration phase

2.3 Go-live

After integration is completed, move to production environment and perform live tests. If the tests are passed, the product is ready to go live.

Table 3 lists actions and support during the go-live phase:

Table 3. Go-live phase

2.4 Post go-live

Use post go-live monitoring and supports for product maintenance and optimization.

Table 4 lists actions and support during the post go-live phase:

Table 4. Post go-live phase

3. Pre-integration phase

During the pre-integration phase, contact Alipay to learn about Alipay products and solutions, and discuss the business intent and decide on cooperation details. Then you can sign agreements with Alipay to onboard.

3.1 Initiation and discovery

Complete the following steps for the initiation and discovery stage:

1. Go to Alipay Global Site and click Sign Up to register a business account. See Creating a merchant account for details.
2. Provide your company information and upload certificate documents for qualification review.
3. Provide information about your business and technical environment, and merchant resources.
4. Learn about Alipay products and solutions from the information and documentation available at Alipay Global Site, or by consulting with Alipay supports.
5. Discuss and identify your business opportunities with Alipay.

3.2 Project definition

Complete the following steps to define what needs to be done for a product integration project:

1. Determine which Alipay product to use and prepare your business and technical resources for the integration and contracting.
2. Sign the NDA (if applicable), discuss product implementation details, and evaluate resources input.
3. Produce documentation of merchant system user experience, system integration flows, and so on.

3.3 Contracting and onboarding

Before you start integrating with Alipay products, complete the following steps to onboard with Alipay:

1. Review the required cooperation contracts that are provided by your Alipay BD, and sign the contracts to continue the subsequent steps.
2. Plan the integration schedule with Technical Support:

• Define the time and personnel required for the integration.
• Define sandbox joint test plan with Alipay.
• Define pre-launch test plans and canary release (if applicable) plans with Alipay.

4. Integration phase

To integrate an Alipay product, configure the system and call the APIs first, then tests the integration in sandbox environment, and finally, complete the integration acceptance by using the tools provided by Alipay.

4.1 Performing integration

Configuring sandbox environment and calling APIs are essential steps during integration. Depending on the product, SDKs or demo codes might be provided by Alipay. For in-store payment products, you can also optimize the error handling abilities according to the instructions provided in the specific integration documentation. See the specific product documentation for details.

4.1.1 Obtaining integration resources

Obtain the integration resources such as integration documentation, sandbox app, and sandbox account. Depending on the product, SDKs and demo codes might also be available. To obtain integration documentation, go to Developer documentation page. To obtain sandbox app and sandbox account, go to Sandbox Portal.

For more information about the sandbox, see Sandbox. For more information about SDKs and demo codes, see the specific product documentation.

4.1.2 Configuring system

Configuring system consists of preparing keys and configuring sandbox environment. See the following list for details:

• Preparing keys. To generate a digital signature, a key pair is required to sign and verify the data. You can prepare either a RSA key pair, a DSA key pair, or a MD5 key to generate and verify a digital signature.

• If you can prepare key independently, see Preparing keys for details.
• You can also use Alipay API Tool to generate keys. See Key pair generation for details.

• Configuring sandbox environment. Log in to Sandbox Portal with your merchant account and then configure the sandbox gateway, keys, and account information before calling APIs. See Sandbox for details.
• (optional) Add funds to your sandbox buyer account. Log in to Sandbox Portal, go to Sandbox Accounts > Buyer, then Click Top Up.

4.1.3 Calling API

To integrate a product, Alipay requires that all APIs listed in the integration document of the product to be implemented. Calling API consists of the following steps:

1. Constructing and signing a request
2. Sending the request to Alipay
3. Verifying the response

Depending on which API you called, you might need to verify both the asynchronous notification and the synchronous notification.

If error codes are returned, see the specific API documentation for more information. You can also use iDiagnose to locate the cause of certain errors, such as INVALID_PARAMETER and ILLEGAL_SIGN.

For more information about how to sign a request, how to verify a response, and API request and response examples, see the integration section or digital signature section in the specific product documentation.

Note:

You must implement the secondary merchant management function to register and manage the merchants in Alipay system, otherwise your merchants cannot develop business normally.

4.1.4 Implementing error handling

Alipay returned error codes can be divided into business error codes and timeout or system error codes. During the integration, design mechanisms to handle timeout or system errors, and follow the instructions on handling business error codes. For more information, see the error handling section in the specific product documentation.

4.2 Functional test

Test the product functions in sandbox environment to ensure that your system works correctly with Alipay product. Generally, the following functions must be tested:

• The payment function.
• The refund and cancel function.
• The reconciliation function.
• Secondary merchant management function

Under Sandbox Accounts > Buyer tab, you can add funds to your buyer test accounts by clicking Top Up. For more information about sandbox, see Sandbox for details.

You can also test other functions of the product that you integrate. For more information about the functions, see the specific product documentation.

4.3 Integration acceptance

Complete the following steps to ensure the integration quality:

1. Use iValidate test cases to test the integrated functions in sandbox environment. All related test case for the related product must be completed. See iValidate for more information. You can check all the test cases by downloading the Appendix. 
2. Submit the acceptance report to Alipay according to the contractual/project requirement. After Alipay reviews and approves the report, you will receive a certificate as prove of successful integration.
3. For In-store Payment products, use mock service to help you test and optimize your error handling abilities. See Service mocking for details.
4. For additional error scenarios/cases, you must define the scope of responsibilities, procedures, and document templates and so on with Alipay GMM.

5. Go-live

Complete the actions in the following stages to go live.

5.1 Go-live preparations and test

Complete the following steps before go-live:

1、Move to production environment by changing the gateway, PID, keys, and any other required data to the ones for the production environment.

2、Preparing the keys:

• If RSA keys are used, exchange your public key with Alipay. Contact Technical Support and provide your PID and public key information. Alipay will then make configurations accordingly, and provide you the Alipay public key.
• If MD5 keys are used, obtain the MD5 key by following the steps described in MD5 sign type.

3、(For in-store products) coordinate the canary release plans with Technical Support.

4、Complete the main flow tests in production environment.

5.2 Canary release

For In-store Payment products, coordinate with Alipay BD and Technical Support to implement pilot projects at selected stores to test the product performance.

Alipay, the stores, and you must all provide pilot project reports. Alipay and you then analyze the product performance by using these reports.

5.3 Official launch

Move to production environment and launch the product.

6. Post go-live

Use iMonitor to implement the product performance monitoring after official launch. iMonitor provides real-time data and date playback for key indicators, and can automatically send alerts to you according to customizable rules.

For more information about iMonitor, please contact Technical Support (AlipayGlobalTechService@service.alipay.com).

Appendix

📎tech_integration_test_cases.xlsx