---
updatedAt: 2025-11-10T23:34:00.000Z
agentTools:
  projectIndex: https://docs.billdesk.io/llms.txt
---

# Retrieve Refund

Merchant can retrieve refund details either by using mercid and merc_refund_ref_no, or the mercid and refundid.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "x-stoplight": {
    "id": "v3t7owhh461u5"
  },
  "servers": [
    {
      "url": "https://uat1.billdesk.com/u2",
      "description": "UAT server"
    },
    {
      "url": "https://api.billdesk.com",
      "description": "PROD server"
    }
  ],
  "info": {
    "title": "Payments",
    "description": "This explorer allows merchants to evaluate APIs that are available in the BillDesk Payment Gateway API suite.\n - Only HMAC authentication is supported.\n - All APIs are RESTful and resource oriented.\n - Servers listed are applicable for the API explorer only.",
    "contact": {
      "name": "API Support",
      "url": "https://www.billdesk.com/helpcenter.htm",
      "email": "support@billdesk.com"
    },
    "version": "2.5"
  },
  "x-samples-languages": [
    "shell",
    "json",
    "node",
    "java",
    "csharp"
  ],
  "paths": {
    "/payments/ve1_2/refunds/get": {
      "parameters": [],
      "post": {
        "summary": "Retrieve Refund",
        "operationId": "retrieveRefund",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "x-examples": {
                    "Example 1": {
                      "objectid": "refund",
                      "refundid": "X45604776418751",
                      "transactionid": "X4560477641875",
                      "orderid": "ORDER202200000001",
                      "mercid": "BDMERCID",
                      "transaction_date": "2022-03-18T11:20:07+05:30",
                      "txn_amount": "2.00",
                      "refund_amount": "2.00",
                      "currency": "356",
                      "refund_date": "2022-03-20T21:27:47+05:30",
                      "merc_refund_ref_no": "REFTS1000004RTEST001",
                      "refund_status": "0799"
                    }
                  },
                  "properties": {
                    "objectid": {
                      "$ref": "#/components/schemas/Objectid"
                    },
                    "refundid": {
                      "type": "string",
                      "description": "Unique refundid created by BillDesk for each refund request",
                      "pattern": "^[A-Za-z0-9]{1,15}$",
                      "example": "X45604776418751"
                    },
                    "transactionid": {
                      "$ref": "#/components/schemas/Transactionid"
                    },
                    "orderid": {
                      "$ref": "#/components/schemas/Orderid"
                    },
                    "mercid": {
                      "$ref": "#/components/schemas/Mercid"
                    },
                    "transaction_date": {
                      "$ref": "#/components/schemas/Transaction_date"
                    },
                    "txn_amount": {
                      "type": "string",
                      "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$",
                      "example": "2400.00",
                      "description": "Original transaction amount in two decimals"
                    },
                    "refund_amount": {
                      "type": "string",
                      "pattern": "^([1-9]{1}[0-9]{0,7}(\\.[0-9]{1,2})?)$",
                      "example": "1100.00",
                      "description": "Refund amount in two decimals"
                    },
                    "currency": {
                      "$ref": "#/components/schemas/Currency"
                    },
                    "refund_date": {
                      "type": "string",
                      "format": "date-time",
                      "description": "BillDesk refund date and time in YYYY-MMDDThh:mm:ssTZD format"
                    },
                    "merc_refund_ref_no": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9\\_\\:\\-]{1,100}$",
                      "example": "REFTS14RTEST001",
                      "description": "Unique reference number created by the merchant for the refund request"
                    },
                    "refund_status": {
                      "type": "string",
                      "description": "Represents the refund status with the following values:\n•\t0799 – categorized as a refund, where the original transaction has been already settled \n•\t0699 – categorized as a cancellation, where the original transaction has not been settled",
                      "enum": [
                        "0699",
                        "0799"
                      ]
                    }
                  }
                },
                "examples": {
                  "Retrieve refund response": {
                    "value": {
                      "objectid": "refund",
                      "refundid": "X45604776418751",
                      "transactionid": "X4560477641875",
                      "orderid": "ORDER202200000001",
                      "mercid": "BDMERCID",
                      "transaction_date": "2022-03-18T11:20:07+05:30",
                      "txn_amount": "2.00",
                      "refund_amount": "2.00",
                      "currency": "356",
                      "refund_date": "2022-03-20T21:27:47+05:30",
                      "merc_refund_ref_no": "REFTS1000004RTEST001",
                      "refund_status": "0799"
                    }
                  }
                }
              }
            },
            "headers": {
              "BD-Traceid": {
                "schema": {
                  "type": "string"
                },
                "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail."
              },
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "description": "Request Content-Type to take the values application/jose"
              },
              "Accept": {
                "schema": {
                  "type": "string"
                },
                "description": "Accept Response Content-Type to take the values application/jose"
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error-object"
                },
                "examples": {
                  "Forbidden": {
                    "$ref": "#/components/examples/403-error"
                  }
                }
              }
            },
            "headers": {
              "BD-Traceid": {
                "schema": {
                  "type": "string"
                },
                "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail."
              },
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "description": "Request Content-Type to take the values application/jose"
              },
              "Accept": {
                "schema": {
                  "type": "string"
                },
                "description": "Accept Response Content-Type to take the values application/jose"
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error-object"
                },
                "examples": {
                  "Internal Server Error": {
                    "$ref": "#/components/examples/500-error"
                  }
                }
              }
            },
            "headers": {
              "BD-Traceid": {
                "schema": {
                  "type": "string"
                },
                "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail."
              },
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "description": "Request Content-Type to take the values application/jose"
              },
              "Accept": {
                "schema": {
                  "type": "string"
                },
                "description": "Accept Response Content-Type to take the values application/jose"
              }
            }
          },
          "default": {
            "description": "Any bad or invalid request will lead to following error object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error-object"
                },
                "examples": {
                  "Invalid merchant config": {
                    "$ref": "#/components/examples/422-Invalid-merchant-config"
                  }
                }
              }
            },
            "headers": {
              "BD-Traceid": {
                "schema": {
                  "type": "string"
                },
                "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail."
              },
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "description": "Request Content-Type to take the values application/jose"
              },
              "Accept": {
                "schema": {
                  "type": "string"
                },
                "description": "Accept Response Content-Type to take the values application/jose"
              }
            }
          }
        },
        "description": "Merchant can retrieve refund details either by using mercid and merc_refund_ref_no, or the mercid and refundid.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Recurring_BdTraceId"
          },
          {
            "$ref": "#/components/parameters/Recurring_BdTimeStamp"
          },
          {
            "$ref": "#/components/parameters/Recurring_Content-Type"
          },
          {
            "$ref": "#/components/parameters/Recurring_Accept"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "x-examples": {
                  "Example 1": {
                    "mercid": "BDMERCID",
                    "refundid": "X45604776418751"
                  }
                },
                "properties": {
                  "mercid": {
                    "$ref": "#/components/schemas/Mercid"
                  },
                  "refundid": {
                    "type": "string",
                    "description": "Unique refundid created by BillDesk for each refund request",
                    "pattern": "^[A-Za-z0-9]{1,15}$",
                    "example": "X45604776418751"
                  },
                  "merc_refund_ref_no": {
                    "type": "string",
                    "description": "Unique reference number created by the merchant for the refund request",
                    "pattern": "^[A-Za-z0-9\\_\\:\\-]{1,100}$",
                    "example": "REFTS14RTEST001"
                  }
                },
                "required": [
                  "mercid"
                ]
              },
              "examples": {
                "Using BillDesk refundid": {
                  "value": {
                    "mercid": "BDMERCID",
                    "refundid": "X45604776418751"
                  }
                },
                "Using merc_refund_ref_no": {
                  "value": {
                    "mercid": "BDMERCID",
                    "merc_refund_ref_no": "REFTS14RTEST001"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Refund"
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "Recurring_Accept": {
        "name": "Accept",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "example": "application/jose"
        },
        "description": "Accept Response Content-Type to take the values application/jose"
      },
      "Recurring_Content-Type": {
        "name": "Content-Type",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "example": "application/json"
        },
        "description": "Request Content-Type to take the values application/jose"
      },
      "Recurring_BdTimeStamp": {
        "in": "header",
        "name": "BD-Timestamp",
        "description": "Request timestamp to identify date and time of origin of request. Example, a value of BD-Timestamp 20210113180403 identifies the request to have originated on 13th January 2021 at 06:04:03 PM.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "20201203182838"
        }
      },
      "Recurring_BdTraceId": {
        "in": "header",
        "name": "BD-Traceid",
        "description": "BD-TraceID is a unique identifier passed by the merchant to ensure request idempotency. Requests with identical BD-TraceID within a 24 hour window would fail.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "20201203182838"
        }
      }
    },
    "examples": {
      "403-error": {
        "value": {
          "status": 403,
          "error_type": "inaccessable_resource_error",
          "error_code": "GNIAE0002",
          "message": "Access forbidden"
        }
      },
      "500-error": {
        "value": {
          "status": 500,
          "error_type": "api_processing_error",
          "error_code": "AUAPE0001",
          "message": "Internal server error"
        }
      },
      "422-Invalid-merchant-config": {
        "value": {
          "status": 422,
          "error_type": "api_validation_error",
          "error_code": "GNAVE0001",
          "message": "Incorrect merchant configuration"
        }
      }
    },
    "schemas": {
      "Error-object": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "This will be same as HTTP response code"
          },
          "error_type": {
            "type": "string",
            "description": "This indicates of the category of errors that could be encountered, for e.g. validation_error, api_connection_error, etc."
          },
          "error_code": {
            "type": "string",
            "description": "Under the error_type, there could be different error_codes that could be returned depending upon the API and the underlying interaction"
          },
          "message": {
            "type": "string",
            "description": "More details as a description for the error_code"
          }
        }
      },
      "Currency": {
        "title": "currency",
        "x-stoplight": {
          "id": "1ehjh4f7vidz7"
        },
        "type": "string",
        "description": "ISO currency code of the transaction amount, for INR this value will be 356"
      },
      "Mercid": {
        "title": "mercid",
        "x-stoplight": {
          "id": "43ns25lu1fyuc"
        },
        "type": "string",
        "pattern": "^[A-Za-z0-9]{1,10}$",
        "example": "BDMERCID",
        "description": "Unique identifier as defined by BillDesk for each merchant"
      },
      "Objectid": {
        "title": "objectid",
        "x-stoplight": {
          "id": "bbwm8bhhbqd4r"
        },
        "type": "string",
        "description": "String representing the object's type. Objects of the same type share the same value. ",
        "enum": [
          "transaction",
          "authentication",
          "mandate",
          "invoice",
          "cardaccount",
          "validatevpa",
          "dispute",
          "settlement",
          "altid",
          "mandate_token",
          "accountvalidation",
          "refund"
        ]
      },
      "Orderid": {
        "title": "orderid",
        "x-stoplight": {
          "id": "lmwrwf7xn6wq8"
        },
        "type": "string",
        "description": "Unique ID generated by the merchant for each request",
        "pattern": "^[-/~A-Za-z0-9\\_ \\:.,#@!\\\\*\\\\+]{1,120}$",
        "example": "TEST0000009005"
      },
      "Transaction_date": {
        "title": "transaction_date",
        "x-stoplight": {
          "id": "d0ekw0quxfwwu"
        },
        "type": "string",
        "description": "BillDesk transaction date and time in YYYY-MM-DDThh:mm:ssTZD format",
        "format": "date-time",
        "example": "2023-03-14T15:14:39+05:30"
      },
      "Transactionid": {
        "title": "transactionid",
        "x-stoplight": {
          "id": "uqizgn6tyoqhg"
        },
        "type": "string",
        "description": "Unique transactionid created by BillDesk ",
        "pattern": "^[A-Za-z0-9]{14,35}$",
        "example": "U4560001099939"
      }
    }
  },
  "tags": [
    {
      "name": "Refund"
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```