Integration

This topic provides answers to some frequently asked questions about integration.

• FAQs about Cashier Payment

• What is the difference between the walletName and walletBrandName parameters?
• Why is the user redirected to an error page after successfully paying the transaction?
• Why does the countdown start from 10 minutes when I set the payment expiry time to 30 minutes?

• FAQs about Merchant-presented Mode Payment

• What kind of QR code does Alipay+ issue?
• What are the rules and requirements for issuing an entry code?
• In the order code mode, how to identify the MPP that the user uses to pay?
• In the order code mode, what should be done if the merchant closes the order?

• FAQs about User-presented Mode Payment

• What are the rules and standards for the Alipay+ payment code?
• Why do I receive the UNKNOWN EXCEPTION result code after sending a payment request?

• FAQs about common issues for different payment scenarios

• In which scenarios do I need to redirect the user to make the payment?
• How do I identify and solve an invalid signature issue?
• What are the minimum and maximum values allowed for the payment amount?
• How do I specify the payment scenarios when using the pay API?
• When do I receive the payment result notification from Alipay+?
• How do I handle the payment result notification sent by Alipay+?
• What are the common exceptions that may occur after a payment is initiated? What are the best practices to handle these exceptions?
• Is the API endpoint identical for sandbox and production environments?

Cashier Payment

What is the difference between the walletName and walletBrandName parameters?

The walletBrandName parameter represents the brand name of the MPP displayed to the customer. The walletName parameter is used for internal system interaction.

The walletBrandName parameter is returned by Alipay+ in the pay (User-presented Mode Payment) API and pay (Auto Debit) API when the payment succeeds.

The walletForAccountBinding.walletBrandName and walletForAccountBinding.walletName parameters are returned by Alipay+ in the applyToken API when the access token application succeeds, and are sent by Alipay+ in the request of authNotify API when the access token is created by the Mobile Payment Provider (MPP).

Why is the user redirected to an error page after successfully paying the transaction?

Figure 2. Error page

If you do not include the paymentRedirectUrl parameter in the pay API request, the user may be redirected to an error page. Make sure you have included this parameter to ensure a smooth payment experience.

Why does the countdown start from 10 minutes when I set the payment expiry time to 30 minutes?

Figure 3. Countdown on the Cashier Payment page

In the Cashier Payment scenario, Alipay+ sets a default expiry time of 10 minutes. Therefore, if you specify a payment expiry time longer than 10 minutes, the default expiry time of 10 minutes will take effect.

Merchant-presented Mode Payment

What kind of QR code does Alipay+ issue?

Alipay+ issues dynamic QR codes called order codes. When an order code is scanned, the user is redirected to the MPP payment confirmation page to confirm the payment. Please note that entry codes or private order codes are issued by Acquiring Service Providers (ACQPs), not by Alipay+.

What are the rules and requirements for issuing an entry code?

The entry code issued by the ACQP is a static QR code. After scanning it, users can be redirected to the merchant's WAP page where users can enter an order amount to pay. The following rules apply:

• Ensure that the QR code is an encoded URL pointing to the merchant's WAP page.
• Ensure that the WAP pages can only be accessed by using the HTTPS protocol.
• Ensure that your WAP server must be able to identify Alipay+ supported digital wallets and retrieve other information through user-agent information in HTTPS requests.
• Ensure that you comply with the related Alipay+ Brand Guidelines.

In the order code mode, how to identify the MPP that the user uses to pay?

Unless specifically required, there is no need to know the specific MPP. Merchants do not need to make any adjustments for new MPPs.

In the order code mode, what should be done if the merchant closes the order?

If the merchant closes the order, stop displaying the generated order code. If you have already initiated the payment with Alipay+, cancel the payment by calling the cancelPayment API.

User-presented Mode Payment

What are the rules and standards for the Alipay+ payment code?

Ensure that the Alipay+ payment code adheres to the following rules:

• Payment codes are 16 - 24 digits long 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 a length of 32 digits for further use.

Why do I receive the UNKNOWN EXCEPTION result code after sending a payment request?

Receiving the UNKNOWN EXCEPTION result code usually indicates that you have not followed the necessary steps:

• Ensure that the paymentMethod.paymentMethodId parameter corresponds to the MPP barcode; otherwise, it is invalid.
• The paymentMethod.paymentMethodType parameter must be set to CONNECT_WALLET.

