Accept a payment
Accepting a payment consists of obtaining the payment code and processing the payment initiated by the merchant.
Obtain the payment code
The following figure illustrates the flow of obtaining the payment code from Alipay+:
Figure 1. Flow of obtaining the payment code
Obtaining the payment code contains the following steps:
- Mobile Payment Partner app calls the getPaymentCode interface to request the payment code from Alipay+ (step 1)
- Alipay+ client SDK creates a session with Alipay+ (step 1.1). If the session is created, skip this step.
- Alipay+ client SDK requests the payment code by session ID from Alipay+ (step 1.2)
- Alipay+ returns the payment code to Alipay+ client SDK (step 1.3)
- Alipay+ client SDK returns the payment code to Mobile Payment Partner app (step 1.4)
Read the following sections for main steps.
Before you begin
Before you start the integration with Alipay+ User-presented Mode Payment product, ensure that you integrate Alipay+ client SDK. See Alipay+ client SDK integration guide for details.
Establish session between Alipay+ client SDK and Alipay+
Skip this step if the session is already created.
To ensure a secure communication between Alipay+ and Alipay+ client SDK, a session is created.
The following figure illustrates the workflow of establishing a session:
Figure x. Workflow of establishing a session
Complete the following steps to establish a session:
- Alipay+ client SDK calls the getAuthCode interface to obtain the authorization code from MPP app (step 1).
- MPP app returns the authorization code to Alipay+ client SDK (step 1.3).
- Alipay+ client SDK sends the authorization code to Alipay+(step 2).
- Alipay+ calls the applyToken interface to obtain the access token from MPP server and MPP server returns the access token and customer ID to Alipay+ (step 2.1 and step 2.1.2).
- Alipay+ creates the session ID (step 2.2).
- Alipay+ returns the session ID to Alipay+ client SDK and the session is created (step 2.3).
Read the following sections for main steps:
1. Call the getAuthCode interface to obtain the authorization code
Alipay+ client SDK calls the getAuthCode interface to obtain the authorization code from MPP. The value of scopes is BASE_USER_INFO
. MPP returns the authorization code by authCallback. For the samples for Android and iOS, see Alipay+ client SDK integration guide.
2. Obtain the access token and customer ID from wallet
Alipay+ client SDK sends the authCode to Alipay+. With the authCode received, Alipay+ calls the applyToken interface to request access token. In this case, the value of acquirerId
is fixed as 2052666000000000
, which represents Alipay+.
Alipay+ can request access token with the authCode received.
Process flow
The interface request contains the following fields:
No. | Field | Remarks |
1 | pspId | / |
2 | acquirerId | / |
3 | grantType | Specify the value as |
4 | authCode | The authCode generated by MPP must be within 32 bits. The first 8 digits of the authorization code must be in the format of |
5 | refreshToken Optional | Required when grantType is |
6 | passThroughInfo Optional | / |
The interface response contains the following fields:
No. | Field | Remarks |
3 | result | If result.resultStatus is |
4 | accessToken Optional | Required when the authorization token application request is successful, the AuthClient can use accessToken to access the corresponding user's resource scope. This token must be within 128 bits. |
5 | accessTokenExpiryTime Optional | Must be returned when the authorization token application request is successful. |
6 | refreshToken Optional | Must be returned when the authorization token application request is successful. This token must be within 128 bits. |
7 | refreshTokenExpiryTime Optional | Must be returned when the authorization token application request is successful. |
8 | customerId Optional | Must be returned when the authorization token application request is successful. |
9 | passThroughInfo Optional | / |
Processing logic
If the access token is short-term valid, set the validity period to more than 10 minutes.
Mobile Payment Partner must be able to provide the refreshToken, and the validity period of the refreshToken must be more than 1.5 years.
Refresh access token
When the original token expires, the AuthClient requests a new access token by using the refresh token. In this scenario, you can also use the applyToken interface. In addition, if the refresh request failed, Mobile Payment Partner must return a result.resultStatus of F
and an error code that is corresponding to a specific reason.
- If the refresh token in invalid, return
INVALID_REFRESH_TOKEN
- If the refresh token expires, return
EXPIRED_REFRESH_TOKEN/INVALID_REFRESH_TOKEN
Sample
Request sample
{
"acquirerId":"10221880000000****",
"pspId":"10220880000000****",
"authCode": "281010133AB2F588D14B43231234****",
"grantType": "AUTHORIZATION_CODE",
}
Response sample
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "Success",
"resultStatus": "S"
},
"accessToken": "281010033AB2F588D14B43238637264FCA5A****",
"accessTokenExpiryTime": "2019-06-06T12:12:12+08:00",
"refreshToken": "2810100334F62CBC577F468AAC87CFC6C910****",
"refreshTokenExpiryTime": "2019-06-08T12:12:12+08:00",
"customerId":"278980891233213455671****"
}
More information
See applyToken for details.
3. Alipay+ creates the session and return session ID to Alipay+ client SDK
Alipay+ creates the session, and associates sessionId
with the returned customerId
and accessToken
. Alipay+ returns the session ID to Alipay+ client SDK. The session is created between Alipay+ and Alipay+ client SDK.
By default, the validity period of the session is 30 minutes (set by Alipay+ for security reasons). Auth login is normally valid for 360 hours unless user logout.
Initialize Alipay+ client SDK
Before Mobile Payment Partner uses the features provided by the Alipay+ client SDK, call the init API that is for Android or the initWithContext API that is for iOS to initialize the Alipay+ client SDK at first.
For more information about the samples for initializing the Alipay+ Android client SDK, see Step 3: Initialize SDK in your app.
For more information about the samples for initializing the Alipay+ iOS client SDK, see Step 3: Initialize SDK in your app.
Call the getPaymenCode interface to obtain the payment code
Mobile Payment Partner app calls the getPaymentCode interface to obtain the payment code from Alipay+.
Requirements:
If the getPaymentCode call succeeds, Mobile Payment Partner must display the payment code. And, if the call fails, Mobile Payment Partner must be able to automatically retry. In addition, Mobile Payment Partner should be able to manually switch the region.
Sample for Android:
String region = "CN";
IAPConnect.getPaymentCode(region, new IPaymentCodeListener() {
@Override
public void onPaymentCodeUpdated(String paymentCode) {
// handle the payment code
}
@Override
public void onPaymentCodeUpdateFailed(String errorCode, String errorMessage) {
// handle the error information
}
});
Sample for iOS:
[AlipayConnect getPaymentCode:@"CN" paymentCodeListener:self];
After the getPaymentCode interface is called, Alipay+ client SDK sends the request of obtaining the payment code to Alipay+ by using sessionId
. Alipay+ returns the payment code to Alipay+ client SDK. After that, Alipay+ client SDK returns the payment code to Mobile Payment Partner app by paymentCodeListener (Mobile Payment Partner app must implement the IAPConnectPaymentCodeListener protocol to obtain the code).
#pragma mark - IAPConnectPaymentCodeListener
- (void)onPaymentCodeUpdateFailed:(IAPConnectResultCode)resultCode resultMessage:(NSString *)resultMessage {
}
- (void)onPaymentCodeUpdated:(NSString *)paymentCode {
dispatch_async(dispatch_get_main_queue(), ^{
[self.mixedCodeView updatePaymentCode:paymentCode];
});
}
Process the payment
Mobile Payment Partner needs to process the payment requests sent from Alipay+ by using the pay interface.
Process flow
The interface request contains the following fields:
No. | Field | Remards |
1 | acquirerId | / |
2 | pspId | / |
3 | order | In User-presented Mode Payment, isInStorePayment is |
4 | paymentRequestId | This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status ( |
5 | paymentAmount | The amount that Mobile Payment Partner requests to receive in the currency that A+ uses to create the payment order. If promotion exists, this is the amount that excluds the promotion amount. |
6 | 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 the merchant's currency, the following equation applies: payToAmount.value=paymentAmount.value*paymentQuote.quotePrice. |
7 | paymentMethod | For User-presented Mode Payment, isInStorePayment is |
8 | paymentFactor | The following rules apply:
|
9 | paymentQuote Optional | Required when paymentAmount is not equal to payToAmount. The value of payToAmount is computed based on values of paymentAmount and paymentQuote, by using a rounding mode of This filed is only used when payToAmount.currency is not the same with paymentAmount.currency. |
10 | paymentExpiryTime | Required when payment is required to be successful before the expiration time. |
11 | paymentNotifyUrl Optional | / |
12 | paymentRedirectUrl Optional | / |
13 | paymentPromoInfo Optional | Required when the promotion is applied in the payment. |
14 | surchargeInfo Optional | Required when paymentFactor.needSurcharge is |
17 | passThroughInfo Optional | / |
The interface response contains the following field:
No. | Field | Remarks |
1 | result | If result.resultCode is |
4 | paymentId | Must be returned when the payment is successful. |
5 | paymentUrl | / |
6 | paymentTime | Must be returned when the payment is successful. |
7 | paymentAmount Optional | / |
8 | payToAmount Optional | / |
9 | customerId Optional | Must be returned when the payment is successful. |
11 | passThroughInfo Optional |
Processing logic
When processing payment requests, Mobile Payment Partner must pay attention to the following items:
- Use the timeout value assigned by Alipay+, if Alipay+ does not provide the timeout value, for Merchant-presented Mode Payment, set the timeout value as 3 minutes at most. When timeout occures, Mobile Payment Partner closes the payment order and returns an error code
ORDER_IS_CLOSED
. - Mobile Payment Partner must be able to handle payment requests with specified customerId (paymentMethod.customerId).
- Mobile Payment Partner must be able to check the idempotency of payment requests by using paymentRequestId.
- Support all the currencies as defined in ISO 4217.
- Mobile Payment Partner must be able to synchronously return the payment result.
- Exceptional case:
- Check whether the balance is enough. If not, return a result.resultCode of
USER_BALANCE_NOT_ENOUGH
. - Mobile Payment Partner must verify the user status (especially, if user is allowed to login when the account is frozen). if the status is abnormal, return a result.resultCode of
USER_STATUS_ABNORMAL
. - Optional: If the payment is declined for risk reasons, return a result.resultCode of
RISK_REJECT
. - Optional: If the payment failed because the payment method used by the Mobile Payment Partner is not available, return a result.resultCode of
UNAVAILABLE_PAYMENT_METHOD
. - Optional: If the payment is declined because the payment verification is failed, return a result.resultCode of
USER_PAYMENT_VERIFICATION_FAILED
. - Optional: If the payment is declined because the user KYC is failed, return a result.resultCode of
USER_KYC_NOT_QUALIFIED
. - Optional: If the payment is declined because the merchant verification is failed, return a result.resultCode of
MERCHANT_NOT_REGISTERED
.
Payment amount limitation exists
If payment amount limitation exists, Mobile Payment Partner must pay attention to the following items:
- Check whether the amount exceeds the payment amount limit of a single transaction. If yes, return an error code
PAYMENT_AMOUNT_EXCEED_LIMIT
- Check whether the accumulated amount exceeds the limit. If yes, return an error code
USER_AMOUNT_EXCEED_LIMIT
- Check whether the payment times exceed the limit. If yes, return an error code
PAYMENT_COUNT_EXCEED_LIMIT
Promotion exists
If promotion exists, the amount user actually pays is specified in the payToAmount filed.
Sample
Request:
{
"order": {
"referenceOrderId": "OrderID_010101****",
"orderDescription": "SHOES",
"orderAmount": {
"value": "100",
"currency": "JPY"
},
"merchant": {
"referenceMerchantId": "M00xxxxx0001",
"merchantMCC": "1405",
"merchantName": "UGG",
"merchantAddress": {
"region": "JP",
"city": "xxx"
},
"store": {
"referenceStoreId": "S00xxxx0001",
"storeName": "UGG-2",
"storeMCC": "1405"
}
}
},
"acquirerId": "102218800000000****",
"pspId": "102217200000000****",
"paymentRequestId": "201811291907410100070000007****",
"paymentAmount": {
"value": "100",
"currency": "JPY"
},
"paymentMethod": {
"paymentMethodType": "CONNECT_WALLET",
"paymentMethodId": "281006050000000000125733DAHJ****",
"customerId":"2160xxxxxxxxxxx1"
},
"payToAmount": {
"value": "1000",
"currency": "KRW"
},
"paymentQuote": {
"quoteId": "1234567",
"quoteCurrencyPair": "JPY/KRW",
"quotePrice": "10.0000"
},
"paymentFactor": {
"isInStorePayment": "true"
}
}
Response:
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"Success"
},
"paymentId":"201xxxxxxxxxxxxxxxxxxxxxxx4444",
"paymentTime": "2020-01-01T12:01:01+08:30",
"customerId":"1234567"
}
More information
See pay for details.