Alipay+ DocsAlipay+ Docs

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

1589183280605-f39b1352-71cb-4d38-b3bc-1233af681807.png

Figure 1. Flow of obtaining the payment code

Obtaining the payment code contains the following steps:

  1. Mobile Payment Partner app calls the getPaymentCode interface to request the payment code from Alipay+ (step 1)
  2. Alipay+ client SDK creates a session with Alipay+ (step 1.1). If the session is created, skip this step.
  3. Alipay+ client SDK requests the payment code by session ID from Alipay+ (step 1.2)
  4. Alipay+ returns the payment code to Alipay+ client SDK (step 1.3)
  5. 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:

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

Figure x. 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 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. The first 8 digits of the authorization code must be in the format of 281***13. The fourth to sixth digits are assigned by Alipay+. 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": "281010133AB2F588D14B43231234****",
  "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.

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:

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

copy
[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).

copy
#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 PaymentisInStorePayment is true, and merchant.store 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

For User-presented Mode Payment, isInStorePayment is true and isCashierPayment is falsepaymentMethodType (value is CONNECT_WALLET), paymentMethodId (value is same as that of paymentCode), and customerId (when the paymentCode is generated by Alipay+) must be provided.

8

paymentFactor

The following rules apply:

  • needSurcharge must be TRUE if surcharge function is used. 
  • For User-presented Mode Payment, isInStorePayment 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.

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

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:

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

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