Alipay+ DocsAlipay+ Docs

Accept payments with client SDK

This chapter goes through the process of integrating the capability of accepting payments by using Alipay+ server SDK, Alipay+ client SDK and APIs.

The process is used in the scenario where a user uses a wallet app to scan the QR code that is presented by the merchant, which can be either an entry code or an order code.

Workflow

To accept a payment, the MPP must identify whether the code is an Alipay+ code, then decode the code value before proceeding to the payment processes.

The following figure illustrates the payment flow:

正扫sdk.jpg

Figure 1. Payment flow

The payment flow consists of the following steps:

  1. The user uses the wallet app to scan the QR code that is presented by the merchant (step 1).
  2. The MPP client sends the code value to the MPP server for identification (step 2).
  3. The MPP server identifies the code.
    • If the code is an MPP local code or in the MPP's allowlist, the MPP identifies the code value according to its own business logic. For more information about what is an allowlist, see Allowlist solution.
    • If the code is neither an MPP local code nor in the MPP's allowlist, the MPP server calls Alipay+ server SDK to identify the code (step 3).
  1. The MPP server/Alipay+ server SDK returns the code identification result that is specified for the isAcCode parameter to the MPP client (step 4-5).
  • If the value of the isAcCode parameter is true, the MPP client calls the decode API to send the decoding request to Alipay+ client SDK (step 6).
    • If the code is identified as an entry code:
      1. Alipay+ client SDK redirects the user to the merchant's cashier page (step 7).
      2. The user enters the payment amount on the merchant's cashier page (step 8).
      3. The merchant/ACQP constructs the Alipay+ URL based on the code value (step 9).
      4. The merchant/ACQP redirects the user to the Alipay+ URL (step 10).
      5. Alipay+ client SDK intercepts the Alipay+ URL and parses the query parameter to obtain the code value (step 11).
      6. Alipay+ client SDK sends the code value to Alipay+ for decoding (step 12-13).
    • If the code is identified as an order code, Alipay+ client SDK sends the code value to Alipay+ to decode directly. For the following procedures, see step 14.
  • If the value of the isAcCode parameter is false, the MPP rejects the code and presents the message that the code value is invalid.
  1. Alipay+ sends the decoding result to the merchant/ACQP and the merchant/ACQP returns the order information (step 14-15).
  2. Alipay+ sends the payment request to the MPP server by calling the pay API (step 16).
  3. The MPP server returns the payment URL to Alipay+ (step 17).
  4. Alipay+ forwards the payment URL to Alipay+ server SDK, which then directs the user to the payment page (step 18-19).
  5. The MPP client displays the payment page to the user (step 20).
  6. The user confirms the payment and the MPP client notifies Alipay+ of the payment result (step 21-25).
  7. The MPP client redirects back to the payment result page and the payment result is displayed to the user (step 26-27).

Note: The payment flow is based on the situation where the MPP uses the allowlist solution for the code identification. For more information about the code identification solution, see Identify the code value.

Establish session between Alipay+ client SDK and Alipay+

Note: 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:

1584599550476-dfcba2b1-ba26-4d04-8f0d-5db50a781878.png

Figure 2. Workflow of establishing a session

Complete the following steps to establish a session:

  1. Alipay+ client SDK calls the getAuthCode interface to obtain the authorization code from MPP app (step 1).
  2. MPP app returns the authorization code to Alipay+ client SDK (step 1.3).
  3. Alipay+ client SDK sends the authorization code to Alipay+(step 2).
  4. 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).
  5. Alipay+ creates the session ID (step 2.2).
  6. Alipay+ returns the session ID to Alipay+ client SDK and the session is created (step 2.3).

Read the following sections for the 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 AUTHORIZATION_CODE

4

authCode

The authCode generated by MPP must be within 32 bits. An authCode can only be used once, and if an authCode is used for a second time, an INVALID_AUTHCODE error will be returned.

5

refreshToken

Optional

Required when grantType is REFRESH_TOKEN. When grantType is REFRESH_TOKEN, refreshToken is used to retrieve accessToken. MPP uses this field for the idempotence control. For the requests of retrieving a new access token with the same refreshToken, MPP must return the same values for the required fields.

6

passThroughInfo

Optional

/

The interface response contains the following fields:

No.

Field

