Integration

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

System architecture

The following figure illustrates the vending machine solution system architecture:

幻灯片1.PNG

Figure 1. Vending machine system architecture

Generally, the solution contains three parts: front end, back end, and data. Each part contains more specific modules that provides the corresponding services:


  • Front end: Front end contain modules to present merchant QR code, display Alipay brand materials and related marketing materials (where applicable).
  • Back end: Back end might contain modules such as vending machine inventory control, merchandise inventory management, and payment systems.
  • Data: Based on big data platform, merchants can collect and analyze sales data, tagging users, and gain insights on choosing hot districts and carrying out target marketing.

Alipay-provided abilities cover the following modules:

  • Alipay brand exposure: Alipay provides free Alipay brand POSMs for merchants. In addition, design guidebook is provided in case merchants want to design POSMs by themselves.
  • Payment system: Alipay provides various tailored payment services to meet merchants' payment requirements.
  • Sales data, user tag, hot district, and target marketing: Alipay provides various data tools to facilitate the business analysis,  and help merchants gain data insights. For example, based on sales data customers are identified with different tags, and merchants can then carry out target marketing in hot districts accordingly.
  • Cloud server, load balancing, big data platform: Alipay has a lot of mature products and services that can support these modules.

Integrate with Alipay

Before you start, configure and obtain information that is required when you do the integration, such as the identity information, the sandbox environment, and the secret key. Contact Alipay Technical Support at overseas_support@service.alibaba.com if you need help.

Prepare keys

When making API calls, a key is required to sign the data and generate a signature. Prepare keys according to the sign type is specified in the API doc. If RSA/RSA2 algorithm is used, swap the public key with Alipay.

Call APIs

The following sequence diagram illustrates the message-flow and time-order of the vending machine (VM) solution:

Vending Machine1.png

Request QR codes for VM devices

In this solution, a QR code is used to identify a VM device. For each VM device, the merchant must request a QR code by calling Alipay QR code generation interface, print and then post the QR code on the device per POSM display guidelines.

Vending Machine2.png

APIs used:

alipay.commerce.qrcode.create 

alipay.commerce.qrcode.modify

alipay.commerce.qrcode.modifyStatus

Implement transaction processing

After receiving the top up result through the customized API, the vending machine delivers the merchandises the customer selected, and then refund the left balance where applicable.

Vending Machine1.png

API used:

alipay.acquire.overseas.spot.refund 

Test in sandbox environment

After the development for system integration is completed, you can test it in the sandbox. You can make API tests based on your own requirements. See Sandbox for details.  

Go live

When you completed tests in the sandbox environment and get ready to go live, move to production environment by changing the gateway, PID, and keys to real ones.

Best practices

The vending machine server must closely monitor the remaining balance and customer's subsequent purchase operation. In the way, the refund processing (where applicable) can be initiated accordingly and the remaining balance can be returned to customer in time.

Case 1: Pay first and then purchase

Merchant back-end waits 5 minutes for the operation on the device. After 5 minutes, the remaining amount is refunded.

  • If the money runs out, the refund will not be initiated.
  • If the customer does not purchase, or if the money does not run out, a refund is initiated to return the remaining amount.

Case 2: Purchase first and then pay

Merchant back-end waits 25 seconds, and then decide whether a refund should be initiated. After receiving payment result, merchant system immediately delivers goods or initiates a refund.