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 restaurant solution can be designed to 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 of how you can design the scan, order, and pay system:

image

  • The front end: Contains several underlying components to ensure a user-friendly interface. Pre-ordering, ordering, marketing, and food delivery sections can be designed to provide customers easy entries for restaurant services. Electronic menu is also needed to support the online ordering service. Restaurant POS system and standalone tablet are needed for checking out bills. Cloud service, object storage, and load balancing are also functional parts better to be included.
  • The back end: contains at least the menu system, the ordering system, the payment system, and other IT system for dealing with business logics. Also a cloud service need to be provided.
  • 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:

  • Digital menu: The Alipay-provided interface alipay.system.oauth.token can be used to get the user ID, which is used in the digital menu model to identify ordered dishes belong to different users.
  • Restaurant POS system and Standalone Tablet: Alipay can provide a payment interface for the restaurant POS system and standalone tablet modules to collect payments.
  • Payment system: Connected to Alipay gateway directly or indirectly through an acquirer gateway.
  • Sales data: Alipay can provide the sales data for merchants to perform further analysis.
  • 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

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 AlipayGlobalTechService@service.alipay.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 Alipay system for a specific service, you can call 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 you a big-picture of how the merchant, the institution, and Alipay work together to provide services for customers.

Smart Restaurants Taxi.png

  1. Customers open 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 Wallet 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 Alipay 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.

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.