# Accept a payment

> To proceed with Auto Debit, a merchant must prompt the user to link a wallet account with the merchant account.

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 Service Provider (ACQP) needs to complete the following steps:

-   [Step 1. Initiate a payment](#hEmGa)
-   [Step 2. Handle the payment result](#FBJZn)

# Workflow

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

![image.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1755740654271-d92c0f73-83a9-4250-a977-f80a2a97f9a8.png)

Figure 1. The payment processing workflow of Auto Debit

The payment process consists of the following steps:

1.  The merchant assembles a payment request using the access token obtained during account binding and initiates a payment to the ACQP. The ACQP then 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 requests the ACQP to inquire about the payment result. The ACQP then initiates an **inquiryPayment** API request to obtain the payment result from Alipay+. This step repeats until a payment result returns. (Steps 7-10)
4.  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 11-12)


# Step 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 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](https://www.iso.org/iso-4217-currency-codes.html) 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`.
-   _paymentExpiryTime_: the expiration time expected for this payment. Normally, the Auto Debit payment can be processed, and the 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+.

| **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` | `ORDER_IS_CLOSED` | Payment fails. - If a transaction is not completed at the MPP side after the payment expires, Alipay+ closes the order and returns `ORDER_IS_CLOSED`. - If a transaction is completed, but you receive the error code `ORDER_IS_CLOSED`, take `ORDER_IS_CLOSED` as the final result. |
| `F` | Values other than `ORDER_IS_CLOSED`, such as `ACCESS_DENIED` and `BUSINESS_NOT_SUPPORT`. | Payment fails. Take actions according to the error message in _result.resultCode._ |
| `U` | `PAYMENT_IN_PROCESS` | Payment in processing. Call the **inquiryPayment** API to inquire the payment result. The inquiry request can be sent 10 to 20 times within 60 seconds. |
| `U` | Values other than `PAYMENT_IN_PROCESS` | Retry the same request. Ensure that the value specified on the _paymentRequestId_ parameter is the same as the one specified in the previous request. |
| No result received | No result received | Retry the same request. Ensure that the value specified on the _paymentRequestId_ parameter is the same as the one specified in the previous request. |

## Sample

The ACQP sends a request to Alipay+.

```json
{
   "paymentNotifyUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automation/paymentNotify.htm",
  "order":{
    "referenceOrderId":"OrderID_010101****",
    "orderDescription":"SHOES",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    },
    "env": {
            "terminalType": "APP",
            "osType": "IOS"
        },
        "buyer": {
            "referenceBuyerId": "907410100070010000"
        },
       "merchant":{
          "referenceMerchantId":"M0000000****",
          "merchantMCC":"1405",
          "merchantName":"UGG",
          "merchantAddress":{
             "region":"JP",
             "city":"xxx"
          }
       }
 },
 "paymentRequestId":"201811291907410100070000001****",
 "settlementStrategy": {
        "settlementCurrency": "JPY"
    },
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentMethod":{
       "paymentMethodType": "CONNECT_WALLET",
       "paymentMethodId": "281006050000000000125733DAHJ****"
  },
 "paymentFactor": {
      "presentmentMode": "TILE",
      "isAgreementPayment":"true"
 }
}
```

Alipay+ returns a response to the ACQP.

```json
{
    "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** API (such as the field description and format), see the [**pay**](../api_acq_tile/pay_auto_debit) API.

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

![image.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1755741158965-3b20da4b-e7eb-4cc8-9b20-cedc3db1a2d5.png)

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](#mQ2Uv) in Step 1.
-   The following table lists the different results that the ACQP might receive from Alipay+ when calling the **inquiryPayment** API.

You might receive different results from Alipay+. Follow the instructions below to handle the result.

| **result.resultStatus** | **paymentResult.resultStatus** | **Payment status** | **Actions** |
| --- | --- | --- | --- |
| `S` | `S` | Payment succeeds. | Update the status from your server side. |
| `S` | `F` | If _paymentResult.resultCode_ is `ORDER_IS_CLOSED`, the payment order is closed or canceled; otherwise, the payment fails. | Take actions according to the payment result code (specified on the _paymentResult.resultCode_ parameter). For more information, see the Result codes section below. |
| `S` | `U` | Payment is in processing. | Keep inquiring within the payment expiry time. For more information about inquiry rules for different products, see the Payment result inquiry rules section below. If you still receive the same payment result of `U` after the payment expires or after your inquiry times exceed the maximum limit, call the **cancelPayment** API to cancel the payment. |
| `F` | `F` | The payment fails or the payment order does not exist. | - For cases where the payment fails, take actions according to the payment result code (specified on the _paymentResult.resultCode_ parameter) or contact the technical support team at [connect\_support@service.alipay.com](mailto:connect_support@service.alipay.com). - For cases where the payment order does not exist, the reason might be: - The payment order ID is incorrect. Use the correct payment order ID to perform inquiries. - The payment order is not created in the Alipay+ system yet. Keep inquiring within the payment expiry time. For more information about inquiry rules for different products, see the Payment result inquiry rules section below. If you still receive the same payment result of `U` after the payment expires or after your inquiry times exceed the maximum limit, call the **cancelPayment** API to cancel the payment. |
| `U` | `U` | Unknown exception | Keep inquiring within the payment expiry time. For more information about inquiry rules for different products, see the Payment result inquiry rules section below. If you still receive the same payment result of `U` after the payment expires or after your inquiry times exceed the maximum limit, call the **cancelPayment** API to cancel the payment. |
| No result received | No result received | Unknown | Keep inquiring within the payment expiry time. For more information about inquiry rules for different products, see the Payment result inquiry rules section below. If you still receive no payment result after the payment expires or after your inquiry times exceed the maximum limit, call the **cancelPayment** API to cancel the payment. |

For more information about how to use the **inquiryPayment** API (such as the field description and format), see the [**inquiryPayment**](../api_acq_tile/inquiry_payment) API.

-   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 notification](handle_notification#JBiu1) 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+.

| **paymentResult.resultStatus** | **paymentResult.resultCode** | **Actions** |
| --- | --- | --- |
| `S` | `SUCCESS` | The payment succeeds. The ACQP needs to verify the values of the _paymentRequestId_ and _paymentAmount_ parameters are consistent with the payment information that is stored at the ACQP side. |
| `F` | ... | The payment fails. The ACQP needs to refer to the _paymentResult.resultCode_ parameter to decide the further processing logic at the ACQP side. |