Integration and acceptance

In this section, you can find the answers to frequently asked questions about Alipay+ integration and acceptance.

Cashier Payment

Who provides the paymentUrl?

The MPP provides the payment URL for the user to pay, which is specified by the paymentUrl parameter in the pay API response. Alipay+ does not verify the value of paymentUrl.

When is the userInitiatedPay API used?

The userInitiatedPay API is used for Cashier Payment when the user completes the payment in the MPP WAP. The MPP server calls this API to send the decoding request to Alipay+. In other payment scenarios, the MPP app calls the Alipay+ Client SDK to decode the code value.

Auto Debit

How frequently does the MPP send OTPs to the user?

Because of the unstable service provided by the mobile message operator or the weak mobile phone signal, the user might not receive the OTP successfully. The MPP can send the OTP multiple times. The time interval is suggested to be 60s on the merchant side and 30s to 60s on the MPP side.

What result code should the MPP return when an API is called by using the access token with insufficient scopes?

The MPP should return the result code INVALID_TOKEN and the result message in detail.

For example, if an Auto Debit payment request is initiated by calling the pay API and the corresponding scopes of the access token do not include AGREEMENT_PAY. In this case, the MPP should return the result code INVALID_TOKEN.

Is the returned information in the inquiryUserInfo API stored by Alipay+?

When and only when the returned parameter is userId will the information be stored by Alipay+ for the user mapping.

What's the usage of the payment evaluation?

The payment evaluation is used in the following scenarios:

• Evaluate the user account to check whether the balance is enough to complete the payment.
• The successful payment evaluation represents the successful payment, but no actual deduction occurs temporarily. After multiple payment evaluations, the merchant initiates one Auto Debit payment. 
  

What is the inquiry result for a payment evaluation?

A payment evaluation is a mocked payment and the payment information isn't stored. If the inquiry request for a payment evaluation is initiated, ORDER_NOT_EXIST is returned.

Should the MPP verify the referenceAgreementId parameter when performing an agreement payment?

No. The value of the referenceAgreementId parameter is the unique ID that is assigned by the authorization client to identify an Auto Debit authorization, which matches an authorization code.

In the Auto Debit scenarios, what's the difference between the authUrl and the redirectUrl?

The authUrl is the URL for the merchant to redirect the user to. Through the authUrl, the user is redirected to the MPP page and completes the Auto Debit authorization. The authUrl can be constructed in one of the following 2 ways:

• The ACQP calls the prepare API to request the authorization URL. In the request, the ACQP specifies the required information such as authClientId, scopes, and so on. The MPP returns the authUrl in the response.

Or,

• The MPP provides the initial authUrl to Alipay+, and Alipay+ constructs the authUrl by appending the required parameters to the authUrl. Alipay+ then sends the complete authUrl to the ACQP and the merchant redirects the user to the authUrl for the agreement payment authorization.

The authRedirectUrl is the URL for the MPP to redirect the user to the page that is provided by the merchant. After the user completes the Auto Debit authorization, the MPP redirects the user to the authRedirectUrl, in which authCode is appended. The merchant uses the obtained authCode to apply for the access token.

Is the integration of the prepare API mandatory?

The prepare API is conditional, for now. If the authUrl is dynamic, this API is required. If the authUrl is static, this API is not required.

How to associate the use of the prepare, applyToken, and pay APIs for Auto Debit?

For Auto Debit, the use of the 3 APIs are associated by the access token. After calling the prepare API, the MPP generates and returns the authCode parameter. The ACQP uses the value of the authCode parameter to apply for the access token by calling the applyToken API. Before the access token expires, the merchant uses the same access token to perform Auto Debit payments by calling the pay API. 

How does the MPP verify the corresponding authClientId of an access token?

When the ACQP calls the applyToken API, the authClientId parameter must be specified in the request. The MPP can associate the access token with the corresponding authClientId parameter.

How does the MPP register the merchant information before an Auto Debit payment?

The MPP can integrate the registration API. Alipay+ calls this API to provide the information about the merchant in the request, such as authClientId, authClientName, scopes, and authRedirectUrl. The MPP adds the merchant information to the internal system for future authorization.

Merchant-presented Mode Payment

Can Alipay+ process the store code issued by the MPP?

No. For the store code issued by the MPP, the MPP processes the code value based on the MPP's own local logic.

What information should MPP add to the original user agent string?

