Integration guide

This topic guides you through how to build an integration to implement Easy Pay by using the APIs provided by Alipay+.

To make a payment, the MPP needs to take the following steps:

Step 1: Check the user's MPP account
Step 2: Create a payment order and send OTP to the user
(Optional) Step 3: Resend OTP to the user
Step 4: Verify OTP and process the payment
(Optional) Step 5: Complete the authorization

Easy Pay workflow

The following figure illustrates the workflow of making a payment in the Easy Pay scenario.

Easy Pay时序图.png

Figure 1: Workflow of making a payment

For the first-time payment, the payment process consists of the following steps:

After placing an order, the user chooses a payment method. The merchant/ACQP then sends a payment request to Alipay+ (Steps 1-2).
Alipay+ obtains the user's MPP account and calls the pay API for the first time to check whether the MPP account supports the payment (Steps 3-4).
Alipay+ obtains the checking result from the MPP. If the user's MPP account supports the payment, Alipay+ displays the authorization and payment page (Steps 5-6).
Alipay+ calls the pay API again to request the MPP to create a payment order and send an OTP to the user (Steps 7-8).
(Optional) If the user fails to receive an OTP, the merchant/ACQP calls the sendOTP API to Alipay+ which then syncs the request to the MPP. The MPP resends an OTP to the user (Steps 9-10).
The user decides whether to sign the authorization agreement on the order confirmation page and then enters the OTP code to pay (Step 11).
Alipay+ calls the pay API for the third time to request the MPP to verify the OTP and make the payment. The MPP can determine whether the user agrees to sign the agreement via the paymentFactor.isAuthorizationAndPay parameter (Step 12).
After verifying the OTP and completing the payment, the MPP returns the payment result to Alipay+ (Steps 13-14).
(Optional) If the value of paymentFactorisAuthorizationAndPay is true, which means the user agrees to sign the authorization agreement, the MPP completes the authorization and calls the authNotify API to return the authorization result with an access token to Alipay+. Alipay+ then syncs the authorization result and access token to the merchant/ACQP. Otherwise, Steps 15-17 can be skipped (Steps 15-17).
(Optional) Alipay+ calls the inquiryPayment API to inquire about the payment result and the MPP returns the payment result to Alipay+ (Steps 18-19).
The MPP calls the notifyPayment API to notify Alipay+ of the payment result (Step 20).
Alipay+ redirects the user to the merchant result page and syncs the payment result to the merchant/ACQP (Steps 21-22).
The merchant displays the authorization result (if any) and the payment result to the user (Step 23).

For the subsequent payments, if the user agrees to sign the authorization agreement in the previous payment, the payment process consists of the following steps:

The user selects a payment method on the Cashier Page (Step 24).
The merchant/ACQP sends a payment request to Alipay+ with an access token obtained from Step 17 in the first-time payment process (Step 25).
Alipay+ syncs the payment request to the MPP and receives the payment result (Steps 26-27).
The merchant/ACQP receives the payment result and displays the payment result to the user (Steps 28-29).

Step 1: Check the user's MPP account

After obtaining the user's MPP account, Alipay+ calls the pay API for the first time to request the MPP to check whether the user's MPP account supports the payment. In this step, no actual payment occurs.

Processing logic

When handling the pay API for the first time, take the following things into consideration:

Handle the request properly, especially the following parameters:

paymentFactor.isAgreementPayment: The value of this parameter must be set as true.
paymentFactor.isPaymentEvaluation: Its value must be set as true, which indicates that the MPP needs to evaluate the user's MPP account.
paymentMethod.paymentMethodId: The MPP uses this parameter to identify the user's account and evaluate whether it can support the payment.
paymentMethod.paymentMethodMetadata.userLoginId: If paymentMethod.paymentMethodId is not specified, the MPP uses this parameter in place of paymentMethod.paymentMethodId to identify the user's account and evaluate whether it can support the payment.
paymentMethod.paymentMethodMetadata.userLoginIdType: The type of method that the MPP user selects to log in to the MPP platform.

