This topic introduces the functions that Alipay+ Tax Refund provides and guides you through how to use the APIs to build an integration for these functions.

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. For more information, see Alipay+ Tax Refund.

Integration process for Alipay+ instant tax refund

Workflow

The Alipay+ instant tax refund workflow contains the following steps:

1. The Tax Refund Service Provider (TRSP) acts based on the user’s method of providing userId (Steps 1-5):

• If the user scans the Alipay+ refund code, the TRSP calls the evaluateOriginalCredit API with subScenarioType = PORT_INSTANT_TAX_REFUND and the tax refund code to evaluate whether the user's MPP account supports the OCT.
• If the user enters their userId on the kiosk machine, the TRSP calls the evaluateOriginalCredit API with subScenarioType = PORT_INSTANT_TAX_REFUND and userId to evaluate whether the user's MPP account supports the OCT.

2. Alipay+ forwards the evaluation request to the MPP and then returns the evaluation result and payeeAmount to the TRSP (Steps 6-7).
3. After the user confirms the refundable amount, the TRSP calls the createOriginalCredit API with subScenarioType = PORT_INSTANT_TAX_REFUND and userId to create an OCT (Steps 8-9).
4. Alipay+ processes the OCT and returns the result to the TRSP (Steps 10-11).
5. If result.resultCode is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the TRSP calls the inquireOriginalCredit API to inquire about the OCT result. Alipay+ processes the inquiry and returns the results to the TRSP (Steps 12-14).
6. If the TRSP has integrated the notifyOriginalCredit API, Alipay+ notifies the TRSP of the OCT result. The TRSP then returns the notification result to Alipay+ (Steps 15-16).
7. If the value of the originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute, the TRSP needs to call the confirmOriginalCredit API to confirm the success of the OCT. Alipay+ then returns the confirmation result to the TRSP (Steps 17-19).
8. the TRSP updates the OCT status at its server side (Step 20).

Step 1: Evaluate user's account

After the user scans the tax refund code, the TRSP calls the evaluateOriginalCredit API to request Alipay+ to evaluate whether the user's MPP account supports the OCT.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• evaluationType: specifies the basis for the evaluation.

• BY_CODE: indicates that the evaluation is performed based on the tax refund code. Set this value when the user presents the tax refund code at the kiosk.
• BY_USER_ID: indicates that the evaluation is performed based on userId. Set this value when the user enters their user ID at the kiosk.

• payeeMethod: specifies the payment method that is used by the user to receive the funds.

• payeeMethod.paymentMethodType: specifies the type of the payment method. In this case, set the value to CONNECT_WALLET, which indicates Alipay+ wallets.
• payeeMethod.paymentMethodId: specifies the ID of the payment method. In this case, set the value to the tax refund code or the userId that is presented by the MPP user.

• subScenarioType: specifies the secondary business scenario. In this scenario, set this to PORT_INSTANT_TAX_REFUND indicating scenarios in which users submit tax refund requests at airports, ports, or borders for real-time refunds.

• Handle the response properly, especially the following parameters:

• result.resultStatus: indicates the evaluation result.

• If result.resultStatus is S, call the createOriginalCredit API to initiate an OCT.
• If result.resultStatus is U, retry the evaluateOriginalCredit API request.

• payee.userId: indicates the ID of the user that receives the fund. You need to specify this parameter in the createOriginalCredit API request when you initiate an OCT.
• payeeAmount: indicates the amount of funds that is refundable to the user's MPP account. The TRSP prompts the user to confirm the refundable amount.

Samples

Request example (user scans tax refund code):

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"PORT_INSTANT_TAX_REFUND",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "evaluationType": "BY_CODE",
  "payeeMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "28100602000000000000"
  }
}

Request example (user enters user ID):

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"PORT_INSTANT_TAX_REFUND",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "evaluationType": "BY_USER_ID",
  "payeeMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "11012289272"
  }
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "passport":{
    "fullName": "XIAOMING",
    "passportNumber": "103369874587",
    "nationality": "CN",
    "issueDate": "2025-01-01",
    "expireDate": "2035-01-01",
    "birthDate": "1998-01-01"
  }
}

More information

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

Step 2: Create an OCT

After the user confirms the refundable amount, the TRSP calls the createOriginalCredit API to request Alipay+ to create an OCT.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• payee.userId: specifies the ID of the user that receives the fund. Set the value of this parameter to that of the payee.userId parameter in the evaluateOriginalCredit API response returned by Alipay+.
• payerAmount: specifies the amount of funds that the TRSP requests to transfer to Alipay+. For the same OCT, set this value to match the actual refund amount specified in the payerAmount parameter of the evaluateOriginalCredit API request.

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