Remarks

3

result

If result.resultStatus is F or U, the AuthClient can guide the user to try again.

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

copy
{
  "acquirerId":"10221880000000****",
  "pspId":"10220880000000****",
  "authCode": "663A8FA9D83648EE8AA11FF68298****",
  "grantType": "AUTHORIZATION_CODE",
}

Response sample

copy
{
  "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.

Identify the code value

Wallet needs to design a solution, such as allowlist solution or blocklist solution, to identify the code and then process the code accordingly. It's recommended that MPP uses the allowlist solution.

Allowlist solution

The following figure illustrates the allowlist solution flow:

1111.png

Figure x. MPP allowlist solution

The allowlist solution contains the following key points:

  • If the code is a local code or in the allowlist of the wallet, wallet processes the code according to its own business logic.
  • If the code is neither a local code nor in the allowlist of the wallet, wallet calls Alipay+ server SDK to identify the code value. See Identify the code for details.

Blocklist solution

The following figure illustrates the blocklist solution flow:

2222.png

Figure x. MPP blocklist solution

The blocklist solution contains the following key points:

  • If the code is in the blocklist, wallet presents the message that the code is invalid and rejects the code.
  • If the code is not in the blocklist and is a local code that is supported by the wallet, wallet processes the code according to its own business logic.
  • If the code is neither in the blocklist nor a local code supported by the wallet, wallet calls Alipay+ server SDK to identify the code value. See Identify the code for details.

Identify the code

Complete the following steps to identify the code by using Alipay+ server SDK. For more information about how to use Alipay+ server SDK, See Alipay+ server SDK integration guide.

1. Initialize the code identification service

Initialize Alipay+ server SDK by calling the ac.code.service.CodeIdentificationService#init interface.

copy
CodeIdentificationInitResult result = codeIdentificationService.init();
if (result.getResult().getResultStatus().equals("S")){
    // Initialization success.
} else {
    // Block the application startup and troubleshoot
}

Result processing logic:

  • If result.resultStatus is S, initialization is successful.
  • If result.resultStatus is F or U, the application startup is blocked. Wallet can troubleshoot the problems based on result codes and logs.

2. Identify whether the code can be processed by Alipay+

Call the ac.code.service.CodeIdentificationService#identify interface to identify whether the code can be processed by Alipay+.

copy
CodeIdentificationIdentifyRequest request = new CodeIdentificationIdentifyRequest();
request.setCodeValue("28100104df23423423423");
request.setOpenId("228770368287434384680");
CodeIdentificationIdentifyResult result = codeIdentificationService.identify(request);
if (result.getResult().getResultStatus().equals("S") && result.isAcCode()){
    // the code should be processed by AlipayConnect
}
if (result.getResult().getResultStatus().equals("F"){
    // Please pay attention to resultCode
}

Result processing logic:

  • If result.resultStatus is S, the code identification is successful. See the following list for details:
    • If isAcCode is true, the code can be processed by Alipay+ and wallet app must call Alipay+ client SDK's API to process this code with acDecodeConfig specified.
    • If isAcCode is false, the code cannot be processed by Alipay+.
  • If result.resultStatus is F, code identification is failed. MPP handles the result based on result codes.
  • If result.resultStatus is U, unknown exceptions occur during the code identification and MPP can check logs to view details. MPP can also retry.

Decode the code value

If the code is identified as an Alipay+ code, wallet app can send a decoding request to Alipay+ client SDK to obtain the code value. For more information about how to use Alipay+ client SDK, see Alipay+ client SDK integration guide.

Process flow

Complete the following steps to decode:

  1. Initialize Alipay+ client SDK

Call the init interface that is for Android or the initWithContext interface that is for iOS to initialize Alipay+ client SDK at first.

2. Call the decode interface

Call the decode interface and send the decoding request to Alipay+.

Processing logic

The following rules apply:

  • Invoke the cashier when the decoding succeeds.
  • If the decoding failed, the wallet must be able to receive the error details from contained in the response, and presents certain message to user accordingly to indicate the error.
  • Exceptional cases:
    • If user has scaned the code, however, the code timeouts, wallet must present certain messages to user to indicate the timeout and encourage the user to retry.
    • If user has scaned the code, however, the code is invalid, wallet must present certain messages to user to indicate that the code is invalid and encourage the user to retry.

Process the payment request from Alipay+

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 Merchant-presented Mode Payment scenario, both isCashierPayment and isInStorePayment are true. When paymentMethod.customerId is null, merchant.store and env.userAgent must be provided.

 

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 (S or F), MPP must return the unique result.

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

In Merchant-presented Mode Payment scenario, isInStorePayment is true and isCashierPayment is true, paymentMethodType (value is CONNECT_WALLET) must be provided. The customerId field is required for Mobile Payment Partner.

8

paymentFactor

needSurcharge must be true if surcharge function is used. Both isInStorePayment and isCashierPayment must be provided as true. For the payment that requires cross-border settlement, isCrossborderSettlement must be true.

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 HALF_EVEN.

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 true.

17

passThroughInfo

Optional

/

The interface response contains the following field:

No.

Field

Remarks

1

result

If result.resultCode is UNKNOWN_EXCEPTION, all optional response fields are not required. 

4

paymentId

Optional

Must be returned when the payment is successful.

5

paymentUrl

Optional

/

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.
  • Normal case: When the payment request is successfully submitted, return a result code PAYMENT_IN_PROCESS.
  • Optional: Exceptional case: Verify the user status, if the status is abnormal, return a result.resultCode of USER_STATUS_ABNORMAL.

Sample

Merchant-presented Mode Payment request:

copy
{
  "order":{
    "referenceOrderId":"OrderID_0100000101",
    "orderDescription":"SHOES",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    },
       "merchant":{
          "referenceMerchantId":"M00000000001",
          "merchantMCC":"5411",
          "merchantName":"UGG",
          "merchantAddress":{
             "region":"JP",
             "city":"xxx"
          },
          "store":{
             "referenceStoreId":"S0000000001",
             "storeName":"UGG-2",
             "storeMCC":"5411"
          }
       }
  }, 
  "paymentRequestId":"20100000000000000000000000011111",
  "paymentAmount":{
    "value":"100",
    "currency":"JPY"
  },
  "paymentMethod":{
      "paymentMethodType": "CONNECT_WALLET",
      "customerId":"2160000000000001"
  },
  "payToAmount":{
    "value":"1000",
    "currency":"KRW"
  },
  "paymentQuote":{
    "quoteId":"1234567",
    "quoteCurrencyPair":"JPY/KRW",
    "quotePrice":"10.0000"
  },
  "paymentFactor": {
      "isCashierPayment":"true",
      "isInstorePayment":"true"
  } 
 }

Merchant-presented Mode Payment response

copy
{
 "result": {
    "resultCode":"PAYMENT_IN_PROCESS",
    "resultStatus":"U",
    "resultMessage":"Payment is processing."
 },
 "paymentId":"123000000000000000000000000004484",
 "paymentUrl":"https://xxxxx/xxxx/xxxx"
}

More information

See pay for details.

Return the payment URL to SDK to present the cashier page

MPP returns the payment URL to SDK. Alipay+ client SDK opens the MPP payment URL by using the pay interface. User confirms to pay. For the samples for Android and iOS, see the A+ client SDK integration guide.

Optional: Redirect the user back to the merchant page

MPP app redirects the user back to the merchant page when paymentRedirectUrl is specified in the payment request. The merchant presents the payment result to the user.

Wallet can use AC SDK to redirect user back to the merchant page, and the following rules apply:

  • If the payment is successfully completed, the user must be redirected back to the merchant page.
  • Optional: If the payment is not successfully completed, the user is redirected back to the merchant page. Wallet must present a result page to indicate that the payment failed.
  • Optional: If the user cancels the payment in the wallet (payment cancel button exists), the user is redirected back to the merchant page.
  • Wallet must trust Alipay+ merchant URL, so that the redirection can be successful without adding the Alipay+ merchant URL to whitelist.
  • Wallet must support the redirection to merchant App by using scheme, or UL/AL
  • In the scan-to-pay scenario, do not redirect back to merchant App. Instead, it's suggested to redirect to wallet homepage.
  • If the merchant page is an WAP page, redirect back to merchant WAP page if the device is of Android system (due to system restrictions, do not redirect back to merchant WAP page if the user is using an iOS device).
  • If the merchant does not provide a redirection address, do not redirect back to the merchant page.