Accept a payment

After the account binding process is completed, the merchant can initiate a payment with the access token that is retrieved during the account binding process, without involving any further user interactions.

To accept the payment in this scenario, the Acquiring Partner (ACQP) needs to complete the following steps:

• Step 1. Initiate a payment
• Step 2. Handle the payment result

Workflow

The following figure illustrates the workflow of how to initiate and process a payment.

Figure 1. The payment processing workflow of Auto Debit

The payment process consists of the following steps:

1. The merchant assembles a payment request with the access token that is obtained during account binding and initiates a payment to the ACQP, which calls the pay API with the access token to initiate a payment to Alipay+ (Steps 1-3).
2. Alipay+ processes the payment and returns the payment result to the ACQP, which syncs the payment result to the merchant (Steps 4-6).
3. The merchant calls the ACQP to inquire about the payment result. The ACQP then initiates inquiryPayment API requests to obtain the payment result from Alipay+. At the same time, Alipay+ calls the notifyPayment API to notify the ACQP of the payment result, which is then synced to the merchant (Steps 7-12).

Step 1. Initiate a payment

After the account binding process is completed, the merchant as the auth client, obtains the user authorization (the access token). Then the merchant can initiate a payment request according to the business scenario, which can be an individual payment request or one of the subscription payment requests. The ACQP then uses the access token to assemble a request to call the pay API.

Processing logic

• The following list provides the key information that the ACQP needs to take into consideration when configuring the request parameters of the pay API:

• paymentAmount.currency: specifies the transaction currency.
• paymentAmount.value: the value of this parameter must be in the smallest currency unit. For example, when the currency is HKD, $5.99 must be specified as 599. When the currency is JPY, ￥599 must be specified as 599. Check ISO 4217 Currency Code for more details.
• paymentMethod.paymentMethodType: the value of this parameter must be set to CONNECT_WALLET.
• paymentMethod.paymentMethodId: specifies the value of the accessToken parameter that is obtained in the account binding process.
• paymentFactor.isAgreementPayment: the value of this parameter must be set to true.
• paymentFactor.presentmentMode: the value of this parameter must be set to UNIFIED.
• paymentExpiryTime: the expiration time expected for this payment. Normally, the Auto Debit payment can be processed and results can return synchronously in a very short time. However, when some issues (such as network timeout) occur, the payment will be closed by Alipay+ when the time reaches the expiration time. By default, the expiration time is 1 minute.
• paymentRequestId: must be a unique ID that is assigned by the payment initiator to identify an order payment.

• The following table lists the different results that the ACQP might receive from Alipay+.

Sample

The ACQP sends a request to Alipay+.

{
    "paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
    "paymentRequestId": "pay_1089760038715669_102775745075669",
    "paymentFactor": {
        "isAgreementPayment": "true",
        "presentmentMode": "UNIFIED"
    },
    "order": {
        "referenceOrderId": "102775745075669",
        "orderDescription": "SHOES",
        "orderAmount": {
            "currency": "JPY",
            "value": "100"
        },
        "merchant": {
            "referenceMerchantId": "M0000000001",
            "merchantName": "UGG",
            "merchantMCC": "5411",
            "merchantAddress": {
                "region": "JP",
                "city": "xxx"
            }
        },
        "env": {
            "terminalType": "APP",
            "osType": "IOS"
        },
        "buyer": {
            "referenceBuyerId": "907410100070010000"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "JPY"
    },
    "paymentAmount": {
        "currency": "JPY",
        "value": "100"
    },
    "paymentMethod": {
        "paymentMethodType": "CONNECT_WALLET",
        "paymentMethodId": "ALIPAY20210521s5yWq9NvmJDFb9l8TLFFvgbum3Mp9rWET39h0QXxlRM0881307330994"
    }
}

Alipay+ returns a response to the ACQP.

{
    "acquirerId": "2021228100000000",
    "result": {
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultStatus": "U",
        "resultMessage": "The payment in process."
    },
    "paymentId": "20190608114010800100188820200355883",
    "paymentAmount": {
        "value": "100",
        "currency": "JPY"
    },
    "paymentTime": "2021-04-08T14:48:50+08:00",
    "customerId": "208812211210000",
    "pspId": "102208800000000000",
    "walletBrandName": "walletName",
    "settlementAmount": {
        "currency": "JPY",
        "value": "100"
    }
}

More information

For more information about how to use the pay API (such as the field description and format), see pay.

Step 2. Handle the payment result

For a payment request, the following three methods are provided for the ACQP to retrieve the payment result:

• from the synchronous response of the pay API.
• use the inquiryPayment API to inquire about the payment result.
• from the payment notification that Alipay+ asynchronously sends to the ACQP by using the notifyPayment API.

Note:

• It is required for the ACQP to support all three methods so that the ACQP can really obtain the payment result.
• The results from the three ways might be inconsistent because the result from the synchronous response of the pay API and the result from the inquiryPayment API might be in the intermediate state. To get the final state of the payment, the ACQP needs to keep retrying the inquiryPayment API call or wait for Alipay+ to send the notifyPayment request.

The following diagram illustrates all the possible combinations of the results that the ACQP might encounter in the three ways.

Figure 2. Combinations of different kinds of results

• For how to handle the result that is returned in the response of the pay API, see Processing logic in Step 1.
• The following table lists the different results that the ACQP might receive from Alipay+ when calling the inquiryPayment API.

For more information about how to use the inquiryPayment API (such as the field description and format), see inquiryPayment.

• After the ACQP successfully handles the notification request, the ACQP needs to return a response to Alipay+. Alipay+ provides a notification retry mechanism if the result.resultCode parameter in the notification response returned from the ACQP is not S. For how to handle the notification, check the following things:

• Refer to Handle a notification to find out the common things that you need to do and consider.
• Refer to the table below to deal with the different payment results that the ACQP might receive in the notifyPayment request that is sent by Alipay+.