Introduction:

This document provides technical details and usage guidelines for integrating UPI Refund API. It includes 3 Refund APIs and Refund Status Check API that enable merchants to process and track refunds.

List of APIs:

  • 1. Original Transaction Refund APIs
    • Allows the merchant to initiate a refund request against a completed UPI transaction.
    • There are 3 refund APIs based on merchant use case a merchant could use them:
      • Standard Refund API
      • Instant Refund API
      • Smart Refund API
  • 2. Refund Status Check API
    • Enables the merchant to check the real-time status of a previously initiated refund.

These APIs are intended for scenarios where:

  1. A customer has paid for goods or services, but the merchant is unable to fulfill the order and initiates a refund.
  2. A customer returns goods due to quality or other issues, and the merchant issues a refund as per their return policy.

 

API Reference:

 

Original Transaction Refund API:

The Original Transaction Refund API allows a merchant to initiate a refund directly against a customer’s UPI transaction ID. It supports both full and partial refunds, depending on the transaction value and refund requirement.

The API also allows the merchant to specify the refund speed at the time of initiation.
1. Standard: Refund will be processed within 3–5 working days.
2. Instant: Refund is credited to the customer instantly.
3. Smart: Refund is processed instantly if system bandwidth is available, otherwise, it is processed under Standard mode.

Process of Refund

1.The merchant has to check UPI transaction status for which he’s willing to initiate refund, for this either could refer to UPI Transaction Callback logs, UPI Transaction Status via UPI Status Check API or Via UPI Transaction Reports available on Merchant Portal, where if the UPI Transaction Status is “SUCCESS” then could proceed with next step to Initiating Refund, else for UPI Transaction status “INITITATED” or “FAILED”, system will not allow to initiate refund

2.Merchant need to Choose Refund Speed by which, willing to refund to the customer, accordingly the merchant has to choose the API to initiate the refund i.e

  • Instant Refund API
  • Standard Refund API
  • Smart Refund API

Note: If a refund request is initiated from any of the above APIs for a specific UPI Transaction ID, subsequent refund requests for the same Transaction ID from any API will not be allowed.

3.On successful initiation of refund the API will provide response as “INITIATED” with Status Code “REIS001” else will get Status “FAILED” to initiate refund with respective failed scenario status code, Kindly refer to Refund Status code Table for all status codes and their description

4.Once refund is initiated successfully the Merchant could check the further status of refund via Refund Status Check API, where initially api will provide status as “INPROGESS” with Status code “REIP001” as its under refund processing queue i.e Instant, Standard or Smart based on initiation and on Successful refund credit to customer the API will provide status as “SUCCESS” with Status code “RESF001” or “FAILED” with respective failed scenario status code.

Note:
1.Refund processing is asynchronous. Merchants are advised to check the final refund status via Callback or Refund Status Check API.

2.In cases where the refund fails with Status Code “REIF009”, merchants may initiate the refund again with the same UPI Transaction ID after 24 hours from the last status check (with Status “FAILED” and Code “REIF009”).

Instant Refund Flow:

instant

Smart Refund Flow:

smart

Standard Refund Flow:

standard

Headers

header_secrets: As per the existing setup

Request Body Parameters

Parameter Description Data type Min Max Mandatory Example Additional Validation
merchant_id Unique identifier of the merchant assigned by Iserveu String 15 15 Yes NSDLM0000000001
  1. Alphanumeric only allowed
  2. No Special Character
  3. Spaces not allowed before first character,after last Character or Inbetween
org_txn_id UPI transaction ID for which merchant is initiating refund to customer Integer 18 18 Yes 537835452729000483
  1. Numeric only allowed
  2. No Special Character
  3. Spaces not allowed before first character,after last Character or Inbetween
org_txn_clientRefId UPI Client Transaction reference ID for which merchant is initiating refund to customer String 10 19 Yes SAMPLEUPI000000078
  1. Alphanumeric only allowed
  2. No Special Character
  3. Spaces not allowed before first character,after last Character or Inbetween
org_txn_rrn Original UPI transaction RRN for which merchant is initiating refund to customer Integer 12 12 Yes 7654788653
  1. Numeric only allowed
  2. No Special Character
  3. Spaces not allowed before first character,after last Character or Inbetween
org_txn_date Original UPI Transaction final Status date and Time Date and Time - - Yes 2019-09-27 10:41:05  
clientRefId Unique refund ID generated by the client for tracking String 10 19 Yes SAMPLEREF0000022
  1. Alphanumeric only allowed
  2. No Special Character
  3. Spaces not allowed before first character,after last Character or Inbetween