Samples

Request:

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"PORT_INSTANT_TAX_REFUND",
  "payerNotificationUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/notify.htm",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payee": {
    "userId": "2102582925174840000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "taxRefundFormNumber":"11048200018287537880",
  "departureRegion":"DE",
  "departurePort":"001",
  "totalSalesAmunt":{
    "currency": "USD",
    "value": "200"
  },
  "env": {
    "clientIp": "1.1.1.1",
    "storeTerminalId": "122222",
    "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
  },
  "memo":"tax refund"
}

Response:

{
  "acquirerId": "1022188000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00",
  "originalCreditId": "20190608114010800100188820200350000",  
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 3: Obtain the OCT result

After calling the createOriginalCredit API, the TRSP can also obtain the OCT result through one of the following methods:

• Call the inquireOriginalCredit API to inquire about the OCT result.
• Receive an asynchronous notification from Alipay+ through the notifyOriginalCredit API if this API is integrated.

Inquire about the OCT result

If the result.resultCode is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the TRSP calls the inquireOriginalCredit API to inquire about the OCT result.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• originalCreditRequestId: specifies the unique ID assigned by the TRSP to identify the OCT. This value must match that in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID assigned by Alipay+ to identify the OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both are provided, priority is given to originalCreditId.

• Handle the response properly. Alipay+ returns the following two kinds of results:

• result: specifies the acknowledgment result of your inquireOriginalCredit request.
• originalCreditResult: specifies the OCT result.

• Within the default OCT expiry time of one minute, the inquireOriginalCredit API should be called in the form of polling until the originalCreditResult.resultStatus parameter of S or F is obtained. For more information about how to handle the inquireOriginalCredit API result, see How to handle the result.
• If the value of originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute and the notifyOriginalCredit API is integrated, the TRSP calls the confirmOriginalCredit API to proactively confirm the success of the OCT.

Samples

Request:

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"PORT_INSTANT_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

More information

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

Receive OCT result notification

Once the OCT reaches a final state of success or failure, Alipay+ instantly sends the TRSP an asynchronous notification with the OCT result if the TRSP has integrated the notifyOriginalCredit API and specified the payerNotificationUrl parameter in the createOriginalCredit API request.

It is recommended that the TRSP integrates the notifyOriginalCredit API.

Processing logic

When handling the notifyOriginalCredit API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• originalCreditResult.resultStatus: indicates the OCT result.

• If the value of this parameter is S, the OCT is successful.
• If the value of this parameter is F, the OCT fails.

• Ensure the following parameters are configured properly in the response:

• result.resultStatus: If you received the notification successfully, set the value of this parameter to S to indicate that your server received the call. Otherwise, Alipay+ takes the notification delivery as unsuccessful and retries the notification sending up to 7 times. The intervals between two consecutive times are as follows: 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

Samples

Request:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"PORT_INSTANT_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

Response:

{
  "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 4: Confirm the OCT result

If originalCreditResult.resultStatus remains U after polling the inquireOriginalCredit API for one minute, the TRSP calls the confirmOriginalCredit API to confirm the success of the OCT. The TRSP can then update the OCT status based on the confirmation response from Alipay+.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• originalCreditRequestId: specifies the unique ID that is assigned by the TRSP to identify an OCT. Ensure the value of this parameter is the same as that in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID that is assigned by the Alipay+ to identify an OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both are provided, priority is given to originalCreditId.

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

Note: Except for the ORIGINAL_CREDIT_ALREADY_FAILED result code, the other result codes with the F result status are only returned in the acceptance testing stage and are NOT returned in the production environment.

Samples

Request

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "2025030419074120000430000002845"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

More information

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

Integration process for urban refund (merchant reservation)

Workflow

The Alipay+ reservation tax refund workflow contains the following steps:

1. Before traveling, the user uploads their passport to Alipay+ (Step 1).
2. The user scans the QR code on the merchant's POSM using the Alipay+ wallet app and presents the tax refund code to the merchant. After the merchant scans the user's Alipay+ refund code, the merchant initiates an Original Credit Transaction (OCT) evaluation request to the TRSP. Then the TRSP calls the evaluateOriginalCredit API with subScenarioType = RESERVATION_TAX_REFUND and tax refund code to evaluate whether the user's MPP account supports the OCT (Steps 2-5).
3. Alipay+ forwards the evaluation request to the MPP and then returns the evaluation result, payeeAmount, and passport to the TRSP. Then the TRSP syncs the evaluation result, payeeAmount, and passport to the merchant (Steps 6-8).
4. The merchant initiates a syncTaxRefundForm API request to the TRSP with tax refund form information. The TRSP then calls the syncTaxRefundForm API with tax refund form information to sync the tax refund form information with Alipay+. Alipay+ stores tax refund form information and returns the synchronization result to the TRSP and the merchant (Steps 9-13).
5. Upon arriving at the airport, the user scans their passport and tax refund form at customs. The merchant initiates an OCT request with userId to the TRSP. Then the TRSP calls the createOriginalCredit API with subScenarioType = RESERVATION_TAX_REFUND and userId to create an OCT (Steps 14-16).
6. Alipay+ processes the OCT and returns the OCT result to the merchant through the TRSP (Steps 17-19).
7. If the result.resultCode is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the TRESP needs to call the inquireOriginalCredit API to inquire about the OCT result. Alipay+ processes the inquiry and returns the inquiry and OCT results to the TRSP, which syncs the inquiry and OCT results to the merchant (Steps 20-22).
8. If the TRSP has integrated the notifyOriginalCredit API, Alipay+ notifies the TRSP of the OCT result, which is then synced to the merchant. The merchant then returns the notification result and the TRSP syncs the notification result to Alipay+ (Steps 23-26).
9. If the value of the originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute, the TRSP needs to call the confirmOriginalCredit API to confirm the success of the OCT. Alipay+ then returns the confirmation result to the TRSP (Steps 27-29).
10. the TRSP updates the OCT status at its server side (Step 30).

Step 0: Before travel

Before traveling, the user uploads their passport to Alipay+.

Step 1: Evaluate user's account

After the user presents their tax refund code, the merchant initiates an OCT evaluation request to the TRSP. Then the TRSP calls the evaluateOriginalCredit API to request Alipay+ to evaluate whether the user's MPP account supports the OCT.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• evaluationType: specifies the basis for the evaluation.

• BY_CODE: indicates that the evaluation is based on the tax refund code. Set the value for evaluationType when the user presents the tax refund code to the kiosk machine.
• BY_USER_ID: indicates that the evaluation is based on the userId. Set the value for evaluationType when the user enters userId on the kiosk machine.

• payeeMethod: specifies the payment method that is used by the user to receive the funds.

• payeeMethod.paymentMethodType: specifies the type of the payment method. In this case, set the value to CONNECT_WALLET, which indicates Alipay+ wallets.
• payeeMethod.paymentMethodId: specifies the ID of the payment method. In this case, set the value to the tax refund code that is presented by the MPP user.

• subScenarioType: specifies the secondary business scenario. In this scenario, set this parameter as PORT_INSTANT_TAX_REFUND, indicating that users submit tax refund requests at airports, ports, or borders to receive refunds in real time.

• Handle the response properly, especially the following parameters:

• result.resultStatus: This parameter indicates the evaluation result.

• If the value of result.resultStatus is S, call the createOriginalCredit API to initiate an OCT.
• If the value of result.resultStatus is U, retry the evaluateOriginalCredit API request.

• payee.userId: indicates the ID of the user that receives the fund. You need to specify this parameter in the createOriginalCredit API request when you initiate an OCT.
• payeeAmount: indicates the amount of funds that is refundable to the user's MPP account. The TRSP prompts the user to confirm the refundable amount.

Samples

Request:

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "evaluationType": "BY_CODE",
  "payeeMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "28100602000000000000"
  }
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "passport":{
    "fullName": "XIAOMING",
    "passportNumber": "103369874587",
    "nationality": "CN",
    "issueDate": "2025-01-01",
    "expireDate": "2035-01-01",
    "birthDate": "1998-01-01"
  }
}