Common

In which scenario do I need to redirect the user to make the payment?

In the Merchant-presented Mode Payment Entry Code scenario, you need to redirect the user to the payment URL returned by Alipay+ in the response of the pay API.

There are no such payment redirections in User-presented Mode Payment, Merchant-presented Mode Payment Order Code, or Merchant-presented Mode Payment Private Order Code scenarios.

How do I identify and solve an invalid signature issue?

To troubleshoot the invalid signature issue, you need to check and verify the following things:

• Signature: Confirm that you have signed the request or response properly. All requests and responses from the ACQP to Alipay+ need to be signed.
• Key and environment: Ensure that you are using the correct private key for signing and have uploaded the corresponding public key in Alipay+ Developer Center in the correct environment. When uploading the public key to Alipay+, omit "BEGIN PUBLIC KEY" and "END PUBLIC KEY".
• Content construction: Verify that the content to be signed is constructed correctly, paying special attention to the format of the Request-Time field, which should adhere to ISO 8601 standards, for example, 2019-05-28T12:12:12+08:00 or 2021-04-21T01:47:04Z.
• Signature algorithms and processing logic: The algorithms and processing logic used in the request signing and signature validation must be consistent.
• Encoding: Confirm that the signature has undergone URL encoding. This process converts special characters in the signature string to a format suitable for URL transmission and prevents any potential misinterpretation of these characters as URL control codes. This allows the complete signature to be integrated into a URL or HTTP request without introducing errors.

What are the minimum and maximum values allowed for the payment amount?

The minimum payment amount allowed by Alipay+ is the smallest unit of the local currency, such as 1 cent. As for the maximum payment amount, Alipay+ does not impose a limit. However, MPPs may have their own maximum limits based on local laws and regulations.

How do I specify the payment scenarios when using the pay API?

To specify different payment scenarios, use the paymentFactor parameter in the pay API request. Refer to the following combinations:

• User-presented Mode Payment: set the isInStorePayment parameter to true, and the inStorePaymentScenario parameter to PaymentCode.
• Merchant-presented Mode Payment Order Code: set the isInStorePayment parameter to true, and the inStorePaymentScenario parameter to OrderCode.
• Merchant-presented Mode Payment Entry Code: set the isInStorePayment parameter to true, and the inStorePaymentScenario parameter to EntryCode.
• Cashier Payment: set the isInStorePayment parameter to false, the isCashierPayment parameter to true, and specify the presentmentMode parameter.
• Auto Debit: set the isInStorePayment parameter to false, the isAgreementPayment parameter to true, and specify the presentmentMode parameter.

When do I receive the payment result notification from Alipay+?

You receive the payment result notification from Alipay+ when the payment reaches a final status, indicating either a successful transaction or a failure.

How do I handle the payment result notification sent by Alipay+?

After receiving a payment result notification from Alipay+, you must send a response to Alipay+ to acknowledge the notification, regardless of the payment status. When constructing the response, you need to specify the result.resultStatus parameter as S and the result.resultCode parameter as SUCCESSto indicate that you have received the notification request successfully. If Alipay+ does not receive the proper acknowledgment, it will resend the asynchronous notification within 24 hours and 22 minutes after the first notification is sent. The notification will be resent up to seven times at intervals of 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, and 15 hours.

What are the common exceptions that may occur after a payment is initiated? What are the best practices to handle these exceptions?

The most common exception is timeout. When a payment is processed, Alipay+ sends an asynchronous notification to you for the result. If you do not receive a notification, call the inquiryPayment API to inquire about the payment result. You can retry the inquiryPayment call if you do not receive any response or if the status returned is PAYMENT_IN_PROCESS.

If the user or merchant cancels the transaction, you can call the cancelPayment API within the cancellable period to cancel the transaction. If you exceed the cancellation deadline, the transaction will be posted to the MPP and you can call the refund API to refund the transaction.

Is the API endpoint identical for sandbox and production environments?

Yes, the API endpoint is the same for both environments. However, users must use a different client ID for each environment. Client IDs for both sandbox and production environments are available in Alipay+ Developer Center. Use the appropriate client ID to ensure proper access and functionality within the respective environment.