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

How to set up Alipay pre-authorization?

System architecture

In general, the pre-auth solution will involve the interactions between hotel, acquirer, and Alipay system. You can refer to the following sample to design the whole solution architecture.

Alipay service

Alipay provides the service interface for Acquirer/ISV integration with Alipay. This includes basic functions such as user fund freeze, unfreeze, cancel, transfer, and refund.

Acquirer/ISV backend system

The Acquirer or ISV builds the system to interact with Alipay pre-auth service interface and hotel payment terminal. The Acquirer or ISV can add more modules to match the hotel's requirements, such as merchant management portal, report, reconciliation, and settlement.

Hotel system

At the hotel side, Alipay can provide integration with simple payment terminals and hotel PMS (Property Management System).

Integrating with Alipay

Before you start, configure and obtain information required for integration, such as the ID information, sandbox environment, and RSA key. See more information about the self-integration process at Alipay developers center user guidance, and if you don't have an Alipay merchant account or need help, contact Alipay Technical Support at AlipayGlobalTechService@service.alipay.com.

Call the APIs

To obtain the hotel pre-auth solution's full capabilities, you must first call the Alipay APIs required. You can refer to API List for more details, including request parameters, response, samples, and error codes.

Once the APIs are called, the hotel pre-auth solution can integrated in two steps:

1. Set up the pre-auth.
2. Capture the authorized payment.

Set up the pre-auth

The pre-auth can be set up with either the merchant-scan or customer-scan method.

Customer-scan pre-auth

API used: alipay.fund.auth.order.voucher.create

Cashiers operate the terminal to call the Alipay interface or merchant back office to generate the QR code and present it to the customer. The customer scans the code to complete the funds pre-auth (freezing) by entering the password in Alipay app.

The following graphic illustrates the customer-scan pre-auth workflow.

The customer-scan pre-auth process consists of the following steps:

1. Merchant or ISV calls the alipay.fund.auth.order.voucher.create interface to create a pre-auth code.
2. Alipay server returns the pre-auth QR code.
3. The customer scans the pre-auth code presented by the cashier with Alipay app and confirms the pre-auth by entering the password.
4. Alipay app sends a request for funds pre-auth to Alipay server.
5. The Alipay server returns a page with the pre-auth result to the Alipay app and sends the Alipay notification.
6. If Alipay server doesn't return a result of success pre-auth, the merchant or ISV can poll the result by calling the alipay.fund.auth.operation.detail.query interface until a success result is returned. If the polling process exceeds 30 seconds and still no success result is received, the merchant or ISV can cancel the funds freezing process by calling the alipay.fund.auth.operation.cancel interface.

Related APIs for setting up the pre-auth:

• alipay.fund.auth.operation.detail.query: Query the pre-auth status.
• alipay.fund.auth.operation.cancel: Cancel the pre-auth. After a pre-auth request is submitted, call alipay.fund.auth.operation.detail.query to check status first. If the result is unknown or if the transaction timeouts, call this interface to cancel the pre-auth.
• alipay.fund.auth.order.unfreeze: Unfreeze pre-authed funds. Call this interface with out_trade_no and out_request_no, or with auth_no and operation_id. Partial unfreezing is supported.

Notes:

• Only the merchant can initiate funds unfreezing for frozen transactions. Alipay will not auto-unfreeze the frozen funds.
• The remarks included in the request will be shown in the user’s transaction records in the Alipay app.
• The out_request_no must be idempotent, because the funds are unfrozen per out_request_no. Therefore, out_request_no must be unique for each funds operation.

Merchant-scan pre-auth

API used: alipay.fund.auth.order.freeze

The merchant scans the code from the user’s Alipay app, and calls this API to perform the funds pre-auth. There are two ways to do this, depending on whether a password is required: password-free mode and password-required mode.

Password-free mode:

The following graphic illustrates the password-free mode workflow.

The merchant-scan pre-auth process in the password-free mode consists of the following steps:

1. The customer logs in to Alipay app, and taps Pay in the main screen to enter the payment code screen and presents the payment code to be scanned by the merchant.
2. The merchant or ISV system calls the alipay.fund.auth.order.freeze interface to initiate the funds pre-auth.
3. The Alipay server returns the pre-auth result to the merchant or ISV.
4. The Alipay server returns a page with the pre-auth result to the Alipay app and sends the Alipay notification.

Password-required mode:

The following graphic illustrates the password-required mode workflow.

The merchant-scan pre-auth process in the password-required mode consists of the following steps:

1. The customer logs in to Alipay app, and taps Pay in the main screen to enter the payment code screen and presents the payment code to be scanned by the merchant.
2. The merchant/ISV system calls the alipay.fund.auth.order.freeze interface to initiate the funds pre-auth.
3. The Alipay server returns the pre-auth result to the merchant/ISV.
4. The Alipay server evokes Alipay app to invite the customer makes confirmation about the pre-auth.
5. The customer confirms the pre-auth by entering the password.
6. Alipay app sends the pre-auth request to Alipay server.
7. The Alipay server returns a page with the pre-auth result to the Alipay app and sends the Alipay notification.
8. If Alipay server doesn't return a result of success pre-auth, the merchant or ISV can poll the result by calling the alipay.fund.auth.operation.detail.query interface until a success result is returned. If the polling process exceeds 30 seconds and still no success result is received, the merchant or ISV can cancel the funds freezing process by calling the alipay.fund.auth.operation.cancel interface.

Note:

The value of out_order_no and out_request_no fields must be unique in all cases. The out_order_no and out_request_no might be occupied even if a pre-auth is failed or cancelled. Therefore, when you request a pre-auth again, use new values for out_order_no and out_request_no fields to call the interface. Otherwise, errors will occur.

Capture the authorized payment

API used: alipay.trade.pay

To transfer the pre-auth funds to the hotel, the alipay.trade.pay interface can be called. After receiving the request, Alipay creates the corresponding transaction and pays the funds to the hotel. The merchant system unfreezes the user’s pre-authorized funds, and pays any remaining funds to the customer. The capture process does not require scanning the user’s Alipay payment code again.

When using this interface, the value of the out_order_no field must be unique in all cases. The value of out_order_no is occupied even if a pre-auth is failed or cancelled. Therefore, when you request a capture again, you must use a new value for the out_order_no field to call the interface. Otherwise, errors will occur.

The payment amount in the transaction currency cannot exceed the authorized amount in the transaction currency. The merchant can specify whether the remaining funds need to be unfrozen in the payment request. If the payment amount at the capture process doesn't match the amount that was frozen during the pre-auth process due to the exchange rate fluctuation, the customer has to bear the loss or benefit incurred.

Related APIs for capturing the authorized payment:

• alipay.trade.refund: The merchant can refund the payment via this interface. Both full and partial refunds are supported. The interface responses according to the value of out_request_no in the idempotent method. Therefore, out_request_no must be unique for each partial refund.
• alipay.trade.query: Query the capture transaction status.