Ensure the following parameters are configured properly in the response:

result.resultStatus: If the checking result is successful, set the value of result.resultStatus to S. If the checking result is unsuccessful, set the value of result.resultStatus to F. If the checking result is unknown, set the value of result.resultStatus to U. For more information, see the Result code section in the pay API.

Sample

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "1022188000000000001",
  "order": {
    "merchant": {
      "merchantAddress": {
        "region": "HK"
      },
      "merchantDisplayName": "testAliasName",
      "merchantMCC": "5021",
      "merchantName": "testAliasName",
      "referenceMerchantId": "2188120xxxx99147"
    },
    "orderAmount": {
      "currency": "HKD",
      "value": "20"
    },
    "orderDescription": "57c1da80-936f-463c-8119-dc3279985fa5",
    "referenceOrderId": "57c1da80-936f-463c-8119-dc3279985fa5"
  },
  "payToAmount": {
    "currency": "HKD",
    "value": "20"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "20"
  },
  "paymentFactor": {
    "isAgreementPayment": "true",
    "isEasyPayScenario": "true",
    "isPaymentEvaluation": "true"
  },
  "paymentMethod": {
    "paymentMethodId": "",
    "paymentMethodMetaData": {
      "userLoginId": "852-524xx184",
      "userLoginIdType": "MOBILE"
    },
    "paymentMethodType": "ALIPAY_HK"
  },
  "paymentRequestId": "20230808190741010008300xxxx3482",
  "pspId": "1022160000000000000"
}

The MPP returns a response to Alipay+.