The MPP must add AlipayConnect and the MPP wallet name to the original user agent string. It's also recommended that the MPP adds the language information in the request header, as the ACQP might use the information for multi-language display. The format is Language/${value} and the value is specified by the two-character ISO 639-1 language code. For example, Language/zh-Hans.

Will Alipay+ verify the format of the codes issued by the ACQP?

Yes, Alipay+ will verify whether the codes follow the Alipay+ Code Scanning Payment Standards.

How to distinguish the codes issued by different ACQPs?

When the code value is a URL, the code is distinguished by the domain name contained in the URL. When the code value is a string, the code is distinguished by the ACQP identifier contained in the value.

Should the MPP identify whether the code is a local code at first after receiving the code value?

Yes, MPP must identify whether the code is a local code at first before calling Alipay+ Server SDK for the code identification. 

Why should the MPP integrate the Alipay+ Server SDK?

The Alipay+ Server SDK helps MPP process different logic based on the returned code identification results. Alipay+ Server SDK periodically pulls configurations from the Alipay+ server. When the MPP app calls the Alipay+ Server SDK to identify a code, the Alipay+ Server SDK returns the isSupported parameter after the code identification. Based on the value of the isSupported parameter, the MPP decides to take the corresponding action, such as rejecting the transaction, calling Alipay+ Client SDK to decode, or redirecting to the merchant page.

Why should the MPP redirect the user to the merchant payment result page after the user completes the payment?

The reason is that oversea merchants confirm the payment result based on the merchant payment result page.

User-presented Mode Payment

What's the validity period of a payment code?

The validity period of the payment code is 60 seconds by default.

What are the solutions to the weak Internet signal problem when MPP displays the payment code?

The caching mechanism is used. Alipay+ Client SDK applies for multiple payment codes from Alipay+ at a time. The time for the payment codes to be effective between each other has an interval. The caching mechanism might cause a network latency of 100ms.

For User-presented Mode Payment, can the user choose the payment method such as a credit card or the balance?

Alipay+ only routes the payment request to a specific MPP. The MPP can display the detailed payment methods, such as credit card and user balance, to be chosen by the user.

How to prevent the payment code from being taken a screenshot?

For iOS, if the screenshot is taken on the payment code page, the Alipay+ Client SDK displays a modal window and MPP can customize the text. For Android, taking screenshots must be forbidden when the MPP presents the payment code.

When a screenshot is attempted, The MPP app notifies the event to the Alipay+ Client SDK and the current payment code is invalid. To obtain a new payment code, the user must refresh the page and the MPP app must call the getPaymentCode API again.

How to specify the terminal ID for User-presented Mode Payment?

The terminal ID is specified by the order.env.deviceTokenId parameter.

Who provides the payment code page for User-presented Mode Payment?

The MPP. However, the payment code is provided by Alipay+. The MPP applies the payment code from Alipay+ and displays the payment code page to the user.

Should the MPP display the reference rate on the payment code page?

For User-presented Mode Payment, the MPP displays the actual exchange rate on the payment result page. It's not suggested that MPP displays the reference rate on the payment code page. The reference rate might be different from the actual exchange rate, which might cause user complaints. 

Reconcile

Why are the paymentId parameter and the refundId parameter not included in the reconciliation reports?

For MPPs that join Alipay+, transactions in the reconciliation reports are identified by the transactionRequestId parameter, which is assigned by Alipay+. In the request processing, the MPP might not return the paymentId or refundId in the response. For example, Alipay+ processes a refund request successfully but the MPP fails to process the refund request. In this case, MPP does not return the refundId in the response, but this refund is included in the clearing report and is identified by the transactionRequestId. After obtaining the clearing report, the MPP deals with the refund manually.

When is the Settlement Report uploaded to the SFTP server?

The settlement report is uploaded to the SFTP server on the MPP's Local Business Day.

Can the settlement report contain no transaction records?

Yes. When no amount is to be settled, or the settlement amount is less than the settlement amount threshold as agreed in the contract, a settlement report is generated with an amount of zero and no transaction records are contained. The transaction amount and currency are empty.

What are the rules of the seq field in the file name of the clearing reports and the settlement report?

A report file can contain a maximum of 100,000 records. If the report contains more than 100,000 records, the report is split across multiple files and the size of each file is around 20 MB. In the file name, the seq field is the sequence number with a range of 000-999. The MPP and Alipay+ can determine the time when all records are available in SLA.

