To integrate with Alipay, you can use Alipay-provided open SDKs or call APIs on your own.
#Use open SDKs
Alipay Global Open SDK encapsulates the process of performing the integration, including the adding and validating of signatures for calling Alipay APIs. For more details, see Alipay SDK for Java, Alipay SDK for PHP, Alipay SDK for Python, and Alipay SDK for .Net.
After integrating with the Alipay User-presented Payment Product, payments can be accepted by scanning the customer's payment code. The following graphic shows the interaction flow of accepting the payment from a customer:
Figure 1. Payment process of User-presented Mode Payment
The payment process consists of the following steps:
- The user presents the payment code to the merchant.
- The merchant scans the payment code of the user.
- The merchant initiates a payment request to Alipay.
3.1 Alipay returns the payment result.
3.2 Alipay returns the asynchronous notification to the merchant.
3.3 The merchant sends Alipay an acknowledgement message to confirm that the payment notification is received.
#Initiate a payment request
Before you start integrating with Alipay's User-Presented Mode Payment product, go through the Development section to learn how to invoke interfaces in both the sandbox and production environments. Then proceed to complete the following steps:
#Step 1: Construct the request
The request that you need to construct is composed of four parts:
- Request URL format: https://open-sea.alipay.com/ams/api/v1/payments/pay
- Method: POST
- HTTP header: mainly contains fields such as Client-Id, Signature, Encrypt, Content-Type, Request-Time, and Agent-Token.
- HTTP body: contains the detailed business request information in the JSON format and the business request information needs to be signed. For more information, see the pay interface.
The following example shows an HTTP body of a request for a User-presented Mode Payment. In this case, an Alipay CN user checks out for a total amount of 500 CNY.
- Specify inStorePaymentScenario with PaymentCode in the payment interface for a User-presented Mode Payment.
- All transaction amount needs to be represented in the smallest unit of a currency. For example, when the currency code is USD, $5.99 is represented as 599. When the currency code is JPY, ￥599 is represented as 599. See ISO 4217 Currency Codes for details.
#Step 2: Submit the payment request to Alipay
Submit the request you constructed as suggested in Step 1 to Alipay with the following gateway addresses:
- open-na.alipay.com: for merchants in North America.
- open-sea.alipay.com: for merchants in Asia.
- open-eu.alipay.com: for merchants in Europe.
Stay open to the possibility that gateway addresses might change.
#Step 3: Handle the payment result
The payment result can be synchronous notification, asynchronous notification, or both.
To handle the payment result notifications, you must:
- Process the payment result response or notification by verifying the signature of the notification.
- Return a receipt acknowledgment message to Alipay. This step is only required for asynchronous notification.
#Verify the signature of the response or notification
The notification Alipay sends to the merchant is signed. The merchant needs to verify the signature to confirm whether the notification is sent from Alipay.
The following example shows typical notification headers and bodies.
Notification body (for a successful payment that succeeds)：
Notification body (for a failed payment):
Based on the above notification header and body, the content to be verified is as follows:
You can use notifications to automate business processes. To process notifications, you must:
- Configure the server address to receive notifications.
Configure the server address to receive notifications from Alipay on the Alipay Developer Platform or in the payment interface.
- Accept notifications and acknowledge the notification with a required response.
To ensure that your server is properly accepting notifications, Alipay requires you to acknowledge every notification with a success response.
- Apply your business logic.
If you use HTTPS to receive notifications, server certificates must be configured according to the authentication requirements.
Acknowledge the notification with required response
After the customer payment succeeds, Alipay sends a payment result notification to the merchant. The address that is used to receive the notification is specified when sending the payment request. After receiving the notification, the merchant must return a receipt acknowledgment message to Alipay Connect.
If you do not reply to this notification, Alipay considers that the notification is not received and continues to send the notification. The response (an acknowledgment receipt message) sent to Alipay does not need to be signed.
Only after receiving the Alipay payment success results notification, the payment can be considered successful and the merchant can proceed with the purchase process, for example, deliver goods. Do not rely on the payment results page to determine whether the payment succeeds because the customer might close the result page before the result arrives or an attacker-tampered information might be presented on the result page.
The following samples illustrate the response header and body that Merchant sends to Alipay:
The customer pays successfully, but the merchant does not receive the payment result notification.
In this case, the customer completes the payment and money is deducted. However, the merchant does not receive the payment result notification. Therefore, the transaction failed.
- After the payment of the customer reaches the final payment status (payment success or payment failure), Alipay does not notify the merchant in time.
- Alipay notified the merchant, but the merchant did not get the payment result due to network reasons.
The merchant is suggested to call the inquiryPayment interface to query the payment status before the transaction closing time. If a successful payment status is obtained, proceed with the transaction. If no clear payment status is returned, continue to retry the query request. If a failed payment status is obtained, or the transaction times out, call cancel interface to cancel the transaction.
The transaction closing time is determined by one of the following ways:
- If the payment is not completed in time after the checkout page is presented, the transaction is to be closed by default.
- The merchant can set the closing time by using the paymentExpireTime parameter in the pay interface, and the merchant can also call the cancel interface to close the unpaid transaction or cancel the paid transaction.
- If the merchant does not specify the paymentExpireTime parameter, the transaction closing time defaults to the contract agreement.