Alipay+ DocsAlipay+ Docs

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 (MPPis 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:

  1. 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".
  1. 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

Result

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:

  • Maximum length: 64 characters

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 S, which indicates that the OCT is successful.

More information about this field:

  • Maximum length: 64 characters

scenarioType

String

Yes

The business scenario in which the OCT is initiated.

Valid values are:

  • TAX_REFUND: indicates the tax refund scenario.

subScenarioType

String

Yes

The secondary scenario of the business scenario that is specified on the scenarioType parameter.

Valid values are:

  • PORT_INSTANT_TAX_REFUND: indicates the secondary scenario in which users submit tax refund requests at airports, ports, or borders to receive refunds in real time.

originalCreditRequestId

String

Yes

The unique ID that is assigned by the ACQP to identify an OCT.

More information about this field:

  • Maximum length: 64 characters

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 S, which indicates that the OCT is successful.

More information about this field:

  • Maximum length: 64 characters

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 S, which indicates that the OCT is successful.

More information about this field:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

payerAmount

Amount

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 S, which indicates that the OCT is successful.

payeeAmount

Amount

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 S, which indicates that the OCT is successful.

payeeQuote

Quote

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 S, which indicates that the OCT is successful.

payer

Merchant

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 S, which indicates that the OCT is successful.

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

User

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 S, which indicates that the OCT is successful.

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

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

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"
  }
}