Integration guide

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.

Workflow

The following figure illustrates the tax refund workflow.

Figure 1. Tax refund workflow

The tax refund workflow contains the following steps:

The user presents the tax refund code to the merchant, who scans the tax refund code and then initiates an Original Credit Transaction (OCT) evaluation request to the Acquiring Service Provider (ACQP) (Steps 1-3).
The ACQP calls the evaluateOriginalCredit API to evaluate whether the user's MPP account supports the OCT. Alipay+ forwards the evaluation request to the MPP and then returns the evaluation result to the ACQP. The evaluation result includes the user ID at the MPP platform and the amount of funds that Alipay+ transfers to the user's MPP account (Steps 4-6).
The ACQP syncs the evaluation result to the merchant, who then prompts the user to confirm the refundable amount (Steps 7-8).
The merchant initiates an OCT with the user ID to the ACQP, which then calls the createOriginalCredit API to request Alipay+ to create an OCT. Alipay+ processes the OCT and returns the result to the ACQP, which syncs the result to the merchant (Steps 9-13).
If the value of the result.resultCode parameter is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the merchant calls the ACQP to inquire about the OCT result. The ACQP 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 ACQP, which syncs the inquiry and OCT results to the merchant (Steps 14-18).
If the ACQP has integrated the notifyOriginalCredit API, Alipay+ notifies the ACQP of the OCT result, which is then synced to the merchant. The merchant then returns the notification result and the ACQP syncs the notification result to Alipay+ (Steps 19-22).
If the value of the originalCreditResult.resultStatus parameter is still U after polling the inquireOriginalCredit API for 1 minute, the ACQP needs to call the confirmOriginalCredit API to confirm the success of the OCT. Alipay+ forwards the confirmation request to the MPP to ensure that the tax refund is successfully processed by the MPP. Alipay+ then returns the confirmation result to the ACQP (Steps 23-25).
The ACQP updates the OCT status at its server side (Step 26).

Step 1. Evaluate user's account

After scanning a tax refund code presented by the user, the merchant initiates an OCT evaluation request to the ACQP. The ACQP 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 based on which the evaluation is performed. In this case, set the value to BY_CODE, which indicates that the evaluation is performed based on the tax refund code.
payeeMethod: specifies the payment method that is used by the user to receive the fund.

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.

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. For more information, see Step 2. 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 in Step 2. Initiate an OCT.
payeeAmount: indicates the amount of funds that is refundable to the user's MPP account. You need to sync it to the merchant, who then prompts the user to confirm the refundable amount.

Samples

Request

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

Response

copy
{
  "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*"
  }
}

More information

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

Step 2. Create an OCT

After the user confirms the refundable amount, the merchant initiates an OCT to the ACQP. The ACQP 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 ACQP requests to transfer to Alipay+. For the same OCT, specify the value of this parameter as the actual refund amount that you specified in the payerAmount parameter of the evaluateOriginalCredit API request.

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

result.resultStatus	result.resultCode	OCT status	Actions
S	`SUCCESS`	The OCT is successful.	Update the status from your server side.
F	Multiple possible values exist, such as `USER_STATUS_ABNORMAL`, `USER_AMOUNT_EXCEED_LIMIT`, etc.	The OCT fails.	Take actions according to the error message in the result.resultMessage parameter.
U	`ORIGINAL_CREDIT_IN_PROCESS`	The OCT is in unknown status.	Call the inquireOriginalCredit API to inquire about the OCT result. It is recommended that you send the inquireOriginalCredit API request 10 to 20 times within the expiry time, which is 60 seconds by default.
U	Multiple possible values exist, such as `UNKNOWN_EXCEPTION`, `REQUEST_TRAFFIC_EXCEED_LIMIT`	The OCT is in unknown status.	Retry the same request. It is recommended that you keep trying several times. If you keep receiving the same result indicating the unknown status, contact connect_support@service.alipay.com.
No result received after trying several times		The OCT is in unknown status.	Contact connect_support@service.alipay.com.

