The Acquiring Service Provider (ACQP) collects the information of purchase order and user payment code submitted by Merchant, and then constructs the payment request to Alipay+. After Alipay+ returns the payment result, the ACQP notifies Merchant about the result.
To integrate the User-presented Mode Payment, the ACQP needs to complete the following steps.
In certain countries or regions, for legal or compliance reasons, the merchant information that is related to this payment must be registered before a payment can be processed. The merchant registration process only needs to be performed once.
The following figure illustrates the merchant registration flow:
Figure 2. Merchant registration flow
When processing merchant registration requests, Mobile Payment Provider must pay attention to the following items:
- Batch operations are not supported. Each time, only one merchant or store can be registered.
- For the cashier payment scenario, at least the merchant information must be registered.
- The response of the merchant registration request only indicates that the registration request is successfully accepted.
- Mobile Payment Provider returns the registration status to Alipay+ asynchronously (normally within 7 days), the ACQP can obtain the registration result by using inquiryRegistrationStatus interface.
- Alipay+ will notify the ACQP of the merchant registration status via notifyRegistrationStatus interface if the ACQP integrates this interface.
Alipay+ sends merchant registration request to Mobile Payment Provider.
Mobile Payment Provider returns result to Alipay+.
For more information about how to use the APIs (such as the field description), see registration.
Identify Alipay+ payment code
The ACQP needs to identify whether the payment code submitted by merchant is an Alipay+ payment code.
In addition, the ACQP needs to ensure that the Alipay+ payment code can be recognized by the merchant scanners by following the code rules below:
- The payment codes are in the length of 16 ~ 24 digits and start with 25, 26, 27, 28, 29, or 30.
- Preserve the ability of code length expansion. It's recommended that your terminal can support the length of 32 digits for further use.
Create a payment
To initiate a payment, the ACQP needs to call the pay interface.
When calling the pay interface, pay attention to the following items:
- Specify paymentMethod.paymentMethodId by using the value of the payment code that is collected by the merchant from the customer's e-wallet.
- Specify paymentMethod.paymentMethodType as
CONNECT_WALLETin the pay interface.
- Represent transaction amount in the smallest unit of a currency. For example, when currency code is HKD, $5.99 is represented as 599. When currency code is JPY, ￥599 is represented as 599. See ISO 4217 Currency Code for details.
- Assign a unique paymentRequestId for the payment request to avoid any failures casued by duplicate number.
- In certain cases, if the payment is not completed but needs to be closed from the merchant side, use the cancelPayment API to close it.
- The default timeout in the Alipay+ system is 1 minute, which means the transaction will be closed in the Alipay+ sysytem if payment is not completed.
- You might receive different results from Alipay+, follow instructions below to handle the result:
Update the status from merchant side.
Take actions according to the error message in result.resultCode.
Payment in processing
Call the inquiryPayment interface to inquire the payment result. The inquiry request can be sent 10 to 20 times within 60 seconds.
No result received
Retry the same request until getting the response. Please make sure that the paymentRequestId parameter must be the same as the previous one.
The ACQP sends a request to Alipay+.
Alipay+ returns a response to the ACQP.
- Response of a successful payment:
- For a failed payment, result.resultStatus is
F, and a sample response is as below:
- For an unknown payment status, result.resultStatus is
U, and a sample response is as below:
For more information about how to use the interface (such as the field description), see pay.
Handle payment result notifications
Alipay+ calls the notifyPayment interface to notify the ACQP about the payment result when a payment reaches a final state of success or failure. After that, the ACQP needs to notify merchant the result accordingly.
For a successful payment transaction, an HTTP POST is fired once the transaction is successfully completed. The HTTP request is sent in the raw JSON, of which the Content-Type request header is specified as
application/json. Ensure that you can access the HTTP body accordingly.
For more information about what the request header, the successful payment notification request body and the failed payment notification body look like, see the samples below.
Verify the signature
The notification request that Alipay+ sends to the ACQP is signed. The merchant needs to verify the signature to confirm whether the notification is sent from Alipay+. For how to validate a signature, see Validate a signature.
After the notification is delieverd successfully, verify whether the values of the paymentAmount and paymentRequestId parameters are as you expect (for exmaple, the amount that you have calculated for the order that you are going to ship).
Acknowledge the notification with the required response
After receiving the notification, no matter whether the order processing succeeds or fails, you must return a receipt acknowledgment message to Alipay+. Meanwhile, the required response must also be signed.
For more information about what the header and body of the response look like, see the samples below.
Note：The notifyPayment interface cannot accept the failure that is caused by business reasons, for example, risk control validation failure. If the payment fails due to some business reasons, ACQP must firstly accept the payment notification and return
SUCCESS to Alipay+, and then call the cancelPayment interface to perform refund.
After receiving the notification, you must respond with an HTTP status code of
200 and send an acknowledgement with result.resultStatus of
S to indicate that your server received and processed the call. If you respond with other status code, or acknowledge with other values, Alipay+ takes the notification delivery as unsuccessful. Therefore, Alipay+ will retry the notification sending.
- The interval between two adjacent times is: 2m, 10m, 10m, 1h, 2h, 6h, 15h
- 7 times - up to 24 hours 22 minutes
Alipay+ sends a request to the ACQP.
- Request header:
- Successful payment notification body:
- Failed payment notification request body:
The ACQP returns a response to Alipay+.
- Response header:
- Response body
For more information about how to use the interface (such as the field description), see notifyPayment.