Refunds - Retrieve

Retrieve details for a refund by its identifier.

Endpoint GET /refunds/{refund_id}

cURL

curl

curl --request GET \
  --url https://sandbox.hyperswitch.io/refunds/{refund_id} \
  --header 'api-key: <api-key>'

Success response (200 application/json)

{
  "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>"
}

Authentication

• Header name: api-key (string, required) Use the API key created under your merchant account from the HyperSwitch dashboard. API key authenticates API requests from your merchant server only. Do not expose this key on a website or embed it in a mobile application.

Path parameters

• refund_id (string, required) — The identifier for the refund

Response fields

• refund_id (string, required) — Unique identifier for the refund

• payment_id (string, required) — The payment id against which the refund is initiated

• amount (integer, required) — The refund amount in the lowest denomination of the currency (e.g., cents for USD, paisa for INR). Amount should be ≤ total payment amount. Required range: x >= 100. Example: 6540

• currency (string, required) — Three-letter ISO currency code

• status (enum, required) — Refund status. Available options: succeeded, failed, pending, review

• connector (string, required) — The connector used for the refund and corresponding payment (example: "stripe")

• reason (string | null) — Arbitrary string attached to the object (useful for display/support)

• metadata (object) — Up to 50 keys; key names up to 40 chars, values up to 500 chars. Useful for storing additional structured info.

• error_message (string | null) — The error message, if any

• error_code (string | null) — The error code, if any

• unified_code (string | null) — Error code unified across connectors, if an error occurred calling the connector

• unified_message (string | null) — Error message unified across connectors

• created_at (string | null) — Timestamp when refund was created

• updated_at (string | null) — Timestamp when refund was updated

• profile_id (string | null) — Business profile id for this refund

• merchant_connector_id (string | null) — The merchant_connector_id of the processor through which this payment went

• split_refunds (object) — Charge-specific fields for controlling revert of funds from platform or connected account. Check sub-fields for details.

  • Example shown:

    • stripe_split_refund:

      • revert_platform_fee: true

      • revert_transfer: true

  • (Options listed in source: Option 1, Option 2, Option 3)

• issuer_error_code (string | null) — Error code received from issuer in case of failed refunds

• issuer_error_message (string | null) — Error message received from issuer in case of failed refunds

• raw_connector_response (string | null) — Contains the whole connector response

Related

• Documentation: https://api-reference.hyperswitch.io/introduction

• Locker API Reference: https://api-reference.hyperswitch.io/locker-api-reference/overview

• Intelligent Router API Reference: https://api-reference.hyperswitch.io/intelligent-router-api-reference/overview

• Source file (suggest edits): https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/refunds/refunds--retrieve.mdx

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

Try other refund endpoints:

• Refunds — Update: https://api-reference.hyperswitch.io/v1/refunds/refunds--update

• Refunds — List: https://api-reference.hyperswitch.io/v1/refunds/refunds--list

Feedback

Was this page helpful?

Yes / No