Samples

Request

copy
{
  "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": "Global Blue",
    "merchantMCC": "5411"
  },
  "env": {
    "clientIp": "1.1.1.1",
    "storeTerminalId": "122222",
    "storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"
  },
  "memo":"tax refund"
}

Response

copy
{
  "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 request and handle the response, see createOriginalCredit.

Step 3. Obtain the OCT result

After calling the createOriginalCredit API, the ACQP can also obtain the OCT result by using the following ways:

by calling the inquireOriginalCredit API to inquire about the OCT result.
from the asynchronous notification sent by Alipay+ through the notifyOriginalCredit API.

Inquire about the OCT result

If the value of the result.resultCode parameter is ORIGINAL_CREDIT_IN_PROCESS in the createOriginalCredit API response, the ACQP 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 that is assigned by the ACQP 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 need to specify either originalCreditRequestId or originalCreditId. In case both parameters are specified, the following priority applies: originalCreditId > originalCreditRequestId.

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 1 minute, the inquireOriginalCredit API should be called 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, the ACQP calls the confirmOriginalCredit API to proactively confirm the success of the OCT. For more information, see Step 4. Confirm the OCT.

Samples

Request

copy
{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000"
}

Response

copy
{
  "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": "Global Blue",
    "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 request 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 ACQP an asynchronous notification with the OCT result if the ACQP has integrated the notifyOriginalCredit API and specified the payerNotificationUrl parameter in the createOriginalCredit API request.

It is recommended that the ACQP integrate 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

copy
{
  "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": "Global Blue",
    "merchantMCC": "5411"
  },
  "payee": {
    "userId": "2102582925174840000",
    "userLoginId": "+442056660000*"
  },
  "originalCreditTime": "2023-01-01T14:48:50+08:00"
}

Response

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

More information

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

Step 4. Confirm the OCT

If no OCT result is obtained from Alipay+ after polling the inquireOriginalCredit API for 1 minute, the ACQP calls the confirmOriginalCredit API to confirm the success of the OCT. Alipay+ forwards the confirmation request to the MPP to ensure that the tax refund is successfully processed by the MPP. The ACQP 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 ACQP 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 need to specify either originalCreditRequestId or originalCreditId. In case both parameters are specified, the following priority applies: originalCreditId > originalCreditRequestId.

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

result.resultStatus	result.resultCode	Confirmation status	OCT status	Actions
S	`SUCCESS`	The confirmation is successful.	The OCT is successful.	Update the OCT status to success from your server side.
F	`ORIGINAL_CREDIT_ALREADY_FAILED`	The confirmation fails.	The OCT fails.	Update the OCT status to failure from your server side.
F	`ORDER_NOT_EXIST`	The confirmation fails.	The OCT is in unknown status.	For cases where the OCT does not exist, the reason might be that the originalCreditRequestId is incorrect. Use the correct ID to reinitiate the request. If you still receive the same result code of `ORDER_NOT_EXIST` after retrying the confirmOriginalCredit request, contact connect_support@service.alipay.com.
F	Multiple possible values exist, such as `ACCESS_DENIED`, `INVALID_CLIENT`, etc.	The confirmation fails.	The OCT is in unknown status.	Take actions according to the error message in the result.resultMessage parameter.
U	Multiple possible values exist, such as `UNKNOWN_EXCEPTION`, `REQUEST_TRAFFIC_EXCEED_LIMIT`, etc.	The confirmation is in unknown status.	The OCT is in unknown status.	Use the same parameters to retry the confirmOriginalCredit request. It is recommended that you keep trying several times. If you keep receiving the same result indicating the unknown status, contact connect_support@service.alipay.com.
No result received after trying several times		The comfirmation is in unknown status.	The OCT is in unknown status.	Contact connect_support@service.alipay.com.

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

copy
{
  "originalCreditRequestId": "gb_tax_1089760038715669_102775745070000"
}

Response

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

More information

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