copy
{
  "customerId": "21602200xxxx2775",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

More information

For more information about how to handle the pay API request and return the response, see pay API.

Step 2: Create a payment order and send OTP to the user

After the user confirms the MPP account to continue the payment on the authorization and payment page, Alipay+ calls the pay API for the second time to request the MPP to create a payment order and send an OTP to the user.

Processing logic

When handling the pay API for the second time, take the following things into consideration:

Handle the request properly, especially the following parameters:

paymentFactor.isAgreementPayment: The value of this parameter must be set as true.
paymentFactor.isEasyPayScenario: Its value must be set as true, which indicates that it is an Easy Pay scenario where the MPP needs to create the payment order and send an OTP to a user.
paymentMethod.paymentMethodMetadata.userLoginId: The login ID that is used by the MPP user to log in to the MPP platform.
paymentMethod.paymentMethodMetadata.userLoginIdType: The type of method that the MPP user selects to log in to the MPP platform.
passThroughInfo: The risk control information that is passed through from the ACQP. The value of this parameter is in a set of key-value pairs.

Ensure the following parameters are configured properly in the response:

verifyRequestId: The unique ID that is assigned by the MPP to identify an OTP. Alipay+ needs this parameter to check if the OTP that the user enters is correct.
result.resultStatus: This parameter indicates the payment result status. In this step, the value of this parameter can't be S because the payment can't be successful before the MPP verifies the OTP. If the MPP creates the payment order successfully, set the value of result.resultStatus to U. If the MPP fails to create the payment order, set the value of result.resultStatus to F.

Sample

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "1022188000000000001",
  "order": {
    "env": {},
    "merchant": {
      "merchantAddress": {
        "region": "HK"
      },
      "merchantDisplayName": "testAliasName",
      "merchantMCC": "5021",
      "merchantName": "testAliasName",
      "referenceMerchantId": "21881200xxxx9147"
    },
    "orderAmount": {
      "currency": "HKD",
      "value": "20"
    },
    "orderDescription": "[orderDescription]EASYPAY from KADEMO Android",
    "referenceOrderId": "[referenceOrderId]1691465371002gN3pa"
  },
  "payToAmount": {
    "currency": "HKD",
    "value": "20"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "20"
  },
  "paymentExpiryTime": "2023-08-08T11:39:41+08:00",
  "paymentFactor": {
    "isAgreementPayment": "true",
    "isEasyPayScenario": "true"
  },
  "paymentMethod": {
    "paymentMethodMetaData": {
      "userLoginId": "852-524xx184",
      "userLoginIdType": "MOBILE"
    },
    "paymentMethodType": "ALIPAY_HK"
  },
  "paymentRequestId": "202308081907410100xxxx18626927",
  "pspId": "1022160000000000000",
  "passThroughInfo": "{\"buyerId\":\"testbuyerid\",\"gaid\":\"\",\"merchantTerminalType\":\"android\",\"pinRedirectUrl\":\"https://ac.alipay.com/page/antom-web-checkout/src/component-app/doubleFA/index.1.8.1.0.html?scene=cashierResultPage&instanceId=31a6d286-e429-4b1c-860e-e36ad1904291&isLandscape=&pmt=ALIPAY_HK&nvar=true&paymentSessionData=rM2KkhmS2c9+s3jeUmu4Bp3f8jUuJf8EWAhldoMwG6lQ9TIdIoRHVrywqm+7p0RvFrh8/mkgN6fWxFBIrPjmdA==&&SG&&188&ps=EASY_PAY&pmct=WALLET&psv=2.0&locale=en_US\",\"renderGroup\":\"h5\",\"riskInfo\":{\"apdid\":\"eYOIkhvjIRq2XFjY52pj/IXY/77dmHtokL6ZHmqNE83ORTrxg3qQDN6g\",\"clientIp\":\"140.*.*.*\",\"deviceData\":{\"accessWirelessNetType\":\"\",\"apdid\":\"eYOIkhvjIRq2XFjY52pj/IXY/77dmHtokL6ZHmqNE83ORTrxg3qQDN6g\",\"appVersion\":\"1.2.0\",\"asdk\":\"31\",\"baseband\":\"21C20B689S000C000,21C20B689S000C000\",\"board\":\"JAD\",\"brand\":\"HUAWEI\",\"cpuCoreNum\":\"8\",\"cpuFrequency\":\"2045000\",\"createTime\":\"1711002665151\",\"device\":\"HWJAD\",\"displayid\":\"JAD-AL50 4.*.*.*(C00E116R3P4)\",\"gsid\":\"33ac0bafa6be97f8\",\"h\":\"2578\",\"hardDisk\":\"498407047168\",\"incremental\":\"104.0.0.132C00\",\"language\":\"zh_CN_#Hans\",\"manufacture\":\"HUAWEI\",\"memory\":\"7668828\",\"mode\":\"13\",\"model\":\"JAD-AL50\",\"name\":\"JAD-AL50\",\"os\":\"android\",\"px\":\"1228*2578\",\"release\":\"12\",\"sdCard\":\"498386075648\",\"sdkName\":\"APPSecuritySDK-OVERSEA\",\"sdkVersion\":\"P8.0.0.20231008\",\"tags\":\"release-keys\",\"timeZone\":\"GMT+08:00\",\"updateTime\":\"1711002665433\",\"w\":\"1228\"},\"deviceRiskData\":{\"proxy\":\"0\",\"simulator\":\"0\"}},\"securityCode\":\"****************************************************************\"}"
}

The MPP returns a response to Alipay+.

copy
{
  "verifyRequestId": "e58z8UhmGLwXSrpgg5uuu3GF0ebIFpjm",
  "result": {
    "resultCode": "VERIFICATION_IN_PROCESS",
    "resultMessage": "The verification is still under process.",
    "resultStatus": "U"
  }
}

More information

For more information about how to handle the pay API request and return the response, see pay API.

(Optional) Step 3: Resend OTP to the user

If the user fails to receive the OTP, he/she can click the Resend code button on the authorization and payment page. The merchant/ACQP calls the sendOTP API to Alipay+ which then syncs the request to the MPP. After receiving the request, the MPP resends an OTP to the user.

Processing logic

When handling the sendOTP API, take the following things into consideration:

Handle the request properly, especially the following parameters:

