---
page_source: https://juspay.io/in/docs/upi-plugin-direct-psp/android/base-integration/udir-refund-360
page_title: UDIR Refund 360
---

## API Version: V1


# Merchant Refund 360



This api can be used to trigger a refund against a successful complaint resolve and if the transaction is successful. There are two types of refunds supported - `ONLINE` and `OFFLINE`. `ONLINE` refunds get credited to remitter account instantly, whereas `OFFLINE` refunds take around 3-5 working days.

Refund360 will be used for initiating a new refund or getting the status of an existing refund. If the "refundRequestId" is present with the PSP, then the latest status of the existing refund will be returned. If not present, then a new refund will be triggered.

> **Note**
> This is an idempotent api.Use --header x-api-version: 3 to get gatewayRefundTransactionId and merchantRequestId in response.
> 
> 

## Endpoints:
- Production: {{host}}/api/n2/merchants/transactions/refund360

## Request Type: 
POST

## Sample Code Snippets:
### Code Snippets:

#### Shell Code Snippet:

```shell
{"success":false,"message":"No Data found for the given path"}
```

### Sample Request and Response:

#### Request:
```json
{"success":false,"message":"No Data found for the given path"}
```

#### Response:
```json
{"success":false,"message":"No Data found for the given path"}
```

## Body Parameters:
### Basic Params:

#### originalupiRequestId:
- Description: UPI request id for the original transaction against which refund is being initiated.**Constraints:** Max**** 35 characters alphanumeric.
- Tags: String, Optional

#### refundRequestId:
- Description: Merchant generated unique id for the refund.

**Constraints:** Max**** 35 characters alphanumeric, can also contain hyphen(-), dot(.) & underscore(_)
- Tags: String, Mandatory

#### refundType:
- Description: Type of refund being initiated. 

**Constraints:** OFFLINE, ONLINE,UDIR
- Tags: String, mandatory

#### refundAmount:
- Description: The amount to be refunded

**Constraints:** String with mandatory two decimals
- Tags: String, Mandatory

#### merchantRefundVpa:
- Description: Merchant refund vpa that is to be used for online refund.

**Constraint** : mandatory for **refundType = ONLINE** 
- Tags: String, Conditional

#### remarks:
- Description: Remarks or reason for the refund.**Constraints:** The transaction note must be alphanumeric, with a **minimum length of 1 character and a maximum length of 50**  characters.
- Tags: String, Mandatory

#### originalTransactionTimestamp:
- Description: Timestamp of the original transaction. Passing this parameter will help PSP to optimize the refund request to reduce the latency of this api.

**Formate** : YYYY-MM-DDTHH:MM:SS+05:30
- Tags: String, Optional

#### iat:
- Description: Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds.

Example: 1496918882000.
- Tags: String, Optional

#### udfParamters:
- Description: Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"**Note** : Few special characters are not allowed. Regex for the characters which are not allowed : **^[^/#-()*!%~`]+$** 
- Tags: Stringified JSON, Optional

#### adjCode:
- Description: Reason Code for complaint sent to NPCI.
- Tags: String, Optional

#### refundUpiRequestId:
- Description: Upi request Id used for refund transaction.

**Constraints:** Max**** 35 characters alphanumeric.
- Tags: String, Optional
## API Responses:
### 200:

#### status:
- Description: PSP status of the API.

**Values:** SUCCESS | FAILURE.
- Tags: String, Mandatory

#### responseCode:
- Description: PSP response code for the API. 

**Values:** Refer Codes Guide in Resource Section.
- Tags: String, Mandatory

#### responseMessage:
- Description: PSP response message for the API. 

**Values:** Refer Codes Guide in Resource Section.
- Tags: String, Mandatory

