syncTaxRefundForm
POST /aps/api/v1/funds/syncTaxRefundForm
The syncTaxRefundForm API is used by the Tax Refund Service Provider (TRSP) to send a request to Alipay+ for synchronizing tax refund form information.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is 20, set it as "20".
- If the data type of a field is Boolean and its value is
true, set it as "true".For optional parameters that are not required in your case, you can:
- exclude it from the request body.
- set its value as
null(without the double quotation marks).Do NOT leave it empty by setting its value as
""; otherwise, an error might occur.
Request parameters
Field | Data type | Required | Description |
taxRefundFormNumber | String | M | The ID of paper-based tax refund form. More information about this field:
|
formStatus | String | M | Current status of tax refund form. Valid values:
|
statusChangeTime | Datetime | O | The time the current status was recorded. More information:
|
formPrintDate | Datetime | O | Print date of the tax refund form. More information:
|
formExpireDate | Datetime | O | Expiration date of the tax refund form. The valid time of the tax refund form is 6 months. formExpireDate = formPrintDate + 6 months. More information:
|
taxRefundAmount | M | Amount of tax refund. | |
merchants | Array(Merchant) | M | Merchant information. |
userId | String | M | The unique ID assigned by Alipay+ to identify a user. More information about this field:
|
memo | String | O | The additional message provided by the payer about the synchronization. More information about this field:
|
Response parameters
Field | Data type | Required | Description |
result | M | The result of syncing the tax refund form. resultStatus == When resultStatus is not |
How to handle the result
You may receive different results from Alipay+. Follow the instructions below to manage the result:
result.resultStatus | result.resultCode | Status | Actions |
S |
| The syncTaxRefundForm request is successful. | Update the status from your server side. |
F | Multiple possible values exist, such as | The syncTaxRefundForm request fails. | Take actions according to the error message specified on the result.resultMessage parameter. |
U | Multiple possible values exist, such as
| The syncTaxRefundForm request is in unknown status. | Retry the syncTaxRefundForm API request using the same parameters. It is recommended to try several times. If you continue to receive the same result indicating an unknown status, contact connect_support@service.alipay.com. |
No result received after several attempts. | The syncTaxRefundForm request is in unknown status. | Contact connect_support@service.alipay.com. | |
Result codes
Result code | Result status | Result message | Further action |
SUCCESS | S | Success | Update the OCT status to success from your server side. |
ACCESS_DENIED | F | Access is denied. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
INVALID_CLIENT | F | The client is invalid. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
INVALID_SIGNATURE | F | The signature is invalid. | Check whether the public key, signed message, and signature algorithm are as expected. |
KEY_NOT_FOUND | F | The key is not found. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. | Use a media type that is accepted by Alipay+. |
METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. | Ensure that the HTTP method is POST. |
NO_INTERFACE_DEF | F | API is not defined. | Check whether the request URL is correct. Ensure that the endpoint of the called API is correct. |
PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. | Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of each API, see the Structure section. |
REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Ensure that the values of the parameters in the repeated requests are the same. |
USER_NOT_EXIST | F | The user does not exist. | It is recommended that you inform the user of the error. |
PROCESS_FAIL | F | A general business failure occurred. Do not retry. | It is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Reduce the frequency of API calls. |
UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. | Try to recall the API. |
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":"210220900000021958205",
"memo": "tax refund"
}Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
}
}