# 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:

-   [Request header](https://yuque.antfin-inc.com/buynx2/api_mpp/api_overview#3mLq0)
-   [Response header](https://yuque.antfin-inc.com/buynx2/api_mpp/api_overview#YdmVS)

> **Note:** **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".
>
> 2.  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

##### currency (string, REQUIRED)

The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1.

Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of the value of this parameter as `00`.

More information:

- Value range: 1 - unlimited

#### payerAmount (Amount, REQUIRED)

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

##### currency (String, REQUIRED)

The currency code of the amount. The value of this parameter must be an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, for example, "EUR" for Euros.

More information:

- Maximum length: 3 characters

##### value (Integer, REQUIRED)

The value of the amount as a natural number. By default, the value of this parameter is in the smallest currency unit. For example, if the currency is USD and the amount is $1.00, set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1, set the value of this parameter to 1.

Due to the currency practices in Indonesia, when the currency is IDR, round the amount with banker's rounding and fix the last two digits of the value of this parameter as `00`.

More information:

- Value range: 1 - unlimited

#### 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.

##### quoteId (String, REQUIRED)

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

More information:

- Maximum length: 64 characters

##### quoteCurrencyPair (string, REQUIRED)

A currency pair, of which the first listed currency (also called base currency) is quoted against the second currency (also called quote currency). The value of this parameter is in the format of `{_base_currency_}/{_quote_currency_}`, where `{_base_currency_}` and `{_quote_currency_}` are alphabetic codes that follow the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. For example, if the base currency is euro and the quote currency is dollar, the value of this parameter is EUR/USD.

More information:

- Maximum length: 8 characters

##### quotePrice (Decimal, REQUIRED)

The quotation of the exchange rate between the currency pair that is specified on the _quoteCurrencyPair_ parameter.

> The value is not always greater than or equal to 1 and has a decimal accuracy of 15 places.

More information:

- Maximum length: 32 characters

##### quoteStartTime (Datetime)

The time when the quotation (specified on the _quotePrice_ parameter) takes effect.

##### quoteExpiryTime (Datetime)

The time when the quotation (specified on the _quotePrice_ parameter) expires.

##### baseCurrency (String)

The first currency in the currency pair that is specified on the quoteCurrencyPair parameter. The value is an alphabetic code that follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

More information:

- Maximum length: 3 characters

##### quoteUnit (String)

The amount in the base currency that is specified on the _baseCurrency_ parameter.

More information:

- Maximum length: 12 characters

#### 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.

##### referenceMerchantId (String, REQUIRED)

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

More information:

- Maximum length: 32 characters

##### merchantMCC (String, REQUIRED)

The merchant category code (MCC) that represents the categorization of the merchant's business type. See [Alipay+ MCC Standards](https://docs.alipayplus.com/alipayplus/alipayplus/mcc-standards/overview.md) for details.

More information:

- Maximum length: 4 characters

##### merchantName (String, REQUIRED)

The legal name of the merchant.

More information:

- Maximum length: 256 characters

##### merchantAddress (Address, REQUIRED)

In the Tax Refund scenario, specify the region where the original credit transaction occurs.

###### region (String, REQUIRED)

The region where the address is located. The value of this parameter must be a 2-character country/region code that follows the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard.

More information:

- Maximum length: 2 characters

###### state (String)

The state, country, or province where the address is located.

More information:

- Maximum length: 8 characters

###### city (String)

The city, district, suburb, town, or village where the address is located.

More information:

- Maximum length: 32 characters

###### address1 (String)

The address line 1, which contains the street name, PO box, or company name.

More information:

- Maximum length: 256 characters

###### address2 (String)

The address line 2, which contains the apartment, suite, unit, or building name.

More information:

- Maximum length: 256 characters

###### zipCode (String)

The zip or postal code.

More information:

- Maximum length: 32 characters

##### merchantDisplayName (String)

The display name of the merchant.

More information:

- Maximum length: 64 characters

#### payee (User, REQUIRED)

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

##### userId (String, REQUIRED)

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

More information:

- Maximum length: 21 characters

##### userLoginId (String)

The ID that the user uses to log in to the MPP platform. The ID is assigned by the MPP and is desensitized.

More information:

- Maximum length: 64 characters

##### userName (UserName)

The user name.

###### firstName (String)

The first name of the user.

More information:

- Maximum length: 32 characters

###### middleName (String)

The middle name of the user.

More information:

- Maximum length: 32 characters

###### lastName (String)

The last name of the user.

More information:

- Maximum length: 32 characters

###### fullName (String)

The full name of the user.

More information:

- Maximum length: 128 characters

#### 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.

##### clientIp (String)

The IP address of the client device.

More information:

- Maximum length: 32 characters

##### storeTerminalId (String)

The ID of the terminal device that is used in the store to process the original credit transaction.

More information:

- Maximum length: 64 characters

##### storeTerminalRequestTime (Datetime)

The time when the request is sent by the terminal device that is used in the store.

#### 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_](#HoTSQ).

##### resultCode (String, REQUIRED)

The result code that indicates the detailed processing result.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

The result status that indicates the processing result. Valid values are:

-   `S`: Successful
-   `F`: Failed
-   `U`: Unknown

##### resultMessage (string)

The result message that describes the result code in detail.

More information:

- Maximum length: 256 characters

#### 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

# Samples

#### Unlinked refund samples

See the API explorer for the samples.

#### Excess refund samples

1.  Alipay+ sends a refund request to the MPP.

```json
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "initialOriginalCreditId": "gb_tax_1089760038715669_102775745070000",
  "associateDebitRequestId":"20190608114010800100188820200350001",
  "payeeAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "payerAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "quote": {
    "quoteId": "123000",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice":"10.0000"
  },
  "payer": {
    "referenceMerchantId": "2188245U41144145",
    "merchantAddress": {
      "region": "JP"
    },
    "merchantName": "Merchant Name",
    "merchantMCC": "5411"
  },
  "payee": {
    "userId": "2088245U41144145"
  },
  "scenarioType": "REFUND",
  "subScenarioType": "EXCEED_REFUND",
  "isDomestic":"false"
}
```

2.  The MPP returns the response to Alipay+.

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "originalCreditId": "201000000000000000000000004444"
}
```

# 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. |

## Request

### ALIPAY, ALIPAY_HK, DANA, H5, DIRECT

```json
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "initialOriginalCreditId": "gb_tax_1089760038715669_102775745070000",
  "payeeAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "payerAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "quote": {
    "quoteId": "123000",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  },
  "payer": {
    "referenceMerchantId": "2188245U41144145",
    "merchantAddress": {
      "region": "JP"
    },
    "merchantName": "Merchant Name",
    "merchantMCC": "5411"
  },
  "payee": {
    "userId": "2088245U41144145"
  },
  "scenarioType": "REFUND",
  "subScenarioType": "UNLINKED_REFUND",
  "isDomestic": "false"
}
```

## Response

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "originalCreditId": "201000000000000000000000004444"
}
```