Are the records of the dispute resolutions included in the Settlement Report?

No. The Settlement Report only includes payment and refund transactions.

Common

Payment

How to understand the difference between the orderAmount, paymentAmount, and payToAmount parameters in the pay API?

The following list describes the orderAmount, paymentAmount, and payToAmount parameters.

• orderAmount is the original amount and currency when the merchant creates the order. 
• paymentAmount is the amount that's collected from the user and is equal to orderAmount if no promotion tools are used.
• payToAmount is the amount that the user pays eventually.

The MPP debits the user account according to payToAmount.

What is the maximum age of transactions for which the MPP should return the transaction status by using the inquiryPayment API?

For the transactions that occur within one year, MPP must return the transaction status when receiving the inquiryPayment API requests from Alipay+.

How frequently can Alipay+ call the inquiryPayment API for the payment with an unknown result?

For the payment with an unknown result, Alipay+ can call the inquiryPayment API to query the payment result. If Alipay+ does not receive the inquiry result in time, Alipay+ retries the inquiry request.

• For Cashier Payment, Alipay+ retries 10 times totally with intervals of 10s, 10s, 30s, 60s, 60s, 120s, 120s, 120s, 120s, 120s.
• For Auto Debit Payment, Alipay+ retries 6 times totally with intervals of 4s, 4s, 30s, 60s, 60s, 60s.
• For User-presented Mode Payment, Alipay+ retries 6 times totally with intervals of 4s, 4s, 30s, 60s, 60s, 60s.
• For Merchant-presented Mode Payment, Alipay+ retries 8 times totally with intervals of 10s, 10s, 30s, 60s, 60s, 60s, 60s, 60s.
  

What is the result of a canceled payment from the inquiryPayment API?

The result of a canceled payment from the inquiryPayment API is ORDER_IS_CLOSED, regardless of the original payment status. See the following list for details:

• When both the payment and the payment cancelation results are successful, the value of the result.resultCode parameter is SUCCESS and paymentResult.resultCode is ORDER_IS_CLOSED.
• When the payment is failed and the cancelation of the failed payment is successful, result.resultCode is SUCCESS and paymentResult.resultCode is ORDER_IS_CLOSED.
• When the payment status is unknown and the cancelation of the unknown payment is successful, result.resultCode is SUCCESS and paymentResult.resultCode is ORDER_IS_CLOSED.
• When the payment is closed because of timeout and the cancelation of the payment is successful, result.resultCode is SUCCESS and paymentResult.resultCode is ORDER_IS_CLOSED.
  

Should payment.resultCode returned in the inquiryPayment API be consistent with the resultCode returned in the pay API?

Yes, both resultStatus and resultCode returned in the inquiryPayment API and the pay API should be consistent.

Can the resultCode be PROCESS_FAIL as long as the resultStatus is F?

No. Only use PROCESS_FAIL when the payment result is failure and cannot match the appropriate result code. Otherwise, use the appropriate result code that is specified for the failure.

What scenarios require the integration of the inquiryPayment and the notifyPayment APIs?

All. To improve the user experience and system stability, the inquiryPayment API and the notifyPayment API must be integrated in all payment scenarios.

Is the order parameter optional in the pay API request?

The order parameter is mandatory. The order information must be sent to the MPP, which includes the buyer information, merchant information, goods information, and payment amount.

Refund & cancelation

How to understand the difference between the refundAmount and refundAmount parameters in the Refund API?

The following list describes refundAmount and refundFromAmount:

• refundAmount is the amount that's refunded to the user by MPP.
• refundFromAmount is the refund amount that the user receives eventually.

The MPP refunds the amount to the user according to refundFromAmount.

When the user status is abnormal or the user does not exist for a refund, should the MPP return refund success? 

Yes, even when the user status is abnormal or does not exist, the MPP returns refund success so Alipay+ can update the refund status to success accordingly. The refund is included in the clearing and settlement reports and the MPP can then deal with the refund manually.

Must the MPP support multiple refunds and partial refunds?

Yes, MPPs must support multiple refunds and partial refunds. If multiple refunds for one payment are initiated, MPP must return the unique refund ID and the actual refund time for each refund.

How is the refund performed asynchronously?