userLoginId: The login ID that is used by the MPP user to log in to the MPP platform.
userLoginIdType: The type of method that the MPP user selects to log in to the MPP platform.
referenceRequestId: The unique ID that is assigned by Alipay+ to identify a payment request.

Ensure the following parameters are configured properly in the response:

verifyRequestId: The unique ID that is assigned by the MPP to identify an OTP. Alipay+ needs this parameter to check if the OTP that the user enters is correct.
result.resultStatus: This parameter indicates the OTP sending result.

If the OTP sending succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.
If the OTP sending fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly. For more information, see the Result codes section in sendOTP.
If the OTP sending result is unknown, set the value of result.resultStatus to U and the value of result.resultCode accordingly. For more information, see the Result codes section in sendOTP.

Sample

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "1022188000000000001",
  "referenceRequestId": "202404158903130000xxxx632734355",
  "pspId": "1022160000000000000",
  "userLoginId": "852-******11",
  "userLoginIdType": "MOBILE",
  "verifyType": "MOBILE"
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "verifyRequestId": "0b9fc14b1571815xxxx352139110000"
}

More information

For more information about how to handle the sendOTP API request and return the response, see sendOTP API.

Step 4: Verify OTP and process the payment

After the user enters the OTP to proceed with the payment, Alipay+ calls the pay API for the third time to request the MPP to verify the OTP and make the payment.

Processing logic

When handling the pay API for the third time, take the following things into consideration:

Handle the request properly, especially the following parameters:

paymentFactor.isVerificationAndPay: Its value must be set as true, which indicates that the MPP needs to verify the OTP and obtain the payment order information based on paymentRequestId to proceed with the payment.
paymentRequestId: The unique ID that is assigned by Alipay+ to identify a payment order.

Ensure the following parameters are configured properly in the response:

result.resultStatus :

If the OTP verification succeeds and then the payment succeeds, set the value of result.resultStatus to S.
If the OTP verification succeeds but the payment fails, set the value of result.resultStatus to F.
If the OTP verification succeeds and the payment result is in unknown status, set the value of result.resultStatus to U.
For the same verifyRequestId, if the OTP verification fails but Alipay+ can still retry, set the value of result.resultStatus to U with the error code VERIFICATION_IN_PROCESS.
For the same verifyRequestId, if the OTP verification fails and exceeds the limit of retries, set the value of result.resultStatus to F.

For more information, see the Result code section in the pay API.

Sample

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "1022188000000000001",
  "authorizationInfo": {
    "authClientId": "218812xxxx699147",
    "authState": "auth_status_95279527xxxx00006",
    "referenceAgreementId": "2023072119074101xxxx30015599879"
  },
  "otpVerification": {
    "otpCode": "144339",
    "verifyRequestId": "ejZsTpWOeibDfWMjxxxxMLQfcy4MVmFd",
    "verifyType": "SMS_OTP"
  },
  "paymentFactor": {
    "isAuthorizationAndPay": "true",
    "isVerificationAndPay": "true"
  },
  "paymentMethod": {
    "paymentMethodType": "ALIPAY_HK"
  },
  "paymentRequestId": "2023072119074101xxxx30015599879",
  "pspId": "1022160000000000000"
}

The MPP returns a response to Alipay+.

