Alipay+ DocsAlipay+ Docs

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 Mobile Payment Provider (MPP) needs to take the following steps:

Easy Pay workflow

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

Easy Pay for DANA.png

Figure 1: Workflow of making a payment

The payment process consists of the following steps:

  1. After placing an order, the user chooses a payment method. The merchant/ACQP then sends a payment request to Alipay+ (Steps 1-2).
  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).
  3. 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).
  4. Alipay+ calls the pay API again to request the MPP to create a payment order and notifies the MPP of whether the user enables the one-click payment (Steps 7-8).
  5. (Optional) If the user enables the one-click payment, the MPP starts the authorization process (Step 9).
  6. The MPP returns the verification page URL to Alipay+, which then renders the verification page to the user (Steps 10-11).
  7. After the user enters the verification code to proceed with the payment, the MPP verifies it and then redirects the user to the Alipay+ payment result page. The redirection URL contains information about whether the verification succeeds (Steps 12-15).
  8. (Optional) Alipay+ calls the inquiryPayment API to inquire about the payment result. The MPP returns the payment result to Alipay+, which then syncs the payment result to the merchant/ACQP. At the same time, the MPP calls the notifyPayment API to notify Alipay+ of the payment result, which is then synced to the merchant/ACQP (Steps 16-23).
  9. (Optional) If the value of paymentFactorisAuthorizationAndPay is true, which means the user enables the one-click payment, 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 (Steps 24-26).

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.isEasyPayScenario: 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.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": "SG"
            },
            "merchantDisplayName": "testAliasName",
            "merchantMCC": "5021",
            "merchantName": "testAliasName",
            "referenceMerchantId": "2188120040699147"
        },
        "orderAmount":
        {
            "currency": "IDR",
            "value": "50"
        },
        "orderDescription": "c05c200e-ba24-40bc-a009-a29974bf7f7b",
        "referenceOrderId": "c05c200e-ba24-40bc-a009-a29974bf7f7b"
    },
    "payToAmount":
    {
        "currency": "IDR",
        "value": "50"
    },
    "paymentAmount":
    {
        "currency": "IDR",
        "value": "50"
    },
    "paymentFactor":
    {
        "isAgreementPayment": "true",
        "isEasyPayScenario": "true",
        "isPaymentEvaluation": "true"
    },
    "paymentMethod":
    {
        "paymentMethodId": "",
        "paymentMethodMetaData":
        {
            "userLoginId": "852-95303585",
            "userLoginIdType": "MOBILE"
        },
        "paymentMethodType": "ALIPAY_HK"
    },
    "paymentRequestId": "2023091819074101000930025674948",
    "pspId": "1022160000000000000"
}

The MPP returns a response to Alipay+.

copy
{
    "paymentRequestId": "2023090419074101000770023468830",
    "pspId": "1022160000000000000",
    "customerId": "2160220037535020",
    "payToAmount": {
        "currency": "HKD",
        "value": "50"
    },
    "acquirerId": "1022188000000000001",
    "paymentAmount": {
        "currency": "HKD",
        "value": "50"
    },
    "resultInfo": {
        "resultCodeId": "IPAY_RS_100000200",
        "resultMsg": "success"
    }
}

More information

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

Step 2: Create a payment order

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 notifies the MPP of whether the user enables the one-click payment.

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: The value of this parameter must be set as true.
    • 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.
    • paymentFactor.isAuthorizationAndPay: If the use enables the one-click payment, the value of this parameter must be set as true and the following parameters must be specified:
      • authorizationInfo.referenceAgreementId: The unique ID that is assigned by the auth client to identify an authorization.
      • authorizationInfo.authClientId: The unique ID that is assigned by the ACQP to identify an auth client, which is usually the merchant.
      • authorizationInfo.authState: The authorization statement that is generated by the auth client.
  • Ensure the following parameters are configured properly in the response:
    • paymentUrl: The URL where the user is redirected to complete the verification.
    • paymentId: The unique ID that is assigned by the MPP to identify a payment.
    • result.resultStatus: This parameter indicates the payment result status. In this step, the value of this parameter can not be S because the payment can not be successful before the MPP completes the verification. If the MPP detects certain risks and needs to implement verification, set the value of result.resultStatus to U. If the MPP rejects the verification, set the value of result.resultStatus to F.

Sample

Alipay+ sends a request to the MPP.