When the ACQP initiates the refund request, Alipay+ returns the refund success synchronously to the ACQP. After that, Alipay+ sends the refund request to the MPP asynchronously. If MPP returns refund success, Alipay+ updates the refund status to refund success. If MPP returns refund failure, Alipay+ retries the refund request until the refund succeeds. The fund flow of the refund is ACQP -> Alipay+ -> MPP.

When the transaction that is not refunded successfully is settled in the settlement report, can the refund request be retried?

Yes. For the transaction that is not refunded successfully and is settled in the settlement report, Alipay+ keeps retrying the refund request. If the refund succeeds, the successful refund is included in the clearing reports and settled in the settlement report.

What's the cancellable period and refundable period of a payment?

The merchant can initiate a refund transaction within 1 year (365 days by default) of the original payment transaction date. The payment can be canceled within the agreed cancellable period, which is from the time when the transaction is initiated to 00:30 UTC+8 of T+1 day, regardless of the payment status.

Message transmission

How do Alipay+ and the MPP exchange public keys?

Currently, for the sandbox environment, the MPP can upload the public key and view Alipay public key at Alipay+ Developer Center. For more information, see Alipay+ Developer Center.

For the production environment, however, the MPP contacts Alipay Connect Technical Support team to exchange the public keys.

For generating and verifying the signature, should the MPP install extra certificates in the MPP server?

The communication between the MPP and Alipay+ uses HTTPS, which means that the MPP domain requires the certificate. Alipay+ and MPP exchange digital certificates by email.

When Alipay+ signs the request that is sent to MPP, who does the Client-Id parameter identify?

In the request sent from Alipay+ to the MPP, the Client-Id parameter identifies the MPP. On the Settings page in the Alipay+ Developer Center, you can find the Client ID, which is assigned by Alipay+ after you create the application.

Why does the signature validation fail and how to resolve the problem?

The signature validation can fail because of various reasons. See the following list for details.

Inconsistent character encodings

Verify whether the failure is caused by inconsistent Chinese character encodings. Sign the request with and without Chinese characters respectively and validate the signatures. Find the reasons based on the verification results. 

Line breaks and spaces included in the request message

The request message must use a strict format and not contain line breaks or spaces. Otherwise, the request message might be inconsistent with the data in the content to be signed, which causes the failure of the signature validation. For more information about the content to be signed, see Sign a request and validate the signature.

Unremoved beginning and ending words

This is because when the MPP uploads the public key, the beginning and ending words, which are BEGIN PUBLIC KEY and END PUBLIC KEY, are not removed. Remove line breaks and the beginning and ending words.

Unmatched private key and public key

Use the tools downloaded at the Alipay+ Developer Center to compare the private key and the public key. Ensure that you use the keys of the same key pair.

Inconsistent algorithms and processing logics 

The algorithms and processing logics used in the request signing and signature validation must be consistent. Currently the algorithm used by Alipay+ is RSA256. Check whether the value of signature in the request header is algorithm=RSA256, keyVersion=0.

Inconsistent processing rules of special characters

Use the same base64 algorithm to encode the data.

Unmatched keys and the environment

Check whether the correct public key is used in the corresponding environment. The development environment, production environment, and the system integration testing environment must use the correct public keys.

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.

Other

Is the information about service fees contained in the refund or pay APIs?

The service fees are charged by Alipay+ after the transaction succeeds and the information is not contained in the API messages. To obtain the service fee information, see Reconcile.

Should all APIs follow the Alipay+ request URL format?

Not so when Alipay+ calls the MPP. But, when MPP calls an API to Alipay+, the API follows the format of https://{host}/aps/api/v1/{restfulPath}, in which host is the standard domain name assigned by Alipay and restfulPath is the path to the API. For example, https://open-sea.alipayplus.com/aps/api/v1/payments/notifyPayment.

Are the HTTP header names case-sensitive?

No, the HTTP header names are case-insensitive.

What is tracer-ID in the HTTP response header used for?

The tracer-ID is an internal identifier assigned by Alipay+, which is used for troubleshooting.

How does MPP connect with Alipay+?

It's suggested that MPP connects with Alipay+ through leased lines. However, the public network is also supported.

Can the resultStatus be F when the resultCode is REQUEST_TRAFFIC_EXCEED_LIMIT?

No. The MPP must follow the API document for the value of the resultStatus parameter. When the value of the resultCode parameter is REQUEST_TRAFFIC_EXCEED_LIMIT, the value of the resultStatus parameter must be U.

