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:
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:
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.
APIs used:
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.
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.