copy
{
  "customerId": "216026110xxxx414",
  "paymentId": "202308071940108xxxx0160410263062940",
  "paymentTime": "2023-08-08T00:00:08+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

More information

For more information about how to handle the pay API request and return the response, see pay API.

(Optional) Step 5: Complete the authorization

If the user agrees to sign the authorization agreement when making the payment (paymentFactorisAuthorizationAndPay=true), the MPP needs to complete the authorization and return the authorization result with an access token by calling the authNotify API.

Processing logic

When calling the authNotify API, take the following things into consideration:

Ensure the following parameters are configured properly in the request:

authorizationNotifyType: As the notification is sent out to notify Alipay+ of the access token, the value must be set as TOKEN_CREATEDand the following parameter must be specified:

referenceAgreementId: The unique ID that is assigned by the auth client to identify an authorization.
accessToken: The token that is used to access the MPP user's resources.

Handle the response properly. Follow the instructions below to handle the result.

result.resultStatus	result.resultCode	Notification status	Actions
S	SUCCESS	Notification succeeds.	N/A
F	Multiple possible values exist, such as ACCESS_DENIED, KEY_NOT_FOUND, etc.	Notification fails.	Take actions according to the error message in result.resultCode. If the problem persists, contact connect_support@service.alipay.com.
U	Multiple possible values exist, such as UNKNOWN_EXCEPTION, REQUEST_TRAFFIC_EXCEED_LIMIT, etc.	Unknown	Unknown exception, which might be caused by network timeout. It is recommended that the MPP server retries the authNotify API request.
No result received		Unknown	It is recommended that the MPP server retry the authNotify API request.

Sample

The MPP sends a request to Alipay+.

copy
{
  "authorizationNotifyType":"TOKEN_CREATED",
  "authClientId": "218823863726123456789",
  "referenceMerchantId": "218823863726123456789",
  "referenceAgreementId": "667d730b56123456789",
  "accessToken": "281010033AB2F588D14B4323863726123456789",
  "accessTokenExpiryTime": "2022-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC123456789",
  "refreshTokenExpiryTime": "2022-06-08T12:12:12+08:00",
  "scopes": ["AGREEMENT_PAY"],
  "customerId":"2789808912345678912345671",
  "userLoginId":"62-***2736"
}

Alipay+ returns a response to the MPP.

copy
{
   "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
   },
  "acquirerId": "1021234567891230001",
  "pspId":"1021234567891230002"
}

More information

For more information about how to call the authNotify API request and handle the response, see authNotify.

Account binding via OTP

The following figure illustrates the workflow of how the user binds the account via OTP and then makes payment.

独立签约时序图.png

Figure 2: Workflow of account binding via OTP and making payment

For the authorization, the workflow of account binding via OTP consists of the following steps:

If a user selects a payment method for account binding, the merchant/ACQP sends an authorization request to Alipay+ (Steps 1-2).
Alipay+ obtains the user's MPP account and displays the authorization page to the user (Steps 3-4).
Alipay+ calls the prepare API to request the MPP to send an OTP to the user and apply for an authorization code. The MPP then sends the OTP to the user and returns the authorization code to Alipay+ (Steps 5-7).
The user confirms the authorization and inputs the OTP code (Step 8).
Alipay+ calls the applyToken API to request the MPP to verify the OTP and apply an access token with the authorization code and the OTP code (Step 9).
After the MPP verifies the OTP and completes the authorization, it returns the authorization result with an access token to Alipay+ (Steps 10-11).
Alipay+ redirects the user back to the merchant side and syncs the authorization result to the merchant/ACQP (Steps 12-13).
The merchant/ACQP renders the Authorization Result page and displays the authorization result to the user (Step 14).

For the subsequent payments after the user completes the authorization, the workflow consists of the following steps:

The user selects a payment method on the Cashier Page (Step 15).
The merchant/ACQP sends a payment request to Alipay+ with an access token obtained from Step 10 in the first-time authorization process (Step 16).
Alipay+ syncs the payment request to the MPP and receives the payment result (Steps 17-18).
The merchant/ACQP receives the payment result and displays the payment result to the user (Steps 19-20).

Step 1: Send OTP to the user

After the user confirms the MPP account to continue the authorization on the authorization page, Alipay+ calls the prepare API to request the MPP to send an OTP to the user and apply for an authorization code.

Processing logic

When handling the prepare API, take the following things into consideration:

Handle the request properly, especially the following parameters:

authorizationAction: The value of this parameter must be set as SMS, which indicates that the user completes the authorization on the merchant side by inputting the OTP code sent by the MPP through SMS.
userLoginId: The login ID that is used by the MPP user to log in to the MPP platform.
userLoginIdType: The type of method that the MPP user selects to log in to the MPP platform.