More information

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

Step 2: Sync tax refund form information

After Alipay+ confirms the user's eligibility for OCT, the evaluation result, along with payeeAmount and passport, is returned to the TRSP, which then syncs this data with the merchant.

Then the merchant requests the TRSP to call the syncTaxRefundForm API to sync the tax refund information form with Alipay+.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• taxRefundFormNumber: the ID of the tax refund form.
• formStatus: the current status of the tax refund form.
• userId: the unique ID that is assigned by the MPP to identify a user.
• taxRefundAmount: the amount of tax to refund.
• merchants: the merchants' information.

• Ensure that you handle the response result properly:

• result: the result of the tax refund form synchronization. When resultStatus is S, the sync is successful and the next step can be processed. If resultStatus is notS, retry with the same taxRefundFormNumber.

Samples

Request

{
  "taxRefundFormNumber":"11048200018287537880",
  "formStatus":"INIT",
  "statusChangeTime":"2019-06-01T12:01:01+08:00",
  "formPrintDate":"2019-06-01T12:01:01+08:00",
  "formExpireDate":"2019-06-01T12:01:01+08:00",
  "taxRefundAmount":{
    "currency": "USD",
    "value": "200"
  },
  "merchants": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "userId":"11012289272",
  "memo":"tax refund"
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

More information

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

Step 3: Create an OCT

After the user arrives at the airport and scans their passport and tax refund form, the merchant initiates an OCT to the TRSP. The TRSP calls the createOriginalCredit API to request Alipay+ to create an OCT.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• payee.userId: specifies the ID of the user that receives the fund. Set the value of this parameter to that of the payee.userId parameter in the evaluateOriginalCredit API response returned by Alipay+.
• payerAmount: specifies the amount of funds that the TRSP requests to transfer to Alipay+. For the same OCT, set this value to match the actual refund amount specified in the payerAmount parameter of the evaluateOriginalCredit API request.

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

Samples

Request:

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "payerNotificationUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/notify.htm",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payee": {
    "userId": "2102582925174840000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "taxRefundFormNumber":"11048200018287537880",
  "departureRegion":"DE",
  "departurePort":"001",
  "totalSalesAmunt":{
    "currency": "USD",
    "value": "200"
  },
  "env": {
    "clientIp": "1.1.1.1",
    "storeTerminalId": "122222",
    "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
  },
  "memo":"tax refund"
}

