Integration guide

To help the user complete a tax refund with the Alipay+ Mini Program deployed in your app, you (the MPP) must take the following steps to build the integration with the APIs provided by Alipay+:

Before you begin

Before you learn more about how to integrate with Alipay+ Tax Refund, ensure that you are familiar with the user experience and product functionalities that Alipay+ Tax Refund can provide to consumers. See Alipay+ Tax Refund introduction for details.

Workflow

The following figure illustrates the tax refund workflow:

Figure 1. Tax refund workflow

The tax refund workflow contains the following steps:

After the user launches the Alipay+ Mini Program in your app, the Alipay+ Mini Program calls Alipay+ to evaluate whether the user's MPP account supports an Original Credit Transaction (OCT) and generate a tax refund code (Step 1).
Alipay+ calls the evaluateOriginalCredit API to forward the evaluation request to the MPP, which performs the evaluation and returns the evaluation result to Alipay+ (Steps 2-4).

If the evaluation succeeds, Alipay+ generates a tax refund code and returns it to the Alipay+ Mini Program (Steps 5-6).
If the evaluation fails, Alipay+ notifies the Alipay+ Mini Program of the failure. Skip the following steps (Step 7).

After scanning the tax refund code displayed in the Alipay+ Mini Program, the merchant/Acquiring Service Provider (ACQP) sends a request to Alipay+ to evaluate whether the user's MPP account supports the OCT and the refund amount can be credited to the MPP account. (Steps 8-9)
Alipay+ calls the evaluateOriginalCredit API to forward the evaluation request to the MPP (Step 10).
The MPP performs the evaluation and returns the evaluation result to Alipay+. The evaluation result includes the user ID at the MPP platform and the amount of funds that Alipay+ requests to transfer to the MPP. Alipay+ then forwards the evaluation result to the merchant/ACQP (Steps 11-13).
The merchant/ACQP prompts the user to confirm the estimated refund amount and then initiates an OCT request with the user ID to Alipay+, which then calls the createOriginalCredit API to request the MPP to create an OCT (Steps 14-15).
The MPP processes the OCT and returns the OCT result to Alipay+, which then forwards the result to the merchant/ACQP (Steps 16-18).
If the value of the result.resultCode parameter in the createOriginalCredit API response is ORIGINAL_CREDIT_IN_PROCESS, Alipay+ calls the inquireOriqinalCredit API to inquire about the OCT result. The MPP processes the inquiry and returns the inquiry and OCT results to Alipay+ (Steps 19-21).
If the MPP has integrated the notifyOriginalCredit API, the MPP asynchronously notifies Alipay+ of the OCT result, which is then returned to the merchant/ACQP (Steps 22-25).
If the ACQP proactively calls Alipay+ to confirm the success of the OCT, Alipay+ returns OCT success to the ACQP and then calls the confirmOriginalCredit API to push the OCT status to success at the MPP side. The MPP needs to ensure that the tax refund is successfully processed and return the confirmation result to Alipay+ (Steps 26-30).
If the ACQP does not call Alipay+ to confirm the success of the OCT but the value of the originalCreditResult.resultStatus parameter is still U after Alipay+ polls the inquireOriginalCredit API for 1 minute, Alipay+ calls the confirmOriginalCredit API to push the OCT status to success at the MPP side. The MPP needs to ensure that the tax refund is successfully processed and return the confirmation result to Alipay+ (Steps 31-33).

Step 1. Obtain a tax refund code

After the user launches the Alipay+ Mini Program in your app for tax refund, the Alipay+ Mini Program needs to obtain a tax refund code that is unique per user from Alipay+. To do so, the Alipay+ Mini Program calls Alipay+ to evaluate whether the user's MPP account supports an OCT.

Note: Before calling Alipay+ to perform OCT evaluation, the Alipay+ Mini Progam needs to obtain the user ID at the MPP platform. For more information, see Obtain user information.

After receiving the OCT evaluation request from the Alipay+ Mini Program, Alipay+ calls the evaluateOriginalCredit API to request the MPP to evaluate whether the user's MPP account supports the OCT.

If the evaluation succeeds, Alipay+ generates a tax refund code and returns it to the Alipay+ Mini Program, which then renders the tax refund code for scanning.
If the evaluation fails, Alipay+ notifies the Alipay+ Mini Program of the failure. Skip the following steps.

Processing logic

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

Handle the request properly, especially the following parameters:

