Alipay+Alipay+

Payment processing

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.

Workflow

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

Payment.png

Figure 1. The payment processing workflow of Auto Debit

Acquiring Partner actions

After receiving the payment request from the merchant, the Acquiring Partner needs to call the pay interface from Alipay+ to process the payment. When Alipay+ returns the response of the pay request, the Acquiring Partner needs to handle the payment result and return it to the merchant.

1. Initiate a payment request

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 Acquiring Partner then uses the access token to assemble a request to call the pay interface.

Processing logic

  • The following list provides the key information that the Acquiring Partner needs to take into consideration when configuring the request parameters of the pay interface:
    • 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 accout binding process.
    • paymentFactor.isAgreementPayment: the value of this parameter must be set to true.
    • 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 uniqure ID that is assigned by the payment initiator to identify an order payment.
  • The following table lists the different results that the Acquiring Partner might receive from Alipay+.

result.resultStatus

result.resultCode

Actions

S

SUCCESS

Payment succeeds, which means the money is deducted from the user. Update the status from merchant side.

F

...

Payment fails. Take actions according to the error message in result.resultCode.

U

...

Payment in processing. Call the inquiryPayment interface to inquire the payment result. The inquiry request can be sent 10 to 20 times within 60 seconds.

No result received

Sample

The Acquiring Partner sends a request to Alipay+.

copy
{
  "order":{
    "referenceOrderId":"OrderID_010101****",
    "orderDescription":"SHOES",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    },
       "merchant":{
          "referenceMerchantId":"M0000000****",
          "merchantMCC":"1405",
          "merchantName":"UGG",
          "merchantAddress":{
             "region":"JP",
             "city":"xxx"
          }
       }
 }, 
 "paymentRequestId":"201811291907410100070000001****",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentMethod":{
       "paymentMethodType": "CONNECT_WALLET",
       "paymentMethodId": "281006050000000000125733DAHJ****"
  },
 "paymentFactor": {
      "isAgreementPayment":"true"
 } 
}

Alipay+ returns a response to the Acquiring Partner.

copy
{
    "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": "20881221121****",
  "pspId":"10220880000000****",
  "walletBrandName": "walletName",
  "settlementAmount": {
    "currency": "JPY",
    "value": "100"
  }
}

More information

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

2. Handle the payment result

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

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

Note:

  • It is required for the Acquiring Partner to support all three methods so that the Acquiring Partner 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 interface and the result from the inquiryPayment interface might be in the intermediate state. To get the final state of the payment, the Acquiring Partner 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 Acquiring Partner might encounter in the three ways.

PaymentResult.png

Figure 2. Combinations of different kinds of results

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

paymentResult.resultStatus

paymentResult.resultCode

Actions

S

SUCCESS

The payment succeeds. The Acquiring Partner can proceed with the order as a successful payment.

F

...

The payment fails. The Acquiring Partner needs to take further actions according to the error message returned in the paymentResult.resultCode parameter.

U

...

The payment is still in processing. The Acquiring Partner needs to keep the polling of inquryPayment until the payment result (paymentResult.resultStatus) in the inquriyPayment response is F or S

.

Note:

  • The polling of inquiryPayment must be performed with an interval of 3 seconds in 60 seconds.
  • After 60 seconds, if the value of paymentResult.resultStatus is still U. The Acquiring Partner needs to use the cancelPayment interface to cancel the order.
  • Only after the order is canceled at the Alipay+ side, the Acquiring Partner can mark the payment as failed.

No results received

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

  • After the Acquiring Partner successfully handles the notification request, the Acquiring Partner 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 Acquiring Partner is not S. For how to handle the notification, check the following things:
    • Refer to Handle 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 Acquiring Partner might receive in the notifyPayment request that is sent by Alipay+.

paymentResult.resultStatus

paymentResult.resultCode

Actions

S

SUCCESS

The payment succeeds. The Acquiring Partner needs to verify the values of the paymentRequestId and paymentAmount parameters are consistent with the payment information that is stored at the Acquiring Partner side.

F

...

The payment fails. The Acquiring Partner needs to refer to the paymentResult.resultCode parameter to decide the further processing logic at the Acquiring Partner side.