To improve your integration quality, refer to the following best practices.
Grant and refresh the access token
Each access token corresponds to a specific scope. For different scopes, the validity periods are different. The following table lists the validity period requirements for different scopes:
The validity period is at least one year for
It's suggested that the validity of
- When multiple scopes are specified, the validity periods of
refreshTokenare defined based on the scope which requires longer or the longest validity period. For example, the values of
scopesare AGREEMENT_PAY and BASE_USER_INFO, then the validity periods of
refreshTokenfollow the requirements for the AGREEMENT_PAY scope.
- When the merchant uses the access token to access the user resources, regardless of the scope type, the user ID must be returned by Mobile Payment Partner.
The merchant will refresh the access token before the expiration time, which is specified by
accessTokenExpiryTime in the response of Authorization Apply Token interface. When the request of refreshing token is processed successfully, Mobile Payment Partner must return a new
refreshToken, and set the original
refreshToken to be invalid. Considering some special cases, such as jitter, it's suggested that Mobile Payment Partner sets a time duration of 5 minutes, during which the merchant can use the same
refreshToken to refresh the access token.
Set timeout length
Timeout might occur when calling the API because of network issues. The party that calls the API sets the timeout length.
Time to wait before timeout when Alipay+ calls an API to Mobile Payment Partner
When Alipay+ calls the API to Mobile Payment Partner, the timeout length is set by Alipay+. Mobile Payment Partner must return response before the timeout. The following table lists the time to wait before timeout for the corresponding API calling:
Time to wait before timeout
Table 2. Time to wait before timeout when Alipay+ calls an API to Mobile Payment Partner
Time to wait before timeout when Mobile Payment Partner calls an API to Alipay+
When Mobile Payment Partner calls the API to Alipay+, the timeout length is set by Mobile Payment Partner. The time to wait before timeout when Mobile Payment Partner calls the
/v1/payments/notifyPayment to Alipay+ is 5 seconds.
Understand different amounts
Multiple fields that are related with the amount are involved in the Payment interface and Refund interface. See the following list for explanations.
The following list describes refundAmount and refundFromAmount:
- refundAmount is the amount that's refunded to the user by Mobile Payment Partner.
- refundFromAmount is the refund amount that the user receives eventually.
Mobile Payment Partner refunds the amount to the user according to refundFromAmount.
The following list describes orderAmount, paymentAmount, payToAmount, surchargeAmount, savingsAmount, paymentQuote.
- orderAmount: The orginal order amount displayed by the merchant for user consumption records or payment results page display.
- paymentAmount: The amount that Mobile Payment Partner requests to receive in the currency that Alipay+ uses to create the payment order. If promotion exists, this is the amount that excludes the promotion amount.
- payToAmount: The amount that Mobile Payment Partner settles to Alipay+ in Mobile Payment Partner's currency. When Mobile Payment Partner's currency is different from paymentAmount.currency, the following equation applies: payToAmount.value=paymentAmount.value*paymentQuote.quotePrice.
- surchargeAmount: If this field is used, this is the actual amount that the user pays, but the amount that Mobile Payment Partner settles to Alipay+ is still payToAmount. surchargeAmount.value=paymentAmount.value*surchargeQuote.quotePrice.
- savingsAmount: The total amount that is saved if payment promotion exists. savingsAmount.currency is the same with payToAmount.currency.
- paymentQuote: The exchange rate between paymentAmount and payToAmount. This filed is only used when payToAmount.currency is not the same with paymentAmount.currency.
The following figure illustrates where the amounts are used in an actual situation:
Figure 1. Amounts in UX
- orderAmount is displayed at merchant's order confirmation page and Mobile Payment Partner's payment confirmation page.
- quotePrice can be paymentQuote.quotePrice or surchargeQuote.quotePrice, depending on whether surcharge is used.
- paymentAmount is optional. In this case, it is not on the UI. It can be different from orderAmount if there is any promotion from Acquirer. However, Mobile Payment Partner should store paymentAmount in the system for reference.
- savingsAmount is the sum of paymentPromoInfo.paymentPromoDetails.savingsAmount.
The following figures describe the roles of each amount in a transaction:
orderAmount is a pass-through field in the information flow.
Figure 2. orderAmount
- Amounts in a payment request when surchargeAmount is not used:
- Alipay+ passes paymentAmount, payToAmount, (and savingsAmount, if any) to Mobile Payment Partner.
- The user sees payToAmount in the payment page as the payment amount, and pays in the amount and currency accordingly.
- Mobile Payment Partner settles to Alipay+ by using payToAmount.
Figure 4. Amounts in a payment
- Amounts in a payment request when surchargeAmount is used:
- Alipay+ passes paymentAmount, payToAmount, surchargeAmount, (and savingsAmount, if any) to Mobile Payment Partner.
- The user sees surchargeAmount in the payment page as the payment amount, and pays in the amount and currency accordingly.
- Mobile Payment Partner still settles to Alipay+ by using payToAmount.
Figure 5. Amounts in a payment when surchargeAmount is used
Understand currency unit
The currency follows ISO 4217 standard. All amounts presented in the sample codes are expressed in the smallest currency unit. For example, if the value is 100, the amount is $1.00 when currency is USD, or ￥100 when currency is JPY.
Support promotion tools
To increase transactions for the merchants or Acquirers, Alipay+ provides promotion tools which can be applied by the user during the payment. Mobile Payment Partner requires to support the usage of the promotion tools. Currently the supported promotion tool provided by Alipay+ is the instant discount, which means that the discount is triggered automatically when the order amount reaches a benchmark. For example, Alipay+ supports 10 JPY discount for 100 JPY and a user places an order with the amount of 110 JPY, then the user pays 100 JPY actually.
When the promotion tools are used in the payment, Alipay+ forwards the promotion information in the payment request to Mobile Payment Partner and specifies the amount that is saved for the user in the Mobile Payment Partner's currency. All promotion information is specified by
paymentPromoInfo. See Payment -> Promotion for details. After the user completes the payment, Mobile Payment Partner must display the promotion information on the payment result page in one of the following ways:
- Mobile Payment Partner itemizes the discounts in detail.
- Mobile Payment Partner summarizes the discounts and displays the total amount that is saved for user.
- Mobile Payment Partner itemizes the discounts in detail and displays the total amount that is saved for user at the same time.
When the refund for a payment with promotion is initiated, the promotion refund information must be specified in the refund request by
refundPromoInfo. See Refund -> Promotion for details.
Mobile Payment Partner must set the risk control mechanism for the payment with promotion. The following figure illustrates the process:
Figure 6. Risk control process
Alipay+ uses the user ID obtained from Mobile Payment Partner to perform the risk evaluation. For the cashier payment, the user ID is returned by Mobile Payment Partner to Alipay+ in the response of Authorization Apply Token interface, specified by
customerId. See Payment process for details.
Risk control strategies:
- Reject payments made by users who abused promotion tools, gambled, or had bad credit.
- Reject payments occurring outside of the country where the merchant is located by using the Location Based Service.
- Reject payments made with an application that is maliciously modified, or with a tampered device, such as emulator, root device, and the device after jailbreaking.
- Reject payments made by the device that is associated with more than 3 accounts in recent 24 hours.
- If Alipay+ detects any risk, Mobile Payment Partner helps to investigate and communicate the result with Alipay+.
- Alipay+ and Mobile Payment Partner update the risk control strategies accordingly if the promotion has specific requirements.
Understand involved IDs and their relationships
When Partners use the Payment Switch Service provided by Alipay+, many IDs are involved. Each ID identifies a party or an object. This document describes all IDs that are used in the Payment Switch Service and relationships between IDs.
What are the involved IDs?
The following figure illustrates the IDs and relationships between IDs:
Figure 7. Involved IDs in Payment Switch Service
The relationship between authClientId and referenceMerchantId in this figure is for Auto Debit Payment.
The following table lists the basic information about the IDs:
The unique ID that is assigned by Alipay+ to identify an Acquirer
The unique ID that is assigned by Alipay+ to identify a Mobile Payment Partner
The unique ID that is assigned by Alipay+ to identify a client during the integration with Alipay+
The unique ID that is assigned by Acquirer to identify a merchant
The unique ID that is assigned by the merchant to identify a store
The unique identifier for AuthClient. AuthClient is the authorization object to which the user grants resource access permission.
Values of acquirerId and pspId comply with the following format and pattern:
- Format: A 16-character combination of letters and digits
- Pattern: 16 characters
- One letter or digit that corresponds to the version
- Two digits that correspond to the Partner category
- Five letters, five digits, or five-character combination of letters and digits that correspond to the Partner code
- Two letters, two digits, or two-character combination of letters and digits that correspond to the primary branch code of the Partner
- Four digits that correspond to the secondary branch code of the Partner
- Two letters, two digits, or two-character combination of letters and digits that are reserved
What are the relationships between different IDs?
The following list describes the relationships between IDs:
- When a Partner is a Mobile Payment Partner and at the same time is also an Acquirer, pspId and acquirerId of the Partner are the same.
- One acquireId or one pspId corresponds to one clientId.
- One clientId can be used to integrate with multiple APIs. For example, one clientId is used to integrate with several interfaces, such as the Payment interface, the Refund interface, and the Payment Notify interface.
- One clientId corresponds to one unique pair of keys. However, when the keys are updated, one clientId has an original pair of keys and a new pair of keys within an agreed period. After the agreed period, the keys of the original version are expired.
- One Acquirer might have multiple merchants, therefore one acquirerId might correspond to multiple referenceMerchantId. For example, two Japanese merchants (with two referenceMerchantId of M00xxxxx0001 and M00xxxxx0002) are connected with Alipay+ through the same Acquirer (with an acquirerId of 102xxxxxxxxxxxx0001).
- AuthClient is the authorization object to which the user grants resource access permission. For Auto Debit Payment, AuthClient is the merchant. As illustrated in the figure, one merchant might have multiple AuthClients, therefore one referenceMerchantId might correspond to multiple authClientId. For example, one Japanese merchant (with a referenceMerchantId of M00xxxxx0001) has two apps (with two authClientId of 218xxxxxxxxx1234 and 218xxxxxxxxx1235). For offline payment scenarios, AuthClient might be Alipay+. For the specific description of authClientId in different payment scenarios, see the integration document of each payment solution.
- One merchant might have multiple stores, therefore one referenceMerchantId might correspond to multiple referenceStoreId. For example, one Japanese merchant (with a referenceMerchantId of M00xxxxx0001) has two stores (with two referenceStoreId of S00xxxx0001 and S00xxxx0002).
When are the IDs assigned?
The following list describes when the IDs are assigned:
- For Auto Debit Payment, authClientId is assigned when the merchant completes the onboarding process. For other scenarios, see the integration documentation for details.
- pspId, acquirerId, clientId, and referenceMerchantId are assigned when the Partner completes the onboarding process. Among which, referenceMerchantId is assigned by the Acquirer to uniquely identify a merchant.