Refunds - Create

Create an instant refund to refund partial amount.

POST /refunds

Try it (sandbox)

cURL
curl --request POST \
  --url https://sandbox.hyperswitch.io/refunds \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "refund_type": "Instant"
}
'

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

Errors: 400

Authorizations

  • api-key (string, header, required) Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Request body (application/json)

Fields

  • payment_id (string, required) The payment id against which refund is to be initiated Required string length: 30 Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • refund_id (string | null) Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refunds initiated against the same payment. If this is not passed by the merchant, this field shall be auto generated and provided in the API response. It is recommended to generate uuid(v4) as the refund_id. Required string length: 30 Example: "ref_mbabizu24mvu3mela5njyhpit4"

  • merchant_id (string | null) The identifier for the Merchant Account Maximum string length: 255 Example: "y3oqhf46pyzuxjbcn2giaqnb44"

  • amount (integer | null) Total amount for which the refund is to be initiated. Amount for the payment in lowest denomination of the currency (e.g., cents for USD, paisa for INR). If not provided, this will default to the full payment amount. Required range: x >= 100 Example: 6540

  • reason (string | null) Reason for the refund. Often useful for displaying to users and your customer support executive. In case the payment went through Stripe, this field needs to be passed with one of these enums: duplicate, fraudulent, or requested_by_customer Maximum string length: 255 Example: "Customer returned the product"

  • refund_type (enum, default: Instant) To indicate whether refund needs to be instant or scheduled. Available options: scheduled, instant

  • metadata (object) You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

  • merchant_connector_details (object) Merchant connector details used to make payments.

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

    • Option 1

    • Option 2

    • Option 3

  • all_keys_required (boolean | null) If true, returns stringified connector raw response body

Response (200 — application/json)

Refund created. Fields:

  • refund_id (string, required) Unique Identifier for the refund

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

  • amount (integer, required) The refund amount, which should be less than or equal to the total payment amount. Amount in the lowest denomination of the currency. Required range: x >= 100 Example: 6540

  • currency (string, required) The three-letter ISO currency code

  • status (enum, required) The status for refunds. Available options: succeeded, failed, pending, review

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

  • reason (string | null) An arbitrary string attached to the object.

  • metadata (object) Up to 50 keys; key names up to 40 chars; values up to 500 chars.

  • error_message (string | null) The error message

  • error_code (string | null) The code for the error

  • unified_code (string | null) Error code unified across the connectors if there was an error while calling connector

  • unified_message (string | null) Error message unified across the connectors if there was an error while calling connector

  • created_at (string | null) The timestamp at which refund is created

  • updated_at (string | null) The timestamp at which refund is updated

  • profile_id (string | null) The id of business profile for this refund

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

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

    • Option 1

    • Option 2

    • Option 3

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

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

  • raw_connector_response (string | null) Contains 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

Edit or raise an issue:

  • Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/refunds/refunds--create.mdx

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

PreviousrefundsNextgsm