#### payload:
- Value:
  - **MerchantChannelId**:
    - Description: Unique id for the merchant channel.
      
      **Values:** As passed in request headers.
    - Tags: String, Mandatory
  - **GatewayResponseStatus**:
    - Description: Response status returned by gateway for the refund.
      
      **Values:** String (SUCCESS, PENDING, DEEMED, FAILURE).
    - Tags: String, Mandatory
  - **MerchantId**:
    - Description: Unique id for the merchant.
      
      **Values:** As passed in request headers.
    - Tags: String, Mandatory
  - **GatewayRefundReferenceId**:
    - Description: Reference id returned by the gateway for the refund.
    - Tags: String, Optional
  - **GatewayResponseMessage**:
    - Description: Response message for code returned by gateway for the refund.
    - Tags: String, Mandatory
  - **OriginalMerchantRequestId**:
    - Description: Merchant generated id for the original transaction.
    - Tags: String, Mandatory
  - **GatewayResponseCode**:
    - Description: Response code returned by gateway for the refund.
    - Tags: String, Mandatory
  - **GatewayTransactionId**:
    - Description: UPI request id returned by gateway for the transaction.
      
      **Values:** Same as **originalUpiRequestId**  passed in request.
    - Tags: String, Mandatory
  - **RefundAmount**:
    - Description: The amount to be refunded.
      
      **Values:** As passed in the request body.
    - Tags: String, Mandatory
  - **RefundRequestId**:
    - Description: Merchant generated unique id for the refund.
      
      **Values:** As passed in the request body.
    - Tags: String, Mandatory
  - **TransactionAmount**:
    - Description: The total amount for which original transaction was performed.
      
      **Values:** String with mandatory two decimals.
    - Tags: String, optional
  - **RefundTimestamp**:
    - Description: Timestamp of when refund request was initiated.
      
      **Formate:** String (YYYY-MM-DDTHH:MM:SS+05:30).
    - Tags: String, Mandatory
  - **RefundType**:
    - Description: Type of refund being initiated.
      
      **Values:** As passed in the request body.
    - Tags: String, Mandatory
  - **MerchantRefundVpa**:
    - Description: Merchant refund vpa that is to be used for online refund 
      
      **Values** : mandatory for `refundType = ONLINE`
    - Value:
      - **PartnersSplit**:
        - Description: List of partners for which the split needs to be divided with the value.
        - Value:
          - **PartnerId**:
            - Description: The LSP id provided by the bank.
            - Tags: String, Mandatory
          - **Value**:
            - Description: Split share for LSP account. Decimal Value.
            - Tags: String, Mandatory
        - Tags: String, Conditional
      - **SplitType**:
        - Description: The type of split for this transaction. Can be AMOUNT,  PERCENTAGE, DEFAULT, LATER.
        - Tags: String, Mandatory
      - **MerchantSplit**:
        - Description: Split share for merchant pool account.
        - Tags: String, Optional
    - Tags: json String, optional
  - **RiskScore**:
    - Description: RiskScore shared by NPCI or Bank
    - Tags: String, Optional
  - **GatewayRefundTransactionId**:
    - Description: UpiRequestId for the refund
    - Value: Values: As passed in the request body in refundUpiRequestId.
    - Tags: String, Optional
  - **SubMerchantId**:
    - Description: Unique id for subMerchant. Only if present as a subMerchant.
    - Tags: String, Optional
  - **SubMerchantChannelId**:
    - Description: Unique id for the channel via which request is made. Only if present as a subMerchant.
    - Tags: String, Optional
  - **Remarks**:
    - Description: Remarks or reason as sent in the request.**Values:** As passed in the request body
    - Tags: String, Optional
  - **Crn**:
    - Description: Complaint reference number returned by NPCI.**Values** :14 to 16 characters alphanumeric.
    - Tags: String, Optional
  - **AdjFlag**:
    - Description: Reason flag for complaint sent to NPCI.
    - Tags: String, Optional
  - **AdjCode**:
    - Description: Reason Code for complaint sent to NPCI.
    - Tags: String, Optional
  - **AdjAmount**:
    - Description: Amount of the transaction sent to NPCI.**Values** :Amount in two decimals.
    - Tags: String, Optional
  - **ReqAdjFlag**:
    - Description: Reason flag for complaint sent by NPCI
    - Tags: String, Optional
  - **ReqAdjCode**:
    - Description: Reason Code for complaint sent by NPCI
    - Tags: String, Optional
- Tags: Json, Mandatory

#### udfParameters:
- Description: Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
- Tags: stringified JSON, optional


---

## API Version: Default


# Merchant Refund 360



This api can be used to trigger a refund against a successful merchant transaction. There are two types of refunds supported - **ONLINE**  and **OFFLINE** . 

Refund360 will be used for initiating a new refund or getting the status of an existing refund. If the "merchantRequestId" parameter is present with the PSP, then the latest status of the existing refund will be returned. If not present, then a new refund will be triggered.


### **Refund retry** 



For failed refunds via ONLINE mode, we would recommend keeping **retry logic on hourly basis**  & auto-switching at **5th**  attempt to OFFLINE mode for successfully processing the refund via NPCI Portal.


| Scenarios where we can retry refund | Description |
|---|---|
| Retry with the same refundId | When responseCode is FAILURE and responseMessage is not DUPLICATE_REQUEST |
| Can't retry Online refund at all | responseCode=SUCCESS and gatewayResponseCode="ZH","UX","ZE","ZG","U17" |
| Retry with different refundId | responseCode=FAILURE and responseMessage=DUPLICATE_REQUEST (OR) responseCode=SUCCESS and remaining gatewayResponseCode. |


> **Note**
> 1. If **gatewayResponseCode is RB** , refund must be treated as **PENDING**  & keep doing status check for next 3-5 days to get the final terminal status.
> 2. If **refundType** **is OFFLINE** then request will be queued up till 8am & then go through NPCI offline process by 2pm & terminal callback will be triggered by 10pm. Until this callback, status will be always given as PENDING.
> 3. **ONLINE**  refunds gets credited to remitter account instantly, whereas **OFFLINE**  refunds takes **around 2-3 working days** .
> 4. Refund will be only possible to transactions which have been done in **last 180 days** .
> 5. This is an idempotent api.




### **Refund responseCode** 