remarks Reason for refund String 1 255 Yes Goods are not in stock
  1. All Alphanumeric and special character allowed
  2. Spaces not allowed before first character and after last Character
refund_amount Amount to be refunded (blank implies full refund else merchant could enter amount upto max transacted amount for given transacted Id) Decimal 1 10 No 100
  1. Integer and upto 2 decimal allowed
  2. No alphabet
  3. No Special Character
  4. Spaces not allowed before first character,after last Character or Inbetween
org_txn_date Date of original UPI Transaction Date 20 20 Yes 2019-09-09
  1. Date format(YYYY-MM-DD) only allowed
  2. No alphabet or Special Character other than (-) and integer allowed.
paramA Additional custom parameter(optional) String NA NA NO N/A
  1. All Alphanumeric and special character allowed
  2. Spaces not allowed before first character and after last character.
paramB Additional custom parameter(optional) String NA NA NO N/A
  1. All Alphanumeric and special character allowed
  2. Spaces not allowed before first character and after last character.
paramC Additional custom parameter(optional) String NA NA NO N/A
  1. All Alphanumeric and special character allowed
  2. Spaces not allowed before first character and after last character.

Sample Request Body

Response Body Parameters

Parameter Description Data type Min Max Mandatory Example
merchant_id Unique identifier of the merchant assigned by Iserveu String 15 15 Yes NSDLM0000000001
org_txn_id UPI transaction ID assigned by the processor(iServeU) string 18 18 Yes 537835452729000483
clientRefId Unique refund ID generated by the client for tracking String 10 19 Yes SAMPLEREF0000022
org_txn_clientRefId Original UPI transaction ID from the merchant/client system String 10 19 Yes SAMPLEUPI000000078
org_txn_date Original UPI Transaction final Status date and Time Date and Time - - Yes 2019-09-27 10:41:05
org_txn_rrn Original UPI transaction RRN forvwhich merchant is initiating refund to customer Integer 12 12 Yes 7654788653
refund_id Refund ID generated by the refund system String 18 18 Yes 598767854345675445
refund_amount Refunded amount Decimal 1 10 Yes 100
remarks Reason for the refund String 1 255 Yes Good are not in stock, for which customer paid
req_timestamp Timestamp of refund request triggered by the merchant DateTime 20 20 Yes 2019-09-24 14:21:05
resp_timestamp Timestamp when refund was created in the system DateTime 20 20 Yes 2019-09-24 14:21:05
refund_status Current status of the refund String 5 15 Yes Success
statusCode Status code indicating success or failure of refund process String 10 10 Yes REF001
statusDesc Description of the refund status String 1 100 Yes Refund Processed Succesfully
speed_requested Speed requested by the merchant while initiating the refund String 5 8 Yes STANDARD,INSTANT,SMART

Sample Response Body

 

Individual Refund Status Check:

 

The Individual Refund Status Check API allows the merchant to check the real-time status of a refund initiated to the customer by passing the required identifiers such as refund date and client refund ID.

Headers

header_secrets: As per the existing setup

Request Body Parameters

Parameter Description Data type Min Max Mandatory Example
productCode Code representing the product type for which refund was initiated String 10 10 Yes UPI_REFUND
txnDate Date on which the refund was initiated Date(YYYY-MM-DD) 10 10 Yes 2025-04-10
clientRefId Unique refund identifier generated by the merchant/client String 10 19 Yes CLIENT_REFUND_ID

Sample Request Body

Response Body Parameters

Parameter Description Data type Min Max Mandatory Example
merchant_id Unique identifier of the merchant assigned by Iserveu String 15 15 Yes NSDLM0000000001
org_txn_id UPI transaction ID assigned by the processor(iServeU) string 18 18 Yes 537835452729000483
clientRefId Unique refund ID generated by the client for tracking String 10 19 Yes SAMPLEREF0000022
org_txn_clientRefId Original UPI transaction ID from the merchant/client system String 10 19 Yes SAMPLEUPI000000078
org_txn_date Original UPI Transaction final Status date and Time Date and Time - - Yes 2019-09-27 10:41:05
refund_id Refund ID generated by the refund system String 18 18 Yes 598767854345675445
bank_refund_id Refund ID generated by the NPCI for refund String 18 18 Yes 598767854345675445
refund_amount Refunded amount Decimal 1 10 Yes 100
refund_rrn RRNgenerated for Refund Integer 12 12 Yes 876543675765
remarks Reason for the refund String 1 255 Yes Good are not in stock, for which customer paid
refund_createDate Timestamp of refund request entered by the merchant DateTime 20 20 Yes 2019-09-24 14:21:05
refund_updateDate Timestamp when refund status was updated by system DateTime 20 20 Yes 2019-09-24 14:21:05
refund_status Current status of the refund String 5 15 Yes Success
statusCode Status code indicating success or failure of refund process String 10 10 Yes REF001
statusDesc Description of the refund status String 1 100 Yes Refund Processed Succesfully
speed_processed Actual speed at which refund was processed by the system String 5 8 Yes STANDARD,INSTANT,SMART
speed_requested Speed requested by the merchant while initiating the refund String 5 8 Yes STANDARD,INSTANT,SMART

