Quick start
This topic mainly helps the Acquiring Partners (ACQPs) learn how to quickly build a smooth Cashier Payment process with the Alipay+ Unified Payment solution.
To start your development and integration with Alipay+, you need to first prepare the environment and resources by taking the following actions:
- Refer the Environment section to set the domain name of the request URL base as you require.
- Get the Client ID and set the public key by using the Alipay+ Developer Center.
- For the sandbox environment, refer to Develop in the sandbox.
- For the production environment, refer to Launch into production.
- Implement the requirement of message signing and signature validation in one of the following methods:
- Develop your own code based on the logic described in Sign a request and validate the signature.
- Use the Signing tutorial that Alipay+ provides in the iTest module of Alipay+ Developer Center.
- Ensure that you provide the merchant registration information to Alipay+ before you start production acceptance testing.
If you need to provide the payment method page for your merchant, take the following actions:
Consult the payment method information from the Alipay+ CDN server via a URL.
The payment information is returned in the JSON data, which indicates whether there is an Alipay+ payment method available and includes the logo and promotion information about the payment method.
a. Construct the CDN URL based on the format requirement and make a request.
b. Parse the JSON data based on Response parameters.
Note: Alipay+ also provides other methods for you to consult the payment method information. For more choices, see the table in Consult the information about the Alipay+ payment method.
Render the payment method page
With the information that is returned in Step 1.1, follow the Alipay+ Brand Display Guidelines for Cashier Payment to render the payment method page.
On the payment method page, the user selects the Alipay+ unified payment method and then goes to the Alipay+ checkout page to select a specific Alipay+ supported MPP for payment.
To open the Alipay+ checkout page and create an order in Alipay+, you need to call the pay API.
Call the pay API and handle the response.
a. Make a POST request to the endpoint /aps/api/v1/payments/pay. When specifying the request parameters, especially pay attention to the following two parameters:
- paymentNotifyUrl: specify the URL so that you can use it to receive a notification from Alipay+ in Step 3
- paymentRedirectUrl: specify the URL so that the MPP can redirect the user back to your merchant client side in Step 4.
b. Receive the response from Alipay+, and get the value of the normalUrl parameter, which then is used to redirect the user to the Alipay+ checkout page.
For more information about how to specify the pay API request parameters and handle the response, see pay.
Open the Alipay+ checkout page
With the payment URL that is specified in the normalUrl parameter, you can redirect the user to the Alipay+ checkout page. Depending on the terminal type and the operating system of your merchant client side, the way of opening the payment URL is different.
Note: For the merchant client side as an app, Alipay+ also provides an SDK for you to smoothly open the Alipay+ checkout page. For more information, see How to open Alipay+ checkout page with SDK.
On the Alipay+ checkout page, the user selects one of the Alipay+ supported MPPs and then goes to the MPP side to complete the payment.
After the user completes the payment, you need to obtain the payment result. Normally, it is recommended that you attempt to obtain the payment result once you send the pay request successfully. To ensure that you can obtain the result, take the following two actions:
- Monitor the notification from Alipay+
When a payment reaches a final state of success or failure, Alipay+ calls the notifyPayment API to notify you of the payment result.
You need to monitor the notification at the URL address that you specify in the paymentNotifyUrl parameter of the pay API. After receiving the notification, you need to verify the request and acknowledge it with a response. For more information, see Handle the payment notification.
- Keep inquiring about the payment result from Alipay+
In case you cannot receive the notification due to some network or system problems, you also need to keep inquiring about the payment result from Alipay+ by calling the inquiryPayment API.
a. Make a POST request to the endpoint /aps/api/v1/payments/inquiryPayment. You can specify the paymentRequestId or paymentId parameter for payment inquiry results.
b. Receive the response from Alipay+.
For more information about how to specify the inquiryPayment API request parameters and handle the response, see inquiryPayment.
Tip: You can refer to the Obtain Payment results topic to learn more about the processing logic between the pay, notifyPayment, and inquiryPayment APIs.
After the user proceeds with the payment order to a status of success, failure, or unknown (for example, give up the payment order), the MPP can redirect the user to the URL address that you specify in the paymentRedirectUrl parameter of the pay API. Normally this URL address represents the merchant result page.
You need to handle the redirection from the MPP side and display the merchant payment result page with the latest payment result that is obtained in Step 3. When rendering the payment result page, conform to the Alipay+ Brand Display Guidelines for Cashier Payment.
To facilitate your development with Alipay+ APIs, Alipay+ provides the server sample code for your reference. You can go to the Alipay+ Developer Center to download it. For how to use it, see the README doc in the downloaded wizard.
Learn how to cancel a payment when you cannot obtain the final payment status (success or failure) via the notifyPayment or inquiryPayment APIs within the payment expiry time, or when you want to close the order before the payment expires for time-sensitive scenarios.
Learn how to refund a payment for a transaction that has been successfully paid.
Learn how to use the set of financial reports provided by Alipay+ to reconcile your transactions and settlements.