| responseCode | HTTP | Meaning |
|---|---|---|
| INVALID_TRANSACTION_ID | 200 | Transaction id on which refund is initiated is not valid |
| UNINITIATED_REQUEST | 200 | Transaction on which refund is initiated was not successful |
| INVALID_REFUND_AMOUNT | 200 | Sum of all the refunds initiated on the transaction exceed the amount of the transaction |
| DUPLICATE_REQUEST | 200 | Same merchantRequestId used for multiple requests. |
## Endpoints:
- Production: {{host}}/api/n2/merchants/transactions/refund360

## Request Type: 
POST

## Sample Code Snippets:
### Code Snippets:

#### Shell Code Snippet:

```shell
{"success":false,"message":"No Data found for the given path"}
```

### Sample Request and Response:

#### Request:
```json
{"success":false,"message":"No Data found for the given path"}
```

#### Response:
```json
{"success":false,"message":"No Data found for the given path"}
```

## Body Parameters:
### Basic Params:

#### merchantRefundVpa:
- Description: Merchant refund vpa that is to be used for online refund.

**Constraint** : mandatory for **refundType = ONLINE** 
- Tags: String, optional

#### originalTransactionTimestamp:
- Description: Timestamp of the original transaction.

Format: YYYY-MM-DDTHH:MM:SS+05:30
- Tags: String, optional

#### originalMerchantRequestId:
- Description: Merchant request id of the original transaction.

**Constraint:** Max**** 35 characters alphanumeric, can also contain hyphen(-), dot(.) & underscore(_)
- Tags: String, Mandatory

#### refundAmount:
- Description: The amount to be refunded.

Constraint: Amount in two decimals. Decimals are mandatory.
- Tags: String, Mandatory

#### refundRequestId:
- Description: Merchant generated unique id for the refund.

Constraints: Max 35 characters alphanumeric.
- Tags: String, Mandatory

#### refundType:
- Description: Type of refund being initiated. 

Value:**** ONLINE / OFFLINE
- Tags: String, Mandatory

#### remarks:
- Description: Remarks or reason for the refund.
- Tags: String, Mandatory

#### iat:
- Description: Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds.

Example: 1496918882000.
- Tags: String, Mandatory

#### udfParameters:
- Description: Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
- Tags: Stringified JSON, Optional
## API Responses:
### 200:

#### status:
- Description: PSP status of the API.

**Values:** SUCCESS | FAILURE.
- Tags: String, Mandatory

#### responseCode:
- Description: PSP response code for the API.

**Values:** Refer Codes Guide in Resource Section.
- Tags: String, Mandatory

#### responseMessage:
- Description: PSP response message for the API.

**Values:** Refer Codes Guide in Resource Section.
- Tags: String, Mandatory

#### payload:
- Value:
  - **MerchantChannelId**:
    - Description: Unique id for the merchant channel.
      
      **Values:** As passed in request headers.
    - Tags: String, Mandatory
  - **GatewayResponseStatus**:
    - Description: Response status returned by gateway for the refund.
      
      **Values:** String (SUCCESS, PENDING, DEEMED, FAILURE).
    - Tags: String, Mandatory
  - **MerchantId**:
    - Description: Unique id for the merchant.
      
      **Values:** As passed in request headers.
    - Tags: String, Mandatory
  - **GatewayRefundReferenceId**:
    - Description: Reference id returned by the gateway for the refund.
    - Tags: String, Mandatory
  - **GatewayResponseMessage**:
    - Description: Response message for code returned by gateway for the refund.
    - Tags: String, Mandatory
  - **MerchantRequestId**:
    - Description: merchant request id of original transaction.
      
      **Mandatory for x-api-version > 0.**
    - Tags: String, optional
  - **GatewayResponseCode**:
    - Description: Response code returned by gateway for the refund.
    - Tags: String, Mandatory
  - **GatewayTransactionId**:
    - Description: UPI request id returned by gateway for the transaction.
      
      **Values:** Same as **originalUpiRequestId**  passed in request.
    - Tags: String, Mandatory
  - **RefundAmount**:
    - Description: The amount to be refunded.
      
      **Values:** As passed in the request body.
    - Tags: String, Mandatory
  - **RefundRequestId**:
    - Description: Merchant generated unique id for the refund.
      
      **Values:** As passed in the request body.
    - Tags: String, Mandatory
  - **TransactionAmount**:
    - Description: The total amount for which original transaction was performed.
      
      Constraint: Amount in two decimals. Decimals are mandatory.
    - Tags: String, Mandatory
  - **RefundTimestamp**:
    - Description: Timestamp of when refund request was initiated.
      
      **Format:**  (YYYY-MM-DDTHH:MM:SS+05:30).
    - Tags: String, Mandatory
  - **RefundType**:
    - Description: Type of refund being initiated.
      
      **Values:** As passed in the request body.
    - Tags: String, Mandatory
  - **RiskScore**:
    - Description: RiskScore shared by NPCI or Bank
    - Tags: String, Optional
  - **GatewayRefundTransactionId**:
    - Description: Upirequestid for refund.
    - Value: Values: As passed in the request body in refundUpiRequestId.
    - Tags: String, Optional
- Tags: Json, Mandatory

#### udfParameters:
- Description: Merchant Defined Parameters

Example: "{\"udf1\":\"value1\",\"udf2\":\"value2\",…}"
- Tags: stringified Json, optional