notifyOriginalCredit
The notifyOriginalCredit API is used by Alipay+ to notify the Acquiring Service Provider (ACQP) of the result of an Original Credit Transaction (OCT) after the OCT processing reaches a final state of success or failure. Currently, an OCT can be processed by Alipay+ only in relation to Tax Refund.
Note: In the following sections, Mobile Payment Provider (MPP) is also known as Payment Service Provider. For example, the pspId parameter specifies the ID that identifies an MPP.
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 parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:
- If the data type of a parameter is Integer and its value is 20, set it as "20".
- If the data type of a parameter is Boolean and its value is
true
, set it as "true".
- For optional parameters that are not required in your case, you can:
- exclude them from the request body.
- set the values as
null
(without the double quotation marks).Do NOT leave the optional parameters empty by setting their values as
""
; otherwise, an error might occur.
Request parameters
Field | Data type | Required | Description |
originalCreditResult | Yes | The result of the OCT. See the OCT result codes table below for details. | |
acquirerId | String | Yes | The unique ID that is assigned by Alipay+ to identify an ACQP. More information about this field:
|
pspId | String | No | The unique ID that is assigned by Alipay+ to identify an MPP. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is More information about this field:
|
scenarioType | String | Yes | The business scenario in which the OCT is initiated. Valid values are:
|
subScenarioType | String | Yes | The secondary scenario of the business scenario that is specified on the scenarioType parameter. Valid values are:
|
originalCreditRequestId | String | Yes | The unique ID that is assigned by the ACQP to identify an OCT. More information about this field:
|
originalCreditId | String | No | The unique ID that is assigned by Alipay+ to identify an OCT. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is More information about this field:
|
originalCreditTime | Datetime | No | The date and time when the OCT reaches a final state. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is More information about this field:
|
payerAmount | Yes | The amount of funds that the ACQP requests to transfer to Alipay+. The currency of the amount must be specified as the one that the ACQP uses to create the OCT and is used by Alipay+ as the settlement currency in reconciliation. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is | |
payeeAmount | No | The amount of funds that Alipay+ transfers to the MPP. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is | |
payeeQuote | No | The exchange rate between the currency used by the payer (specified on the payerAmount.currency parameter) and the currency used by the payee (specified on the payeeAmount.currency parameter). This parameter is specified by Alipay+ if the currency used by the payer is different from the currency used by the payee and the value of the originalCreditResult.resultStatus parameter is | |
payer | No | The information about the merchant that pays the tax refund amount, including the merchant ID, merchant legal name, merchant display name, and merchant address. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is More information about child parameters: The payer.merchantDisplayName parameter is specified by Alipay+ if the display name of the merchant is different from the legal name of the merchant. | |
payee | No | The information about the MPP user that receives the tax refund, including the user ID, user login ID, and user name. This parameter is specified by Alipay+ if the value of the originalCreditResult.resultStatus parameter is More information about child parameters: The payee.userLoginId and payee.userName parameters are specified by Alipay+ if the information is returned by the MPP. |
Response parameters
Field | Data type | Required | Description |
result | Yes | The result of the notification, including the result status, result code, and result message. For more information about how to respond to the notification, see How to return the result. |
How to return the result
The ACQP needs to return the result (specified in the result parameter) according to the result of receiving the notification.
If you received the notification successfully, set the value of result.resultStatus 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.
For more information about how to define your result codes, see the Result codes section below.
Result codes
Result code | Result status | Result message |
SUCCESS | S | Success |
ACCESS_DENIED | F | Access is denied. |
INVALID_CLIENT | F | The client is invalid. |
INVALID_SIGNATURE | F | The signature is invalid. |
KEY_NOT_FOUND | F | The key is not found. |
MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTPS method. |
NO_INTERFACE_DEF | F | API is not defined. |
PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. |
PROCESS_FAIL | F | A general business failure occurred. Do not retry. |
REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. |
OCT result codes
Result code | Result status | Result message | Further action |
SUCCESS | S | Success | Update the status from the ACQP side. |
BUSINESS_NOT_SUPPORT | F | The original credit transaction business is not supported. | Check whether the parameter values in the request message when you call the createOriginalCredit API, such as payer.referenceMerchantId and payerAmount.currency, conform to the contract. If yes, it is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue; otherwise, correct the parameters to align with the contract. |
CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Ensure that the currencies used in the request message when you call the createOriginalCredit API, such as payerAmount.currency and settlement currency, conform to the contract. If the issue persists, it is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue. |
EXPIRED_CODE | F | The code is expired. | Instruct the user to refresh the tax refund code. |
INVALID_CODE | F | The code is invalid. | Ensure that the tax refund code is valid. If invalid, instruct the user to refresh the tax refund code. |
INVALID_CONTRACT | F | The contract is invalid. | Check whether the parameter values in the request message when you call the createOriginalCredit API, such as payer.referenceMerchantId and payerAmount.currency, conform to the contract. If yes, it is recommended that you contact connect_support@service.alipay.com to troubleshoot the issue; otherwise, correct the parameters to align with the contract. |
RISK_REJECT | F | The request is rejected because of the risk control. | It is recommended that you inform the user of the error. |
USER_AMOUNT_EXCEED_LIMIT | F | The refundable amount exceeds the limit that is specified by the user's digital wallet. | It is recommended that you inform the user of the error. |
USER_KYC_NOT_QUALIFIED | F | User is not qualified for the KYC verification. | It is recommended that you inform the user of the error. |
USER_NOT_EXIST | F | The user does not exist. | It is recommended that you inform the user of the error. |
USER_STATUS_ABNORMAL | F | The user status is abnormal. | It is recommended that you inform the user of the error. |
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": "Global Blue",
"merchantMCC": "5411"
},
"payee": {
"userId": "2102582925174840000",
"userLoginId": "+442056660000*"
},
"originalCreditTime": "2023-01-01T14:48:50+08:00"
}
Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
}
}