Does Alipay+ always retry the request when the returned resultStatus is F or U?

No. For the refund and cancelation requests, Alipay+ retries the request if the value of the resultStatus parameter is F or U. However, for the payment request, Alipay+ only retries the request if the value of the resultStatus parameter is U.

Do the date and time format in the requests from Alipay+ follow ISO 8601?

Yes. The MPP must be able to handle the UTC time normally. For example, 2004-05-03T17:30:08+08:00 describes a UTC+8 time and 2004-05-03T17:30:08Z describes a UTC time.

What environment should the MPP use to perform the sandbox testing?

The MPP should use the offline testing environment and can set endpoints on the Sandbox > Settings page in the Alipay+ Developer Center.

Does Alipay+ verify the value of the authCode parameter?

No. The value of the authCode parameter is used for routing the request. Alipay+ only verifies the format of the value of the authCode parameter.

Does Alipay+ generate and verify the value of the accessToken parameter?

No. The value of the accessToken parameter is generated and verified by the MPP according to requirements.

Why must the values of the authCode and the accessToken parameters follow the CGCP standard?

When requesting user authorization or initiating an Auto Debit payment request, the merchant only provides the authCode or accessToken parameter in the request. Alipay+ must route the request to the corresponding MPP based on the value of the authCode or accessToken parameter.

What are the length requirements for the values of the authCode and the accessToken parameters?

The length requirement for the values of the authCode parameter is 32 digits at most and for that of the accessToken/refreshToken parameter, 128 digits at most. The business type identifier for the value of the authCode parameter is 13 and for that of the accessToken/refreshToken parameter, 03.

Must the MPP support idempotency for the requests initiated with the same paymentRequestId parameter?

Yes. For the requests initiated with the same paymentRequestId, the MPP must return the results based on the following rules:

• If Alipay+ initiates pay requests with the same paymentRequestId twice, the MPP must avoid inconsistent results such as the following:

• For the first payment request, MPP returns resultStatus = F. For the second payment request, MPP returns resultStatus = S.
• For the first payment request, MPP returns resultStatus = S. For the second payment request, MPP returns resultStatus = F.

• If Alipay+ initiates inquiryPayment requests with the same paymentRequestId twice, the MPP must avoid inconsistent results such as the following:

• For the first payment inquiry request, MPP returns paymentResult.resultStatus = F. For the second payment inquiry request, MPP returns paymentResult.resultStatus = S.
• For the first payment inquiry request, MPP returns paymentResult.resultStatus = S. For the second payment inquiry request, MPP returns paymentResult.resultStatus = F. Cases where the successful payment is cancelled before the second payment inquiry is excluded.

• For the payment with the same paymentRequestId, the MPP returns the results via the pay API and the inquiryPayment API. The MPP must avoid the following situation:

• In the pay API, resultStatus = F, but in the inquiryPayment API, paymentResult.resultStatus = S.
• In the pay API, resultStatus = S and in the inquiryPayment API, paymentResult.resultStatus = F. Cases where the successful payment is canceled before the second payment inquiry is excluded.

If resultStatus = F is returned by the pay API, or paymentStatus.resultStatus = F is returned by the inquiryPayment API, Alipay+ updates the payment status to failure and the MPP must ensure that the payment cannot be successful anymore. 

How do I know what parameters are required in the API response?

In the API response, the result parameter is always mandatory. For other parameters, see the response section of the API for details.

Why should the MPP integrate the notifyPayment API even if the inquiryPayment API is integrated?

Integrating the notifyPayment API is needed because of the following reasons:

• Too frequent payment inquiries increase the network pressure for the MPP. The merchant might not get the payment result in time, thus resulting in the cancelation of the payment. 
• When the payment inquiry is unavailable because of network issues, using the notifyPayment API is the only method to notify the merchant of the payment result.

What are the validity periods of the access token and the refresh token?

Each access token corresponds to a specific scope. According to the scopes, the validity period of the access token differs. The following table lists the validity period requirements for different scopes:

How to understand the currency code?

The currency code used by Alipay+ follows the ISO 4217 standard. All amounts presented in the API sample codes are expressed in the smallest currency unit. See Currency list for details. In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. Most currencies have 2 decimals. Some currencies do not have decimals, such as JPY, and some have 3 decimals, such as BHD. For example, 10 CNY is submitted as 1000, whereas 10 JPY is submitted as 10.