Response:

{
  "acquirerId": "1022188000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00",
  "originalCreditId": "20190608114010800100188820200350000",  
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 4: Obtain the OCT result

After calling the createOriginalCredit API, the TRSP can obtain the OCT result using one of the following methods:

• Call the inquireOriginalCredit API to inquire about the OCT result.
• Receive an asynchronous notification from Alipay+ through the notifyOriginalCredit API if this API is integrated.

Inquire about the OCT result

If the result.resultCode is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the merchant requests the TRSP to call the inquireOriginalCredit API to inquire about the OCT result.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• originalCreditRequestId: specifies the unique ID assigned by the TRSP to identify an OCT. This value must match that in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID assigned by Alipay+ to identify an OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both parameters are included, priority is given to originalCreditId.

• Handle the response properly. Alipay+ returns the following two kinds of results:

• result: specifies the acknowledgment result of your inquireOriginalCredit request.
• originalCreditResult: specifies the OCT result.

• Within the default OCT expiry time of one minute, the inquireOriginalCredit API should be called in the form of polling until the originalCreditResult.resultStatus parameter of S or F is obtained. For more information about how to handle the inquireOriginalCredit API result, see How to handle the result.
• If the value of originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute and the notifyOriginalCredit API is integrated, the TRSP calls the confirmOriginalCredit API to proactively confirm the success of the OCT.

Samples

Request

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

More information

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

Receive OCT result notification

Once the OCT reaches a final state of success or failure, Alipay+ instantly sends the TRSP an asynchronous notification with the OCT result if the TRSP has integrated the notifyOriginalCredit API and specified the payerNotificationUrl parameter in the createOriginalCredit API request. Then the TRSP syncs the result with the merchant.

It is recommended that the TRSP integrates the notifyOriginalCredit API.

Processing logic

When handling the notifyOriginalCredit API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• originalCreditResult.resultStatus: indicates the OCT result.

• If the value is S, the OCT is successful.
• If the value is F, the OCT fails.

• Ensure the following parameters are configured properly in the response:

• result.resultStatus: if you received the notification successfully, set this value to S to indicate successful receipt of the notification. If not set to S, Alipay+ considers the notification delivery unsuccessful and will attempt to resend it up to seven times, with the following intervals: 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

Samples

Request:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

Response:

{
  "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 result

If originalCreditResult.resultStatus remains U after polling the inquireOriginalCredit API for 1 minute, the TRSP calls the confirmOriginalCredit API to confirm the success of the OCT. The TRSP can then update the OCT status based on the confirmation response from Alipay+.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• originalCreditRequestId: specifies the unique ID that is assigned by the TRSP to identify the OCT. Ensure that this value matches the one in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID that is assigned by Alipay+ to identify the OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both parameters are included, priority is given to originalCreditId.

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

Note: Except for the ORIGINAL_CREDIT_ALREADY_FAILED result code, the other result codes with the F result status are only returned in the acceptance testing stage and are NOT returned in the production environment.

Samples

Request:

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "2025030419074120000430000002845"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

More information

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

Integration process for Alipay+ mini-program auto tax refund

Workflow

The Alipay+ mini-program auto tax refund workflow contains the following steps:

1. The merchant prints a tax refund form for the user. Then the user scans the POSM of the Alipay+ tax refund mini-program, uploads their passport, and scans the tax refund forms to Alipay+ (Steps 1-4).
2. Alipay+ calls the syncTaxRefundUserInfo API to sync the taxRefundFormNumber and userId with the TRSP (Steps 5-6).
3. The TRSP calls the syncTaxRefundForm API with tax refund form information to sync tax refund form information with Alipay+. Alipay+ stores taxRefundForm and returns the synchronization result to the TRSP (Steps 7-9).
4. When the user arrives at the airport and scans their passport and tax refund form at customs, the TRSP calls the createOriginalCredit API with subScenarioType = RESERVATION_TAX_REFUND and userId to create an OCT (Step 10).
5. Alipay+ processes the OCT and returns the OCT result to the TRSP (Steps 11-12).
6. If the value of the result.resultCode is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the TRSP needs to call the inquireOriginalCredit API to inquire about the OCT result. Alipay+ processes the inquiry and returns the inquiry and OCT results to the TRSP (Steps 13-15).
7. If the TRSP has integrated the notifyOriginalCredit API, Alipay+ notifies the TRSP of the OCT result. The TRSP then returns the notification result to Alipay+ (Steps 16-17).
8. If the value of the originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute, the TRSP needs to call the confirmOriginalCredit API to confirm the success of the OCT. Alipay+ then returns the confirmation result to the TRSP (Steps 18-20).
9. The TRSP updates the OCT status at its server side (Step 21).

Step 1: User uploads passport and tax refund form

The user scans the POSM of the Alipay+ tax refund mini-program and uploads their passport and scans the associated tax refund forms.

Step 2: Sync of the user information

After scanning the tax refund form, Alipay+ calls the syncTaxRefundUserInfo API to sync userId and taxRefundFormNumber with the TRSP.

Processing logic

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

• Handle the request properly, especially the following parameters:

• userId: the unique ID that is assigned by the MPP to identify a user.
• passport: the passport information.
• taxRefundFormNumber: the ID of the tax refund form.

• Ensure the following parameter is configured properly in the response:

• result: the result of sync tax refund user information. When synchronization succeeds, the TRSP should return the result with resultStatus = S to indicate the synchronization succeeds. If the synchronization fails, Alipay+ retries with the same taxRefundFormNumber, the TRSP should ensure idempotency.

Samples

Request:

{
  "taxRefundFormNumber":"11048200018287537880",
  "userId":"11012289272",
  "passport":{
    "fullName": "XIAOMING",
    "passportNumber": "103369874587",
    "nationality": "CN",
    "issueDate": "2025-01-01",
    "expireDate": "2035-01-01",
    "birthDate": "1998-01-01"
  }
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

More information

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

Step 3: Sync tax refund form information

The TRSP calls the syncTaxRefundForm API to sync the tax refund information form with Alipay+. Alipay+ stores the tax refund form information.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• taxRefundFormNumber: the ID of the tax refund form.
• formStatus: the current status of the tax refund form.
• userId: the unique ID that is assigned by the MPP to identify a user.
• taxRefundAmount: the amount of tax to refund.
• merchants: the merchants' information.

• Ensure handle the response result properly:

• result: the result of sync tax refund form. When resultStatus =S indicates the synchronization is successful and the next step can be processed. If resultStatus is notS, retry with the same taxRefundFormNumber.

Samples

Request:

{
  "taxRefundFormNumber":"11048200018287537880",
  "formStatus":"INIT",
  "statusChangeTime":"2019-06-01T12:01:01+08:00",
  "formPrintDate":"2019-06-01T12:01:01+08:00",
  "formExpireDate":"2019-06-01T12:01:01+08:00",
  "taxRefundAmount":{
    "currency": "USD",
    "value": "200"
  },
  "merchants": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "userId":"11012289272",
  "memo":"tax refund"
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

More information

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

Step 4: Create an OCT

After the user arrives at the airport and scans their passport and tax refund form, the TRSP calls the createOriginalCredit API to request Alipay+ to create an OCT.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• payee.userId: specifies the ID of the user that receives the fund. Set the value of this parameter to that of the payee.userId parameter in the evaluateOriginalCredit API response returned by Alipay+.
• payerAmount: specifies the amount of funds that the TRSP requests to transfer to Alipay+. For the same OCT, set this value to match the actual refund amount specified in the payerAmount parameter of the evaluateOriginalCredit API request.

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

Samples

Request:

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "payerNotificationUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/notify.htm",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payee": {
    "userId": "2102582925174840000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "taxRefundFormNumber":"11048200018287537880",
  "departureRegion":"DE",
  "departurePort":"001",
  "totalSalesAmunt":{
    "currency": "USD",
    "value": "200"
  },
  "env": {
    "clientIp": "1.1.1.1",
    "storeTerminalId": "122222",
    "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
  },
  "memo":"tax refund"
}

Response:

{
  "acquirerId": "1022188000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00",
  "originalCreditId": "20190608114010800100188820200350000",  
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 5: Obtain the OCT result

After calling the createOriginalCredit API, the TRSP can obtain the OCT result through one of the following methods:

• Call the inquireOriginalCredit API to inquire about the OCT result.
• Receive the asynchronous notification sent by Alipay+ through the notifyOriginalCredit API if this API is integrated.

Inquire about the OCT result

If the result.resultStatus is U in the createOriginalCredit API response, the TRSP calls the inquireOriginalCredit API to inquire about the OCT result.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• originalCreditRequestId: specifies the unique ID assigned by the TRSP to identify an OCT. This value must match that in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID assigned by Alipay+ to identify an OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both parameters are included, priority is given to originalCreditId.

• Handle the response properly. Alipay+ returns the following two kinds of results:

• result: specifies the acknowledgment result of your inquireOriginalCredit request.
• originalCreditResult: specifies the OCT result.

• Within the default OCT expiry time of one minute, the inquireOriginalCredit API should be called in the form of polling until the originalCreditResult.resultStatus parameter of S or F is obtained. For more information about how to handle the inquireOriginalCredit API result, see How to handle the result.
• If the value of originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute and the notifyOriginalCredit API is integrated, the TRSP calls the confirmOriginalCredit API to proactively confirm the success of the OCT.

Samples

Request:

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

More information

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

Receive OCT result notification

Once the OCT reaches a final state of success or failure, Alipay+ instantly sends the TRSP an asynchronous notification with the OCT result if the TRSP has integrated the notifyOriginalCredit API and specified the payerNotificationUrl parameter in the createOriginalCredit API request.

It is recommended that the TRSP integrates the notifyOriginalCredit API.

Processing logic

When handling the notifyOriginalCredit API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• originalCreditResult.resultStatus: indicates the OCT result.

• If the value of is S, the OCT is successful.
• If the value of is F, the OCT fails.

• Ensure the following parameters are configured properly in the response:

• result.resultStatus: If you received the notification successfully, set this value to S to indicate successful receipt of the notification. If not set to S, Alipay+ considers the notification delivery unsuccessful and will attempt to resend it up to seven times, with the following intervals: 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

Samples

Request

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

Response:

{
  "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 6: Confirm the OCT result

If originalCreditResult.resultStatus remains U after polling the inquireOriginalCredit API for one minute, the TRSP calls the confirmOriginalCredit API to confirm the success of the OCT. The TRSP can then update the OCT status based on the confirmation response from Alipay+.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• originalCreditRequestId: specifies the unique ID that is assigned by the TRSP to identify the OCT. Ensure that this value matches the one in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID that is assigned by Alipay+ to identify the OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both parameters are included, priority is given to originalCreditId.

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

Note: Except for the ORIGINAL_CREDIT_ALREADY_FAILED result code, the other result codes with the F result status are only returned in the acceptance testing stage and are NOT returned in the production environment.

Samples

Request:

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "2025030419074120000430000002845"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

More information

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

Integration process for TSRP H5/APP auto refund

Workflow

The Alipay+ mini-program auto tax refund workflow contains the following steps:

1. The user scans the POSM to open the H5 page or app of the TRSP. Then the user chooses Alipay+ as the refund method, opens the Alipay+ GlobalPass page, copies the GlobalPass ID, and pastes it into the H5 or app page (Steps 1-3).
2. Then the TRSP calls the evaluateOriginalCredit API with subScenarioType = RESERVATION_TAX_REFUND and tax refund code to evaluate whether the user's MPP account supports the OCT (Steps 4-5).
3. After the user confirms the payee information, the user ID and user information are successfully bound (Steps 7-8).
4. The TRSP calls the syncTaxRefundForm API with tax refund form information to sync tax refund form information with Alipay+. Alipay+ stores taxRefundForm and returns the synchronization result to the TRSP (Steps 9-11).
5. When the user arrives at the airport and scans their passport and tax refund form at customs, the TRSP calls the createOriginalCredit API with subScenarioType = RESERVATION_TAX_REFUND and userId to create an OCT (Step 12).
6. Alipay+ processes the OCT and returns the OCT result to the TRSP (Steps 13-14).
7. If the value of the result.resultCode is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the TRSP needs to call the inquireOriginalCredit API to inquire about the OCT result. Alipay+ processes the inquiry and returns the inquiry and OCT results to the TRSP (Steps 15-17).
8. If the TRSP has integrated the notifyOriginalCredit API, Alipay+ notifies the TRSP of the OCT result. The TRSP then returns the notification result to Alipay+ (Steps 18-19).
9. If the value of the originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute, the TRSP needs to call the confirmOriginalCredit API to confirm the success of the OCT. Alipay+ then returns the confirmation result to the TRSP (Steps 20-22).
10. The TRSP updates the OCT status at its server side (Step 23).

Step 1: User binds GlobalPass ID on the TRSP's H5 or APP

The user scans the POSM to open the H5 page or app of the TRSP. Then the user chooses Alipay+ as the refund method, opens the Alipay+ GlobalPass page, copies the GlobalPass ID, and pastes it into the H5 or app page.

Step 2: Evaluate user's account and finish binding

The TRSP calls the evaluateOriginalCredit API to request Alipay+ to evaluate whether the user's MPP account supports the OCT. If the evaluation shows that the user's MPP account is eligible, the TRSP's H5 or app page displays the payee information for confirmation.

After the user confirms the information, the binding process succeeds.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• evaluationType: specifies the basis for the evaluation.

• BY_CODE: indicates that the evaluation is based on the tax refund code. Set the value for evaluationType when the user presents the tax refund code to the kiosk machine.
• BY_USER_ID: indicates that the evaluation is based on userId. Set the value for evaluationType when the user enters userId on the kiosk machine.

• payeeMethod: specifies the payment method that is used by the user to receive the funds.

• payeeMethod.paymentMethodType: specifies the type of the payment method. In this case, set the value to CONNECT_WALLET, which indicates Alipay+ wallets.
• payeeMethod.paymentMethodId: specifies the ID of the payment method. In this case, set the value to the tax refund code that is presented by the MPP user.

• subScenarioType: specifies the secondary business scenario. In this scenario, set this parameter as PORT_INSTANT_TAX_REFUND, indicating that users submit tax refund requests at airports, ports, or borders to receive refunds in real time.

• Handle the response properly, especially the following parameters:

• result.resultStatus: indicates the evaluation result.

• If result.resultStatus is S, call the createOriginalCredit API to initiate an OCT.
• If result.resultStatus is U, retry the evaluateOriginalCredit API request.

• payee.userId: indicates the ID of the user that receives the fund. You need to specify this parameter in the createOriginalCredit API request when you initiate an OCT.
• payeeAmount: indicates the amount of funds that is refundable to the user's MPP account. The TRSP prompts the user to confirm the refundable amount.

Samples

Request:

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "evaluationType": "BY_CODE",
  "payeeMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "28100602000000000000"
  }
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "passport":{
    "fullName": "XIAOMING",
    "passportNumber": "103369874587",
    "nationality": "CN",
    "issueDate": "2025-01-01",
    "expireDate": "2035-01-01",
    "birthDate": "1998-01-01"
  }
}

More information

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

Step 3: Sync tax refund form information

The TRSP calls the syncTaxRefundForm API to sync the tax refund information form with Alipay+. The Alipay+ stores this information.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• taxRefundFormNumber: the ID of the tax refund form.
• formStatus: the current status of the tax refund form.
• userId: the unique ID that is assigned by the MPP to identify a user.
• taxRefundAmount: the amount of tax to refund.
• merchants: the merchants' information.

• Ensure handle the response result properly:

• result: indicates the outcome of syncing the tax refund form. When resultStatus =S indicates the synchronization is successful and the next step can be processed. If resultStatus is notS, retry with the same taxRefundFormNumber.

Samples

Request:

{
  "taxRefundFormNumber":"11048200018287537880",
  "formStatus":"INIT",
  "statusChangeTime":"2019-06-01T12:01:01+08:00",
  "formPrintDate":"2019-06-01T12:01:01+08:00",
  "formExpireDate":"2019-06-01T12:01:01+08:00",
  "taxRefundAmount":{
    "currency": "USD",
    "value": "200"
  },
  "merchants": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "userId":"11012289272",
  "memo":"tax refund"
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

More information

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

Step 4: Create an OCT

After the user arrives at the airport and scans their passport and tax refund form, the TRSP calls the createOriginalCredit API to request Alipay+ to create an OCT.

Processing logic

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

• Ensure the following parameters are configured properly in the request:

• payee.userId: specifies the ID of the user that receives the fund. Set the value of this parameter to that of the payee.userId parameter in the evaluateOriginalCredit API response returned by Alipay+.
• payerAmount: specifies the amount of funds that the TRSP requests to transfer to Alipay+. For the same OCT, set this value to match the actual refund amount specified in the payerAmount parameter of the evaluateOriginalCredit API request.

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

Samples

Request:

{
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "payerNotificationUrl": "https://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/notify.htm",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payee": {
    "userId": "2102582925174840000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "taxRefundFormNumber":"11048200018287537880",
  "departureRegion":"DE",
  "departurePort":"001",
  "totalSalesAmunt":{
    "currency": "USD",
    "value": "200"
  },
  "env": {
    "clientIp": "1.1.1.1",
    "storeTerminalId": "122222",
    "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
  },
  "memo":"tax refund"
}

Response:

{
  "acquirerId": "1022188000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00",
  "originalCreditId": "20190608114010800100188820200350000",  
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  }
}

More information

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

Step 5: Obtain the OCT result

After calling the createOriginalCredit API, the TRSP can obtain the OCT result through one of the following methods:

• Call the inquireOriginalCredit API to inquire about the OCT result.
• Receive an asynchronous notification from Alipay+ through the notifyOriginalCredit API if this API is integrated.

Inquire about the OCT result

If the result.resultStatus is U in the createOriginalCredit API response, the TRSP calls the inquireOriginalCredit API to inquire about the OCT result.

Processing logic

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

• Ensure the following parameters are properly configured in the request:

• originalCreditRequestId: specifies the unique ID that is assigned by the TRSP to identify the OCT. Ensure that this value matches the one in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID that is assigned by Alipay+ to identify the OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both parameters are included, priority is given to originalCreditId.

• Handle the response properly. Alipay+ returns the following two kinds of results:

• result: specifies the acknowledgment result of your inquireOriginalCredit request.
• originalCreditResult: specifies the OCT result.

• Within the default OCT expiry time of one minute, the inquireOriginalCredit API should be called in the form of polling until the originalCreditResult.resultStatus parameter of S or F is obtained. For more information about how to handle the inquireOriginalCredit API result, see How to handle the result.
• If the value of originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for one minute and the notifyOriginalCredit API is integrated, the TRSP calls the confirmOriginalCredit API to proactively confirm the success of the OCT.

Samples

Request:

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

More information

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

Receive OCT result notification

Once the OCT reaches a final state of success or failure, Alipay+ instantly sends the TRSP an asynchronous notification with the OCT result if the TRSP has integrated the notifyOriginalCredit API and specified the payerNotificationUrl parameter in the createOriginalCredit API request.

It is recommended that the TRSP integrates the notifyOriginalCredit API.

Processing logic

When handling the notifyOriginalCredit API request, take the following things into consideration:

• Handle the request properly, especially the following parameters:

• originalCreditResult.resultStatus: indicates the OCT result.

• If the value is S, the OCT is successful.
• If the value is F, the OCT fails.

• Ensure the following parameters are configured properly in the response:

• result.resultStatus: If you received the notification successfully, set this value to S to indicate successful receipt of the notification. If not set to S, Alipay+ considers the notification delivery unsuccessful and will attempt to resend it up to seven times, with the following intervals: 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

Samples

Request:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "originalCreditResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "scenarioType":"TAX_REFUND",
  "subScenarioType":"RESERVATION_TAX_REFUND",
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "20190608114010800100188820200350000",
  "payerAmount": {
    "currency": "USD",
    "value": "100"
  },
  "payeeAmount": {
    "value": "1000",
    "currency": "HKD"
  },
  "payeeQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "USD/HKD",
    "quotePrice": "10.0000"
  },
  "payer": [
    {
      "referenceMerchantId": "2188245U41144145",
      "merchantAddress": {
        "region":"DE"
      },
      "merchantName": "Merchant Name",
      "merchantMCC": "5411"
    }
  ],
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

Response:

{
  "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 6: Confirm the OCT result

If originalCreditResult.resultStatus is still U after polling the inquireOriginalCredit API for 1 minute, the TRSP calls the confirmOriginalCredit API to confirm the success of the OCT. The TRSP can then update the OCT status based on the confirmation response from Alipay+.

Processing logic

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

• Ensure the following parameters are properly configured in the request:

• originalCreditRequestId: specifies the unique ID that is assigned by the TRSP to identify the OCT. Ensure that this value matches the one in the createOriginalCredit API request.
• originalCreditId: specifies the unique ID that is assigned by Alipay+ to identify the OCT.

Note: You must specify either originalCreditRequestId or originalCreditId. If both are provided, priority is given to originalCreditId.

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

Note: Except for the ORIGINAL_CREDIT_ALREADY_FAILED result code, the other result codes with the F result status are only returned in the acceptance testing stage and are NOT returned in the production environment.

Samples

Request:

{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000",
  "originalCreditId": "2025030419074120000430000002845"
}

Response:

{
  "acquirerId": "A10221XX000000000000",
  "pspId": "1022160000000000000",
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

More information

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