Ensure the following parameters are configured properly in the response:

verifyRequestId: The unique ID that is assigned by the MPP to identify an OTP. Alipay+ uses this parameter to check if the OTP that the user enters is correct.
authCode: The authorization code that is used by the auth client to get the access token.
result.resultStatus: If the MPP creates the authorization code successfully, set the value of result.resultStatus to S. If the MPP fails to create the authorization code, set the value of result.resultStatus to F. If the MPP fails to send the OTP code to users, set the value of result.resultStatus to U .

Sample

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "1022191000000000001",
  "authClientDisplayName": "TestClientName",
  "authClientId": "2191120xxxxx945",
  "authClientName": "TestClientName",
  "authRedirectUrl": "https://render.alipay.com/p/yuyan/180020010001207415/adaptor.html?accessType=back&callbackType=Common&terminalType=WAP&referenceAgreementId=2023080419031313007165909028316&authRequestId=2023080419091305000290006672000&pspId=1022160000000000000&clientId=4GGO000000000001",
  "authState": "amsdemo_sdkSign_authState_lijun_blj_20230804_190329_120",
  "authorizationAction": "SMS",
  "customerBelongsTo": "ALIPAY_HK",
  "osType": "IOS",
  "pspId": "1022160000000000000",
  "referenceAgreementId": "202308041903131xxxxx909028316",
  "referenceMerchantId": "2191120xxxxx945",
  "scopes": ["AGREEMENT_PAY"],
  "terminalType": "WAP",
  "userLoginId": "852-940xx811",
  "userLoginIdType": "MOBILE"
}

The MPP returns a response to Alipay+.

copy
{
  "authCode": "281004132USSO1WaRTVlxxxxxAlk029",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "verifyRequestId": "fUWZ5RCp6FN01VIxxxxxXSbn6YcxNj5x"
}

More information

For more information about how to handle the prepare API request and return the response, see prepare API.

Step 2: Verify OTP and complete the authorization

After the user confirms the authorization and enters the OTP code, Alipay+ calls the applyToken API to request the MPP to verify the OTP and apply the access token with the authorization code and the OTP code.

Processing logic

When handling the applyToken API, take the following things into consideration:

Handle the request properly, especially the following parameters:

grantType: The value of this parameter must be set as VERIFICATION_CODE, which indicates that the auth client uses the verification code (otpVerification.otpCode) and the authorization code (authCode) together to get an access token.
authCode: The authorization code that is used by the auth client to get the access token.
otpVerification: The information about the One-Time Password (OTP) verification.
otpVerification.otpCode: The OTP code that is used by the auth client to get the access token.
otpVerification.verifyRequestId: The unique ID that is assigned by the MPP to identify an OTP.

Ensure the following parameters are configured properly in the response:

result.resultStatus: If the MPP creates the access token successfully, set the value of result.resultStatus to S. If the MPP fails to create the access token, set the value of result.resultStatus to F. If the OTP verification fails, set the value of result.resultStatus to U with the error code OTP_VERIFICATION_FAILED.

Sample

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "1022191000000000001",
  "authClientId": "219112xxxx39945",
  "authCode": "281004132USSO1WaxxxxsdIsKAlk029",
  "grantType": "VERIFICATION_CODE",
  "otpVerification": {
    "otpCode": "362773",
    "verifyRequestId": "fUWZ5RCp6FN01VIxxxxXSbn6YcxNj5x"
  },
  "pspId": "1022160000000000000"
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35",
  "accessTokenExpiryTime": "2022-06-06T12:12:12+08:00",
  "refreshToken": "2810100334F62CBC577F468AAC87CFC6C9107811",
  "refreshTokenExpiryTime": "2022-06-08T12:12:12+08:00",
  "customerId":"2789808900000000000000001",
  "userLoginId":"62-***2736"
}

More information

For more information about how to handle the applyToken API request and return the response, see applyToken API.