adjustRefund

The adjustRefund API is used by Alipay+ to send a request to the Mobile Payment Provider (MPP) to initiate either an unlinked refund or an excess refund in the NFC payment scenario. The MPP then returns the refund result to Alipay+.

Unlinked refund: A refund that is not associated with any prior payment.
Excess refund: A refund amount that exceeds the original payment amount.

Note: The MPP is theoretically not allowed to return a failure result, except for some technical reasons, such as parameter exceptions or signature verification failures. For more information about technical failure results, see Result/Error codes section.

The refund process differs based on the type of sub-scenario:

If subScenarioType is EXCEED_REFUND, Alipay+ calls the adjustRefund API to initiate a request to refund the difference between the merchant refund amount and payment amount (amount difference = merchant refund amount - payment amount), and calls the refund API to refund the payment amount.
If subScenarioType is UNLINKED_REFUND, Alipay+ calls the adjustRefund API to initiate a request to refund the total refund amount.

Note: The Mobile Payment Provider (MPP) is also known as the Payment Service Provider (PSP). For example, pspId refers to 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: 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 take one of the following actions:
Exclude the parameters from the request body.
Set the parameter 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

originalCreditRequestId string REQUIRED

The unique ID that is assigned by Alipay+ to identify a refund.

More information:

This field is an API idempotency field. For requests that are initiated with the same originalCreditRequestId, the MPP must return the same result.
Maximum length: 64 characters

initialOriginalCreditId String REQUIRED

The unique ID that is assigned by the ACQP to identify a refund.

More information:

Maximum length: 64 characters

associateDebitRequestId String CONDITIONAL

The unique ID that is assigned by Alipay+ to identify an associated debit transaction. The parameter is required when scenarioType is REFUND and subScenarioType is EXCEED_REFUND.

acquirerId String REQUIRED

The unique ID that is assigned by Alipay+ to identify an ACQP.

More information:

Maximum length: 64 characters

pspId String REQUIRED

The unique ID that is assigned by Alipay+ to identify an MPP.

More information:

Maximum length: 64 characters

payeeAmount Amount REQUIRED

The refund amount that the MPP settles to Alipay+ for this refund, in the MPP's currency.

More information:

Value range: 1 - unlimited

Show child parameters

payerAmount Amount REQUIRED

The refund amount that is paid by the MPP for this refund, in the payment currency, also known as transaction currency.

Show child parameters

quote Quote

The exchange rate between payerAmount and payeeAmount.

This parameter is specified by Alipay+ if the value of the payeeAmount.currency parameter is not the same as that of the payerAmount.currency parameter.

Show child parameters

payer Merchant REQUIRED

The information about the merchant that pays the refund amount, including the merchant ID, legal name, display name, and address.

More information about the child parameters:
Specify the payer.merchantDisplayName parameter if the merchant display name is different from the legal name.
If payer.merchantDisplayName is not specified, the value of the payer.merchantName parameter is used.

Show child parameters

payee User REQUIRED

The information about the MPP user who receives the refund, including the user ID, user login ID, and user name.

Show child parameters

scenarioType String REQUIRED

The business scenario in which the credit transaction is initiated.

Valid value is:

REFUND: Indicates the refund scenario.

subScenarioType String REQUIRED

The detailed business scenario that is specified on the scenarioType parameter.

Valid values are:

UNLINKED_REFUND: indicates that the refund is not associated with any prior payment.
EXCEED_REFUND: indicates that the refund amount is greater than the amount of the payment.

isDomestic Boolean REQUIRED

Specifies whether the refund is domestic. By default, the value of this parameter is false.

env Env

The environment information of the payer's device during the refund.

It is highly recommended to specify this parameter for anti-money laundering, fraud detection, and refund success rate improvement.

Show child parameters

memo String

An additional message provided by the payer about the refund, which will be displayed on the user's electronic bill in their wallet apps.

Specify this parameter if the user's electronic bill is required to display the corresponding message.

More information:

Maximum length: 64 characters

Response parameters

result Result REQUIRED

The result of the refund, including the result status, result code, and the result message.

For more information about how to return the result of the adjustRefund API, see How to return the result.

Show child parameters

originalCreditId String

The unique ID that is assigned by the MPP to identify a refund.

Return this parameter if the value of the result.resultStatus parameter is S, which indicates that the refund is successful.

More information:

Maximum length: 64 characters

API Explorer

Request

Request Body

Response

Response Body

Samples

Unlinked refund samples

See the API explorer for the samples.

Excess refund samples

Alipay+ sends a refund request to the MPP.

Sample Code

The MPP returns the response to Alipay+.

Sample Code

How to return the result

The MPP must return the result based on the refund processing result as follows:

If the refund succeeds: Set result.resultStatus to S and result.resultCode to SUCCESS.
If the refund fails: Set result.resultStatus to F and assign the appropriate value to result.resultCode.
If the refund result is unknown: Set result.resultStatus to U and assign the appropriate value to result.resultCode.

For more information about how to define your result codes, see the Result/Error codes section below.

Note: If the value of result.resultStatus is not S in the response, Alipay+ will automatically retry the adjustRefund request with the same originalCreditRequestId. The MPP must ensure idempotency in such cases.

Result/Error codes

Code	Value	Message
SUCCESS	S	Success
ACCESS_DENIED	F	Access is denied.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.
INVALID_CLIENT	F	The client is invalid.
INVALID_ORDER_STATUS	F	The order status is invalid for this operation.
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 or invalid date.
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.
UNKNOWN_EXCEPTION	U	An API call failed due to unknown reasons.