copy
{
    "acquirerId": "1022188000000000001",
    "extendInfo": "{\"acqToMerchantSettleFxMode\":\"NON_LOCKING\",\"fxRateBizScene\":\"COMMON_QUOTE\",\"settleContractId\":\"2022050219046000100142100082205\",\"merchantSettlementArea\":\"HK\",\"isLocalSettlement\":false,\"acqSiteMerchantInfo\":{\"merchantId\":\"2188120040699147\",\"merchantName\":\"testAliasName\"},\"fxPdCode\":\"Merchant_Live_KA\",\"settleProductCode\":\"MC400300000000000036\"}",
    "order":
    {
        "env":
        {},
        "merchant":
        {
            "merchantAddress":
            {
                "region": "SG"
            },
            "merchantDisplayName": "testAliasName",
            "merchantMCC": "5021",
            "merchantName": "testAliasName",
            "referenceMerchantId": "2188120040699147"
        },
        "orderAmount":
        {
            "currency": "IDR",
            "value": "50"
        },
        "orderDescription": "AMSDM_GIFT",
        "referenceOrderId": "amsdmorder_wuyunkun_wyk_20230918_093653_794"
    },
    "passThroughInfo": "{\"buyerId\":\"wuyunkun.wyk\",\"gaid\":\"\",\"merchantTerminalType\":\"android\",\"pinRedirectUrl\":\"https://ac.alipay.com/page/antom-web-checkout/src/component-app/doubleFA/index.html?paymentSessionData=n5xHy7LlExD8%2BaNKekkKwPm%2FotYQ3UjTXDoh5tlj4R8QajYr0lNjqv%2B%2FOkMs4QLvfHFwC9QkDRio2sX34SSATg%3D%3D%26%26SG%26%26188&ps=EASY_PAY&pmct=WALLET&psv=2.0&app=app&en_US=en_US\",\"renderGroup\":\"h5\",\"securityCode\":\"****************************************************************\"}",
    "payToAmount":
    {
        "currency": "IDR",
        "value": "50"
    },
    "paymentAmount":
    {
        "currency": "IDR",
        "value": "50"
    },
    "paymentExpiryTime": "2023-09-18T09:47:51+08:00",
    "authorizationInfo":
    {
        "authClientId": "2188120040699147",
        "authState": "authStatus_0918001002",
        "referenceAgreementId": "2023091819074101000380025683717"
    },
    "paymentFactor":
    {
        "isAgreementPayment": "true",
        "isAuthorizationAndPay": "true",
        "isEasyPayScenario": "true"
    },
    "paymentMethod":
    {
        "paymentMethodMetaData":
        {
            "userLoginId": "852-95303585",
            "userLoginIdType": "MOBILE"
        },
        "paymentMethodType": "ALIPAY_HK"
    },
    "paymentRequestId": "2023091819074101000380025683717",
    "pspId": "1022160000000000000",
    "paymentRedirectUrl":"https://ac.alipay.com/page/antom-web-checkout/src/component-app/doubleFA/index.html?paymentSessionData=n5xHy7LlExD8%2BaNKekkKwPm%2FotYQ3UjTXDoh5tlj4R8QajYr0lNjqv%2B%2FOkMs4QLvfHFwC9QkDRio2sX34SSATg%3D%3D%26%26SG%26%26188&ps=EASY_PAY&pmct=WALLET&psv=2.0&app=app&en_US=en_US"
}

The MPP returns a response to Alipay+.

copy
{
        "customerId": "217010000018847072594",
        "paymentUrl": "http://render-dev.site.alipay.net/p/s_dev/imobileicprod-S29001199025/#/mic/entry?verifyId=b7cd4bc3de4f494b0ac29b3bdbc73523_out_sg_site&domain=http://ifcidentitycloudsg.test.alipay.net&lan=hk&productCode=PAYMENT_PASSWORD",
        "paymentId": "201000000000000000000000004444",
        "result": {
            "resultCode": "PAYMENT_IN_PROCESS",
            "resultMessage": "payment in process",
            "resultStatus": "u"
        }
    }

More information

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

Step 3: Complete verification and proceed with the payment

After receiving the verification page URL from the MPP, Alipay+ redirects the user to that page where the user enters the verification code. The MPP has the flexibility to select the type of verification, which can be a Personal Identification Number (PIN), a Short Message Service (SMS), or a combination of both. In case the user does not receive an SMS verification code or the code expires, the MPP must support resending a new SMS to ensure that the user can proceed with the payment.

After the user completes the verification process, the MPP needs to update the payment status and redirect the user to the Alipay+ payment result page. The redirection URL must contain the verification status, which must be specified as success or fail. For example:

https://ac.alipay.com/page/antom-web-checkout/src/component-app/doubleFA/index.html?paymentSessionData=n5xHy7LlExD8%2BaNKekkKwPm%2FotYQ3UjTXDoh5tlj4R8QajYr0lNjqv%2B%2FOkMs4QLvfHFwC9QkDRio2sX34SSATg%3D%3D%26%26SG%26%26188&ps=EASY_PAY&pmct=WALLET&psv=2.0&app=app&en_US=en_US&status=success

(Optional) Step 4: Return the payment result

If Alipay+ does not receive the final payment result (success or failure) from the pay API, the MPP can return the payment result in the following ways:

  • The MPP responds to the inquiryPayment API request that is initiated by Alipay+ every 10 seconds. The request can be initiated up to 12 times. For more information, see Respond to payment inquiry.
  • After the payment reaches the final status, the MPP calls the notifyPayment API to notify Alipay+ of the payment result. For more information, see Notify payment result.

(Optional) Step 5: Complete the authorization

If the user enables the one-click 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
  {
      "accessToken": "2816660352710421693892531000ZCl8FEuhWe4Tcu000369",
      "accessTokenExpiryTime": "2033-09-02T13:41:58+08:00",
      "acquirerId": "A071234000000000",
      "customerId": "210220900020803427367",
      "pspId": "1022166000000000001",
      "refreshToken": "28166603eC8gWOrn6DEuh6UCjNUqwzXG70ZqiCJqf7001369",
      "refreshTokenExpiryTime": "2033-09-02T13:41:58+08:00",
      "result": {
          "resultCode": "SUCCESS",
          "resultMessage": "Success",
          "resultStatus": "S"
      },
      "userLoginId": "62-857****6473",
      "walletForAccountBinding": {
          "walletBrandName": "DANA",
          "walletLogo": {
              "logoName": "DANA",
              "logoUrl": "https://gw.alipay.com/icon/medium/default/DANA.svg"
          },
          "walletName": "DANA",
          "walletRegion": "ID"
      }
  }

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 the authNotify API.

Learn more about

Home
Get Support
Need more help?