evaluationType: indicates based on which you need to perform the evaluation. In the tax refund scenario, the value is set to BY_USER_ID, which indicates that you need to perform the evaluation based on the user’s ID at your side.
payeeMethod: indicates the payment method that is used by the user to receive the fund.

payeeMethod.paymentMethodType: indicates the type of the payment method.
payeeMethod.paymentMethodId: indicates the ID of the payment method. In the tax refund scenario, the value is set to the user's ID at your side.

payeeAmount.value: indicates the amount of funds that Alipay+ requests to transfer to the MPP. In this step, the value is set to 0.
acquirerId: In this step, the value is fixed as 2052666000000000, which represents Alipay+.

Ensure the result.resultStatus parameter is configured properly in the response:

If the evaluation succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS, and return payee to Alipay+.
If the evaluation fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly.
If the evaluation is in unknown status, set the value of result.resultStatus to U and the value of result.resultCode accordingly.

Samples

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "2052666000000000",
  "pspId": "10221XXXX0000000000",
  "payeeAmount": {
    "value": "0",
    "currency": "HKD"
  },
  "evaluationType": "BY_USER_ID",
  "payeeMethod": {
    "paymentMethodType": "ALIPAY_HK",
    "paymentMethodId": "28100602000000000000"
  }
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "payee": {
    "userId": "2088245U41144145",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 2. Evaluate user's account with refund amount

After scanning the tax refund code rendered in the Alipay+ Mini Program, the merchant/ACQP initiates an OCT evaluation request with the refund amount to Alipay+, which then calls the evaluateOriginalCredit API to request the MPP to evaluate whether the user's MPP account supports the OCT and the refund amount can be credited to the MPP account.

Processing logic

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

Handle the request properly, especially the following parameters:

evaluationType: indicates based on which you need to perform the evaluation. In the tax refund scenario, the value is set to BY_USER_ID, which indicates that you need to perform the evaluation based on the user’s ID at your side.
payeeMethod: indicates the payment method that is used by the user to receive the fund.

payeeMethod.paymentMethodType: indicates the type of the payment method.
payeeMethod.paymentMethodId: indicates the ID of the payment method. In the tax refund scenario, the value is set to the user's ID at your side.

Ensure the result.resultStatus parameter is configured properly in the response:

If the evaluation succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS, and return payee to Alipay+.
If the evaluation fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly.
If the evaluation is in unknown status, set the value of result.resultStatus to U and the value of result.resultCode accordingly.

Samples

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "evaluationType": "BY_USER_ID",
  "payeeMethod": {
    "paymentMethodType": "ALIPAY_HK",
    "paymentMethodId": "28100602000000000000"
  }
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "payee": {
    "userId": "2088245U41144145",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 3. Create an OCT

After the user confirms the estimated refund amount, the merchant/ACQP initiates an OCT to Alipay+. Alipay+ then calls the createOriginalCredit API to request the MPP to create an OCT.

Processing logic

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

Handle the request properly, especially the following parameters:

payeeAmount: indicates the amount of funds that Alipay+ requests to transfer to the MPP. For the same OCT, Alipay+ specifies the same value for this parameter in the evaluateOriginalCredit and createOriginalCredit API requests.
initialOriginalCreditId: indicates the unique ID that is assigned by the ACQP to identify an OCT.

Ensure the result.resultStatus parameter is configured properly in the response:

If the OCT succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS, and return originalCreditId to Alipay+.
If the OCT fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly.
If the OCT is in unknown status, set the value of result.resultStatus to U and the value of result.resultCode accordingly.

Samples

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "sceneType":"TAX_REFUND",
  "subSceneType":"PORT_INSTANT_TAX_REFUND",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "initialOriginalCreditId": "gb_tax_1089760038715669_102775745070000",
  "payeeAmount": {
    "currency": "HKD",
    "value": "1000"
  },
  "payee": {
    "userId": "2088245U41144145"
  }
  "payer": {
    "referenceMerchantId": "2188245U41144145",
    "merchantAddress": {
      "region":"DE"
    },
    "merchantName": "Global Blue",
    "merchantMCC": "5411"
  },
  "env": {
    "clientIp": "1.1.1.1",
    "storeTerminalId": "122222",
    "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
  },
  "memo":"tax refund"
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00",
  "originalCreditId": "hk_tax_1089760038715669_102775745070000",
  "payee": {
    "userId": "28100602000000000000",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 4. Return the OCT result

After handling the createOriginalCredit API request, the MPP can also return the OCT result by using the following ways:

by handling the inquireOriginalCredit API request sent by Alipay+
by calling the notifyOriginalCredit API to notify Alipay+ of the OCT result.

Handle inquiries about the OCT result

If the value of the result.resultCode parameter is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, Alipay+ calls the inquireOriginalCredit API to inquire about the OCT result.

Processing logic

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

Ensure the result and originalCreditResult parameters are configured properly in the response:

If the OCT succeeds, set the value of result.resultStatus to S and the value of originalCreditResult.resultStatus to S.
If the OCT fails, set the value of result.resultStatus to S and the value of originalCreditResult.resultStatus to F.
If the OCT is in processing, set the value of result.resultStatus to S and the value of originalCreditResult.resultStatus to U.
If the OCT order does not exist, set the value of result.resultStatus to F and the value of result.resultCode to ORDER_NOT_EXIST.
If system or network issues exist, set the value of result.resultStatus to U and Alipay+ will retry the inquiry.

By default, the OCT expiry time is 1 minute. Before the OCT expires, Alipay+ calls the inquireOriginalCredit API in the form of polling until the originalCreditResult.resultStatus parameter of S or F is obtained, or until the asynchronous notification is received.
If the value of originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for 1 minute and no asynchronous notification is received, Alipay+ calls the confirmOriginalCredit API to proactively push the OCT status to success. For more information, see Step 5. Confirm the OCT.

Samples

Alipay+ sends a request to the MPP.

copy
{
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000"
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "sceneType":"TAX_REFUND",
  "subSceneType":"PORT_INSTANT_TAX_REFUND",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "originalCreditId": "hk_tax_1089760038715669_102775745070000",
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

More information

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

Send OCT result notifications

Once the OCT reaches a final state of success or failure, if the MPP has integrated the notifyOriginalCredit API, the MPP can instantly send Alipay+ an asynchronous notification with the OCT result. Therefore, it is recommended that the MPP integrate the notifyOriginalCredit API.

Processing logic

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

Ensure the following parameters are configured properly in the request:

originalCreditResult.resultStatus: specifies the OCT result.

If the OCT is successful, set the value of this parameter to S.
If the OCT fails, set the value of this parameter to F and set the value of the originalCreditResult.resultMessage parameter accordingly.

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

result.resultStatus	result.resultCode	Notification status	Actions
S	`SUCCESS`	The notification is successful.	N/A
F	Multiple possible values exist, such as `ACCESS_DENIED` and `KEY_NOT_FOUND`.	The notification fails.	Take actions according to the result code which is specified on the result.resultCode parameter.
U	Multiple possible values exist, such as `UNKNOWN_EXCEPTION` and `REQUEST_TRAFFIC_EXCEED_LIMIT`.	The notification is in unknown status.	Retry the same request.
No result received		The notification is in unknown status.	Retry the same request.

Samples

The MPP sends a request to Alipay+.

copy
{
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "sceneType":"TAX_REFUND",
  "subSceneType":"PORT_INSTANT_TAX_REFUND",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "originalCreditId": "hk_tax_1089760038715669_102775745070000",
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payee": {
    "userId": "2088245U41144145",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

Alipay+ returns a response to the MPP.

copy
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

More information

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

Step 5. Confirm the OCT

Alipay+ calls the confirmOriginalCredit API to push the OCT status to success in either of the following conditions:

The ACQP proactively calls Alipay+ to confirm the success of the OCT.
The ACQP does not call Alipay+ to confirm the success of the OCT but no OCT result is obtained from the MPP after Alipay+ polls the inquireOriginalCredit API for 1 minute.

After receiving the confirmOriginalCredit API request from Alipay+, the MPP needs to ensure that the tax refund is successfully processed.

Processing logic

When handling the confirmOriginalCredit API, ensure the result parameter is configured properly in the response:

If the OCT succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS, and return originalCreditId to Alipay+.
If the OCT fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly. Alipay+ then retries the confirmOriginalCredit request.
If the OCT is in unknown status, set the value of result.resultStatus to U and the value of result.resultCode accordingly. Alipay+ then retries the confirmOriginalCredit request.

Note: If the value of result.resultStatus is not S in the response, Alipay+ retries the confirmOriginalCredit request until the OCT succeeds at the MPP side.

Samples

Alipay+ sends a request to the MPP.

copy
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "originalCreditRequestId": "20190608114010800100188820200350000"
}

The MPP returns a response to Alipay+.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "originalCreditId": "hk_tax_1089760038715669_102775745070000"
}

More information

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