Refunds - List

POST /refunds/list

Description: Retrieve a list of refunds filtered by time range and other optional criteria.

Example — cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/refunds/list \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "refund_id": "<string>",
  "profile_id": "<string>",
  "limit": 123,
  "offset": 123,
  "amount_filter": {
    "start_amount": 123,
    "end_amount": 123
  },
  "connector": [
    "<string>"
  ],
  "merchant_connector_id": [
    "<string>"
  ],
  "currency": [
    "AED"
  ],
  "refund_status": [
    "succeeded"
  ]
}
'

Successful Response (200)

{
  "count": 1,
  "total_count": 123,
  "data": [
    {
      "refund_id": "<string>",
      "payment_id": "<string>",
      "amount": 6540,
      "currency": "<string>",
      "status": "succeeded",
      "connector": "stripe",
      "reason": "<string>",
      "metadata": {},
      "error_message": "<string>",
      "error_code": "<string>",
      "unified_code": "<string>",
      "unified_message": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "profile_id": "<string>",
      "merchant_connector_id": "<string>",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "<string>",
      "issuer_error_message": "<string>",
      "raw_connector_response": "<string>"
    }
  ]
}

Authorization

• Header: api-key (string) — required Use the API key from your HyperSwitch dashboard. This key authenticates requests from your merchant server only. Do not expose it publicly (e.g., in client-side code or mobile apps).

Request Body (application/json)

A type representing a range of time for filtering, including a mandatory start_time and an optional end_time.

• start_time (string) — required The start time to filter the refunds list. To get available filters, start_time must be provided.

• end_time (string | null) — optional The end time to filter the refunds list. If not provided, defaults to now.

• payment_id (string | null) — optional The identifier for the payment.

• refund_id (string | null) — optional The identifier for the refund.

• profile_id (string | null) — optional The identifier for the business profile.

• limit (integer | null) — optional Limit on the number of objects to return.

• offset (integer | null) — optional The starting point within a list of objects.

• amount_filter (object) — optional Attributes:

  • start_amount (number)

  • end_amount (number)

• connector (string[] | null) — optional List of connectors to filter refunds.

• merchant_connector_id (string[] | null) — optional List of merchant connector ids to filter refunds for a selected label.

• currency (enum[] | null) — optional List of currencies to filter refunds. The field uses three-letter ISO 4217 currency codes (e.g., "USD", "EUR").

Available currencies (click to expand)

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

• refund_status (enum[] | null) — optional List of refund statuses to filter the refunds list. Available options:

  • succeeded

  • failed

  • pending

  • review

Response (200 — application/json)

List of refunds.

• count (integer) — required The number of refunds included in the response. (Range: x >= 0)

• total_count (integer) — required The total number of refunds matching the query.

• data (object[]) — required The array of refund response objects (see example above for fields in each refund object).

Links

• Edit docs: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/refunds/refunds--list.mdx

• Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/refunds/refunds--list

Related endpoints

• Refunds — Retrieve: https://api-reference.hyperswitch.io/v1/refunds/refunds--retrieve

• Disputes — Retrieve Dispute: https://api-reference.hyperswitch.io/v1/disputes/disputes--retrieve