Quick start
This topic mainly helps the Acquiring Service Providers (ACQPs) learn how to quickly build a smooth Cashier Payment process with the Alipay+ Unified Payment solution.
Before you begin
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.
Procedure
（Optional）Step 1. Consult and render the payment method information
If you need to provide the payment method page for your merchant, take the following actions:
1. Consult the payment method information
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 (if any) about the payment method.
a. Construct the CDN URL based on the format requirement and make a request.
Sample CDN URL
b. Parse the JSON data based on Response parameters.
Sample JSON response
{
"enabled": true,
"logos":[
{
"logoName": "Alipay+",
"logoUrl": "https://resource.alipayplus.com/prod/A1112TEST0000000/82c67417922f7c946504b2d9faff39c260539213e5a4effbb561396fccde3498/CASHIER_PAYMENT/PHP/defaultregion/P2-WEB-TypeD/alipayplus.png",
"logoPattern": "P2-WEB-TypeD",
"logoWidth": "912",
"logoHeight": "120"
}
],
"brandName": "Alipay+"
}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.
2. 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.
Sample payment method page
Mobile | Web |
|
|
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.
Step 2. Initiate a payment
To open the Alipay+ checkout page and create an order in Alipay+, you need to call the pay API.
1. 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.
Sample pay request
curl -X POST \
https://open-sea.alipayplus.com/aps/api/v1/payments/pay \
-H 'Content-Type: application/json' \
-H 'Client-Id: TEST_5X00000000000000' \
-H 'Request-Time: 2022-12-01T12:12:12+08:00' \
-H 'Signature: algorithm=RSA256, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx' \
-d '{
"userRegion": "US",
"paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
"paymentRedirectUrl": "https://xmock.inc.alipay.net/paymentResult.htm",
"paymentRequestId": "pay_sample_112233445566",
"paymentFactor": {
"isInStorePayment": "false",
"isCashierPayment": "true",
"presentmentMode": "UNIFIED"
},
"order": {
"referenceOrderId": "102775745070000",
"orderDescription": "SHOES",
"orderAmount": {
"currency": "USD",
"value": "4900"
},
"merchant": {
"referenceMerchantId": "M0000000001",
"merchantName": "UGG",
"merchantMCC": "5411",
"merchantAddress": {
"region": "US",
"city": "New York"
}
},
"env": {
"terminalType": "APP",
"osType": "IOS"
},
"buyer": {
"referenceBuyerId": "907410100070010000"
}
},
"settlementStrategy": {
"settlementCurrency": "JPY"
},
"paymentAmount": {
"currency": "USD",
"value": "4900"
},
"paymentMethod": {
"paymentMethodType": "CONNECT_WALLET"
}
}'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.
Sample pay response body
{
"acquirerId": "2022TEST00000000",
"result": {
"resultCode": "PAYMENT_IN_PROCESS",
"resultStatus": "U",
"resultMessage": "The payment in process."
},
"paymentId": "20221201121200",
"paymentAmount": {
"value": "4900",
"currency": "USD"
},
"normalUrl": "http://iopengw-sea.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?codeValue=https%3A%2F%2Fqr.alipayplus.com%2F281666040092tUox5AICEzTlESzUJe26IPnn"
}For more information about how to specify the pay API request parameters and handle the response, see pay.
2. 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.
Sample Alipay+ checkout page
Mobile | Web |
|
|
Sample codes for different client sides
For Android apps
try {
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(normalUrl));
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
startActivity(intent);
} catch (Exception e) {
e.printStackTrace();
}For iOS apps
if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
[[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];
}else{
[[UIApplication sharedApplication] openURL:url];
}For Web or WAP
window.location.href = normalUrl;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.
Step 3: Obtain the payment result
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.
Sample request that Alipay+ sends to you
Request header
"Content-Type": "application/json",
"Request-Time": "2022-12-01T12:13:12+08:00",
"client-id": "TEST_5X00000000000000",
"Signature": "algorithm=RSA256,keyVersion=1,signature=jTOHqknjk%2fnDjEn8lfg%2beNODdoh2eHGJV%2blvrKaDwP782WxJ7ro49giqUu23MUM8sFVVNvhg32qHS3sd4O6uf5kAVLqztqNOPJFZcjw141EVi1vrs%2bIB4vU0%2fK%2f8z2GyWUByh2lHOWFsp%2b5QKCclXp%2bjacYqWYUur5IVbuebR1LoD5IiJ7u7J9qYriFxodkxmIAJYJyJs7mks2FWHh2YePLj3K%2f4B65"Request body that indicates a successful payment
{
"acquirerId": "2022TEST00000000",
"pspId":"1022172000000000001",
"paymentResult": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
},
"paymentRequestId":"pay_sample_112233445566",
"paymentId":"20221201121200",
"paymentTime": "2022-12-01T12:12:12+08:00",
"paymentAmount":{
"value":"4900",
"currency":"USD"
},
"customerId":"12345678",
"walletBrandName":"KAKAOPAY",
"settlementAmount": {
"value": "4900",
"currency": "USD"
},
"settlementQuote": {
"quoteCurrencyPair": "USD/JPY",
"quoteExpiryTime": "2022-12-02T12:00:00+08:00",
"quoteId": "046793306919858814",
"quotePrice": "1.35",
"quoteStartTime": "2022-12-01T12:00:00+08:00"
}
}Sample response that you need to return to Alipay+
Response header
"Content-Type": "application/json",
"response-time": "2022-12-01T12:13:42+08:00",
"client-id": "TEST_5X00000000000000",
"Signature": "algorithm=RSA256,keyVersion=1,signature=jTOHqknjk%2fnDjEn8lfg%2beNODdoh2eHGJV%2blvrKaDwP782WxJ7ro49giqUu23MUM8sFVVNvhg32qHS3sd4O6uf5kAVLqztqNOPJFZcjw141EVi1vrs%2bIB4vU0%2fK%2f8z2GyWUByh2lHOWFsp%2b5QKCclXp%2bjacYqWYUur5IVbuebR1LoD5IiJ7u7J9qYriFxodkxmIAJYJyJs7mks2FWHh2YePLj3K%2f4B65"Response body
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"Success"
}
}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.
Sample inquiryPayment API request
Inquiry with paymentRequestId
{
"paymentRequestId": "pay_sample_112233445566"
}or inquiry with paymentId
{
"paymentId": "20221201121200"
}Sample inquiryPayment API response body
{
"acquirerId": "2022TEST00000000",
"pspId": "1022172000000000000",
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentResult": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentRequestId": "pay_sample_112233445566",
"paymentId": "20221201121200",
"paymentTime": "2022-12-01T12:12:12+08:00",
"paymentAmount": {
"value": "4900",
"currency": "USD"
},
"customerId": "12345678",
"walletBrandName": "KAKAOPAY",
"settlementAmount": {
"value": "4900",
"currency": "USD"
},
"settlementQuote": {
"quoteCurrencyPair": "USD/JPY",
"quoteExpiryTime": "2022-12-02T12:00:00+08:00",
"quoteId": "046793306919858814",
"quotePrice": "1.35",
"quoteStartTime": "2022-12-01T12:00:00+08:00"
}
}For more information about how to specify the inquiryPayment API request parameters and handle the response, see inquiryPayment.
Tip: You can refer to the topic Obtain Payment results to learn more about the processing logic between the pay, notifyPayment, and inquiryPayment API.
Step 4: Handle the redirection from the MPP side
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.
Brand display for payment result
|
|
Alipay+ as image | Alipay+ as text |
More resources
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.
Next steps
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.