Sample Response Body

 

Status Code and Descriptions:

Status Reason StatusCode Status Desciption Response at API
Initiated Refund Created Successfully REIS001 Refund Created Successfully Initiate Refund
Success Refund Successfully RESF001 Refund Successfully Status Check
Inprogress Refund has successfully created, but in system refund queue REIP001 Refund Inprogress Status Check
Failed Product Code REEF0001 Product Code is invalid. Status Check
Failed txnDate REEF0002  Refund date does not match the given client reference id or is invalid. Status Check
Failed clientRefId REEF0003 Refund Client reference ID not available or is invalid Status Check
Failed Invalid Merchant ID REIF001 Merchant ID not found or is invalid. Initiate Refund
Failed org_txn_id or UPI Transaction ID not found REIF002 Original UPI Transaction ID not found or is invalid. Initiate Refund
Failed org_txn_clientRefId does not match the given UPI transaction or validation failed REIF003 Client Reference ID does not match the given UPI transaction or is invalid. Initiate Refund
Failed refund_amount not equal to original transaction amount or validation failed REIF004 Refund amount does not match the given UPI transaction amount or is invalid. Initiate Refund
Failed remarks Validation failed REIF005 Remark is invalid. Initiate Refund
Failed Org_txn_date not equal to original transaction date or validation failed REIF006 Original UPI transaction date does not match the given UPI transaction or is invalid. Initiate Refund
Failed clientRefId validation REIF007 Client reference ID already exists or is invalid. Initiate Refund
Failed Refund request failed due to system or bank/NPCI issue. REIF009 Refund request failed due to system or bank/NPCI issue. Initiate Refund
Failed org_txn_rr REIF008 Original UPI transaction RRN does not match the given UPI transaction or is invalid. Initiate Refund, Status Check
Failed ParamA validation failed REIF010 ParamA is invalid. Initiate Refund
Failed ParamB validation failed REIF011 ParamB is invalid. Initiate Refund
Failed ParamC validation failed REIF012 ParamC is invalid. Initiate Refund
Failed NewRefund cannot be initiated as full refund already processed. REIF013 Refund cannot be initiated, full amount already refunded. Initiate Refund
Failed NewRefund cannot be initiated as another refund is in progress with same UPI transaction ID REIF014 Another refund is already in progress for the given UPI transaction. Initiate Refund
Failed Transaction not eligible for refund REIF015 Refund not allowed for in progress or failed UPI transactions. Initiate Refund
RESERVED Reserved REIF016 __ —
Failed Refund window expired (Max 45 day from Org UPI Transaction Date) REIF017 Refund not allowed as the refund window has expired. Initiate Refund
Failed Insufficient balance in merchant account REIF018 Refunds failed due to insufficient balance in the merchant account. Initiate Refund, Status Check
Failed org_txn_rrn does not match the given UPI transaction or validation failed REIF019 Original UPI transaction RRN does not match the given UPI transaction or is invalid. Initiate Refund
Failed Any error getting from Bank/ NPCI regarding Beneficiary Account Details. Publish same error message along with BANK/NPCI error code in given format REIF098 Bank/NPCI error code: XXXXXXX, message: XXXX XXXX XXXX Initiate Refund, Status Check
Failed One Partner tried to initiate refund for another partner Merchant. REIF099 Refund not allowed. Initiate Refund

Status Codes Abbreviations

  1. REIS – Refund Initiated Successfully
    Refund has been successfully initiated from the system. Awaiting confirmation from bank.
  2. REIP – Refund In Progress
    Refund request has been received and is currently being processed. Final status will be shared once completed.
  3. REIF – Refund Failed (for both Initiation Failed and Inprogress Failed)
    Refund attempt was unsuccessful. Check the corresponding Status Code and Status Description for the reason.
  4. RESF – Refund Successful
    Refund has been successfully processed and credited to the customer’s account.
  5. REEF – Refund Enquiry Failed
    Refund enquiry failed.