# refund (NFC Payment)

Alipay+ uses the **refund** API to initiate a refund of a successful payment.

**Note**: In the following sections, the Mobile Payment Provider (MPP) is also known as 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](api_overview#3mLq0)
-   [Response header](api_overview#YdmVS)

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

#### acquirerId (String, REQUIRED)

The unique ID that is assigned by Alipay+ to identify an Acquiring Partner (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

#### paymentRequestId (String, REQUIRED)

The request ID of the payment to be refunded, assigned by Alipay+ to identify the original payment order.

More information:

- Maximum length: 64 characters

#### paymentId (String, REQUIRED)

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

More information:

- Maximum length: 64 characters

#### refundRequestId (String, REQUIRED)

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

More information:

- This field is an API idempotency field.The MPP must regard the requests with the same refundRequestId as repeated and process them only once. The MPP is recommended to check the consistency of the following key request parameters: refundAmount, refundFromAmount, refundPromoInfo, and surchargeInfo. If any values differ from the previous request, the MPP needs to return the REPEAT_REQ_INCONSISTENT result code.
- Maximum length: 64 characters

#### refundAmount (Amount, REQUIRED)

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

**Important**: The value of the _refundAmount.currency_ parameter must be the same as the value of the _paymentAmount.currency_ parameter of the original payment order.

##### 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 as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1.

More information:

- Value range: 1 - unlimited

#### refundFromAmount (Amount, REQUIRED)

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

**Important**: The value of the _refundFromAmount.currency_ parameter must be the same as the value of the _payToAmount.currency_ parameter of the original payment order.

##### 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 as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1.

More information:

- Value range: 1 - unlimited

#### refundQuote (Quote)

The exchange rate between the refund amount (_refundAmount_) and the refund from amount (_refundFromAmount_). 

This parameter is specified by Alipay+ if the value of the _refundAmount_._currency parameter_ is not the same as that of the _refundFromAmount_._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. 

Sometimes, the first currency is the order currency and the second currency is the user's payment currency. Sometimes, the sequence is reversed.

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. 

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

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

##### quoteExpiryTime (Datetime)

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

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

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

#### refundPromoInfo (RefundPromoInfo)

The promotion information related to the refund when a promotional discount is applied in the original payment.

This parameter is specified by Alipay+ if a promotional discount is applied to the original payment and Alipay+ forwards the promotion info to the MPP.

##### refundPromoDetails (Array<RefundPromoDetail>)

The details of a refund that is requested for an order where a promotion is applied.

This parameter is specified by Alipay+ if a promotional discount is applied to the original payment and Alipay+ forwards the promotion info to the MPP.

###### promoId (String, REQUIRED)

The ID of the promotion that is applied to the order for which a refund is requested.

More information:

- Maximum length: 128 characters

###### promoType (String, REQUIRED)

The type of promotion. Valid values are:

-   `INSTANT_DISCOUNT`: indicates an instant discount.
-   `COUPON`: indicates a coupon.

###### refundAmount (Amount, REQUIRED)

The amount that is not refunded because of the related promotion applied to the original payment.

For a full refund, this value equals the original payment's promotional savings. The value of this parameter is the same as that of the _paymentPromoInfo.paymentPromoDetails.savingsAmount.value_ of the original **pay** API request.

For a partial refund, this amount is calculated proportionally based on the actual refund relative to the original order amount, indicating the portion of the promotional savings that is not refunded.

###### 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 as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1.

More information:

- Value range: 1 - unlimited

###### promoName (String, REQUIRED)

The name of the promotion that is applied to the original payment.

More information:

- Maximum length: 128 characters

#### surchargeInfo (SurchargeInfo)

The surcharge information.

This parameter is specified by Alipay+ if a surcharge is applied in the original payment.

##### surchargeAmount (Amout, REQUIRED)

This parameter specifies the actual amount that is paid by the user when a surcharge exists for the payment transaction. This amount is calculated based on _paymentAmount_ and _surchargeQuote_.

**Important**: The amount that the MPP settles to Alipay+ is still _payToAmount_.

###### 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 as listed in [the Current Currency & Funds list](https://www.currency-iso.org/en/home/tables/table-a1.html). In the list, the Minor unit column defines the number of decimals, which determines the smallest unit of a currency. For example, if the currency is USD and the amount is $1.00 (2 decimals), set the value of this parameter to 100; or if the currency is JPY and the amount is ￥1 (0 decimal), set the value of this parameter to 1.

More information:

- Value range: 1 - unlimited

##### surchargeQuote (Quote, REQUIRED)

The exchange rate between _paymentAmount.currency_ and _surchargeAmount.currency_.

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

Sometimes, the first currency is the order currency and the second currency is the user's payment currency. Sometimes, the sequence is reversed.

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. 

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

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

###### quoteExpiryTime (Datetime)

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

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

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

#### refundReason (String)

The reasons for the refund.

This parameter is specified by Alipay+ if the ACQP provides the reason.

More information:

- Maximum length: 256 characters

## Response parameters

#### result (Result, REQUIRED)

The refund result. If this API is successfully called, the refund succeeds. For more information about how to return the refund result, see _How to return the result_.

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

It is recommended that you specify this parameter to provide details about the result.

More information:

- Maximum length: 256 characters

#### refundId (String)

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

Return this parameter if the refund succeeds (the value of the _result_._resultCode_ parameter is `SUCCESS`).

More information:

- Maximum length: 64 characters

#### refundTime (Datetime)

The date and time when the refund reaches a final state of success.

Return this parameter if the refund succeeds (the value of the _result_._resultCode_ parameter is `SUCCESS`).

More information:

- The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00".

## More information

### How are the different amounts calculated

This section introduces how are _refundAmount_, _refundFromAmount_, and _surchargeAmount_ calculated when Alipay+ calls the **refund** API request and provides calculation cases to illustrate the process.

> **Note**: Alipay+ calculates the values of all amounts in the smallest currency unit. For example, if the currency is HKD and the amount is $1.00, the value of the amount is set to 100; or if the currency is JPY and the amount is ￥1, the value of the amount is set to 1.

#### refundAmount

| Refund type | Full refund | Partial refund |
| --- | --- | --- |
| Currency | The currency that is used by Alipay+ to create the payment order that is related to the refund. | The currency that is used by Alipay+ to create the payment order that is related to the refund. |
| Value | The same as the value of the _paymentAmount.value_ parameter in the **pay** API request. | The same as the value of the refund amount that is requested by the ACQP from Alipay+. |

> **Note**: In case of partial refunds, Alipay+ ensures that the total _refundAmount.value_ of all partial refunds does not exceed the value of the _paymentAmount.value_ parameter in the original **pay** API request.

#### refundFromAmount

| Refund type | Full refund | Partial refund |
| --- | --- | --- |
| Currency | The currency that is used by the MPP. | The currency that is used by the MPP. |
| Value | The same as the value of the _payToAmount.value_ parameter in the **pay** API request. | _refundAmount \* refundQuote_ |

> **Note**: In case of partial refunds, Alipay+ ensures that the total _refundFromAmount.value_ of all partial refunds does not exceed the value of the _payToAmount.value_ parameter in the original **pay** API request.

#### surchargeAmount

| Refund type | Full refund | Partial refund |
| --- | --- | --- |
| Currency | The currency that is used by the MPP. | The currency that is used by the MPP. |
| Value | The same as the value of the _surchargeAmount.value_ parameter in the **pay** API request. | _refundAmount \* surchargeQuote_ |

> **Note**: In case of partial refunds, Alipay+ ensures that the total _surchargeAmount.value_ of all partial refunds does not exceed the value of the _surchargeAmount.value_ parameter in the original **pay** API request.

### How to return the result

The MPP needs to return the result (specified on the _result_ parameter) based on the business processing result as follows:

-   If the refund succeeds, set the value of _result.resultStatus_ to `S` and the value of _result.resultCode_ to `SUCCESS`.
-   If the refund fails, set the value of _result.resultStatus_ to `F` and the value of _result.resultCode_ accordingly.
-   If the refund result is unknown, set the value of _result.resultStatus_ to `U` and the value of _result.resultCode_ accordingly.

For more information about how to define your result codes, see the _Result codes_ section below.

## 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. |
| ORDER_NOT_EXIST | F | The order doesn't exist. |
| PARAM_ILLEGAL | F | Illegal parameters. For example, non-numeric input, invalid date. |
| PROCESS_FAIL | F | A general business failure occurred. Do not retry. |
| REFUND_AMOUNT_EXCEED | F | The total refund amount exceeds the payment amount. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. |
| USER_AMOUNT_EXCEED | F | The user balance exceeds the balance limit. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
| UNKNOWN_EXCEPTION | U | An API call failed, which is caused by unknown reasons. |

## Request

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

```json
{
  "acquirerId": "1022188000000000000",
  "pspId": "1022172000000000000",
  "paymentRequestId": "201811291907410100070000000000",
  "paymentId": "201811291907410100070000000000",
  "refundRequestId": "201811291907410200070000000000",
  "refundAmount": {
    "value": "90",
    "currency": "JPY"
  },
  "refundFromAmount": {
    "value": "900",
    "currency": "KRW"
  },
  "refundQuote": {
    "quoteId": "1230000",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  }
}
```

## Response

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "refundId": "201811291907410200070000000000",
  "refundTime": "2020-10-10T12:01:01+08:30"
}
```