Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Integration

The following sections explain how you can design your system and integrate with Alipay.

System architecture

The Alipay taxi solution can be designed with three modules: the front end, the back end, and the data analysis layer. Each module contains specific functions for providing corresponding services.

The following system architecture is an example for your reference to integrate taxi company systems with Alipay systems:

taxiarchiu.png

Figure 1. An example of a system architecture designed for Alipay taxi solution

  • Front end: Contains several underlying components to ensure a user-friendly interface. The reservation, notification system, trip management system, and GPS system can be designed to provide customers easy entries for taxi related services. Order management system is also needed to support the online ordering service, which is linked to taximeters and passenger devices to assist with checking out bills. Cloud service, object storage, and load balancing are also functional parts better to be included.
  • Back end: Contains at least the taxi matching logic processor, order system, payment system, and bill management system. Also a cloud service can be included.
  • Data analyzer: Contains modules to handle customer data and sales data, and several sub modules that can be customized.

Alipay can provide technical support for the following modules:

  • Reservation & Notification system: Alipay can provide taxi reservation abilities and notification service with payment amount and payment result displayed.
  • Order management: Used for dealing with taxi payment orders via Alipay.
  • Passenger device: The payment entry on customers' mobile device.
  • Taximeters: Can integrate with Alipay to get the ability to receive payment notifications and check accounts.
  • Payment system: Connected to Alipay gateway directly or indirectly through an acquirer gateway, integrated with the Alipay payment interface.
  • Bill management system: Alipay can provide the bill management ability to help with payment type distinction.
  • Business analysis, Marketing, Process optimization, User research, Industry trends: Alipay can provide transaction data and marketing related data for these modules.
  • Cloud server, Object storage, Load balancing, Big data platform: Alibaba group has a lot of mature products and services that can support the functions of these modules.

Integration with Alipay

Alipay taxi solution specializes in the payment service and the other services closely related to payment. You can integrate with Alipay by calling related APIs. 

Before integration, you need to create an Alipay account and an Alipay application. Besides, the development environment and keys also need to be configured. You can use the sandbox environment to test the integration before going live. The following content provides some key information about the integration process. For more details about integration, please contact Global Merchant Technical Support at overseas_support@service.alibaba.com.

Prepare your account information

Obtaining the APPID that is used in the production environment:

  1. Check whether you have submitted your company information and completed the validation. If not, contact Alipay Global Merchant Technical Support for help.
  2. Go to Alipay Openplatform, and enter your Global Alipay account credentials when prompted.
  3. Create a new app by clicking the button under 创建应用 on the upper left corner. Follow the instructions to provide the required information.
  4. After the app is successfully created, select the app, and then click 查看. On the 概览 tab, you can view information such as APPID, secret key. In addition, you can configure other settings such as the authRedirect URL.

Obtaining the test APPID that is used in the sandbox environment:

  1. Check whether you have submitted your company information and completed the validation. If not, contact Alipay Global Merchant Technical Support for help.
  2. Go to Alipay Openplatform, and enter your Global Alipay account credentials when prompted.
  3. In the upper navigation pane, under 开发者中心, click 研发服务 > 沙箱应用. View the APPID and other app details on the right pane.

Prepare keys

To generate a digital signature, normally a key is required to sign the data. You must prepare the MD5 private key or the RSA/RSA2 private and public key pair to generate and verify a digital signature.

Implement APIs

To integrate with the Alipay system for a specific service, you can call the Alipay APIs by sending an HTTP/HTTPS request to Alipay and use keys to sign the request before you send them.

The following sequence diagram gives a big-picture of how the merchant, the institution, and Alipay can work together by integrating their systems to each other:

Smart Restaurants Taxi.png

Figure 2. Taxi solution integration flow

  1. Customers open the Alipay app, scan the QR code provided by partners, and visit the page provided by the partner.
  2. When the partner server processes the HTTP request, the HTTP request from Alipay can be identified from the User-Agent value enclosed in the http request header. Then the partner server will redirect the user to the Alipay authorization page and specify the callback page URL in the request parameter.
  3. Alipay authorization page immediately (the user will not notice the page jumps) redirects the user to the partner’s callback page with the auth_code attached. With the auth code, the alipay.system.oauth.token API is called to obtain the Alipay user ID, and then records the Alipay user ID into the session. After that, the partner renders the payment page. 
  4. The user enters the payment amount on the payment page and then submits it to the partner server to process. With the Alipay user ID stored in the session and other required parameters, the partner creates an order by calling the alipay.acquire.create API , and then send the returned Alipay trade number back to the H5 page.
  5. Within the H5 page, the partner calls the jsapi:tradepay interface with the trade number by using the Javascript language to request the payment.
  6. Alipay app prompts the user to confirm the order and pay. The user enters the password to complete the payment.
  7. After the payment succeeds, Alipay sends an asynchronous notification to the partner.
  8. In the meantime, Alipay notifies the user of the successful payment by messages.

Authorization process

The authorization process is needed to get the user_id parameter for creating a payment order. To obtain user_id, complete the following steps:

  • Configure account information
  • Configure callback URL
  • Obtain the Alipay user ID

For more information about the processes, see How to obtain Alipay user_id. API used: alipay.system.oauth.token

Payment process

After implementing the authorization process, the payment page is rendered. The customer is prompted to enter the payment amount and then submit it for further process.

  1. Payment order placed from the server side: With the Alipay user ID obtained and other required parameters, a payment order is placed by calling Alipay API. The Alipay trade number returned will be used in the next step.
  1. Alipay in-app purchasing page rendered: To render Alipay in-app purchasing page, where the customer is prompted to confirm the payment and enter password to pay, the jsapi.tradePay API need to be called with the returned Alipay trade number.

Test in sandbox environment

Sandbox is an environment where you can mimic the characteristics of the production environment and create simulated responses from all APIs the application relies on before going live. You can make API tests based on your own requirements including making a transaction, cancel, or refund a transaction, and so on.

Go Live

When you have completed tests in the sandbox environment and are ready to go live, you can turn to the production environment by changing the gateway, PID, and keys to real ones.

Notes

  1. In this solution, in addition to the partner ID information, the system provider needs to apply for the AppID and configure the authorization callback address on open.alipay.com. For more details, see
    Https://docs.open.alipay.com/399/106843/ .
  2. If the vehicle information is not added in the QR code of each vehicle, the operation of manually entering the vehicle number for payment is needed.
  3. After the payment is completed, it is suggested to add some dynamic effects to the payment confirmation page that is displayed to the driver, to avoid malicious screenshots.

Exception handling

Error codes from Alipay can be divided into the following types:

  • Timeout or system errors
    Depending on network stabilities, timeout errors might occur on the QUERY and REFUND interface requests. At the same time, Alipay might return SYSTEM_ERROR for internal system problems. In both cases, you can retry or query to get aligned with the final transaction status in Alipay.

    Mechanisms need to be designed in the integration phase to handle this kind of errors. If such errors appear in production environments, partner’s alarm mechanism need to be triggered, and investigation must be made to help fix the problems.

  • Business errors
    Business errors need to be expressed in a way that the cashiers can easily understand. In addition, the cashiers need to be trained to handle these errors or explain errors to customers.