Integration

Cashier Payment

What is the difference between the parameters walletName and walletBrandName?

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

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

The parameters walletForAccountBinding.walletBrandName and walletForAccountBinding.walletName 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 does the following system error occur on the Cashier Payment web page that displays the Alipay+ QR code？

Figure 1. system error

This error occasionally occurs only in the sandbox environment. You can clear your browser cache and try again.

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

Figure 2. error page

This is usually because you didn't pass the parameter paymentRedirectUrl in the pay API request. Check and ensure that you have passed this parameter in the pay API request.

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

FAQ integration.png

Figure 3. countdown on the Cashier Payment page

For the Cashier Payment scenario, the default expiry time specified by Alipay+ is 10 minutes. The expiry time that you specified must be shorter than 10 minutes; otherwise, the default expiry time of 10 minutes takes effect.

Merchant-presented Mode Payment

What kinds of QR code does Alipay+ issue?

Alipay+ issues Order Code, which is a dynamic QR code. When an Order Code is scanned, the user is directly redirected to the MPP payment confirmation page to confirm the payment.

Currently, Alipay+ does not issue Entry Code and Private Order Code, which are instead issued by Acquiring Service Providers (ACQPs).

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

The Entry code issued by the ACQP is a static QR code which actually is an encoded URL pointing to the merchant's WAP page. Users can enter an order amount on this WAP page 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 is 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 otherwise required (such as regulation), you do not need to know the specific MPP. For merchants, they 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 order code that you generate. 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?

You need 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.

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

You usually receive the result code UNKNOWN EXCEPTION if you do not do the following things:

The parameter paymentMethod.paymentMethodId needs to take the value corresponding to the MPP barcode; otherwise it is invalid.
The parameter paymentMethod.paymentMethodType needs to take the value of CONNECT_WALLET.

Common

In which scenarios 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 to pay. This URL (the parameter paymentUrl) is 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, 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, for example, 1 cent.

As for the maximum payment amount, Alipay+ does not impose a limit. However, the MPPs may set their own maximum limits in accordance with local laws and regulations.

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

The parameter paymentFactor is used to specify the payment scenario in the request of the pay API.

You can refer to the following combinations to specify different payment scenarios:

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

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 need to send a response to Alipay+ to acknowledge the notification, regardless of the payment status. When constructing the response, you need to specify the parameter result.resultStatus as S and the parameter result.resultCode 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.

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.