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

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.

Body

application/json
​
payment_id
string
required

The payment id against which refund is to be initiated

Required string length: 30
​
amount
integer | null

Total amount for which the refund is to be initiated. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, this will default to the full payment amount

Required range: x > 100
​
merchant_connector_details
object

Merchant connector details used to make payments.

​
merchant_id
string | null

The identifier for the Merchant Account

Maximum length: 255
​
metadata
object | null

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.

​
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 length: 255
​
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
​
refund_type
enum<string>
default:
Instant

To indicate whether to refund needs to be instant or scheduled

Available options:
scheduled,
instant
​
split_refunds
object

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

Response

200 - application/json
​
amount
integer
required

The refund amount, which should be less than or equal to the total payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc

Required range: x > 100
​
connector
string
required

The connector used for the refund and the corresponding payment

​
currency
string
required

The three-letter ISO currency code

​
payment_id
string
required

The payment id against which refund is initiated

​
refund_id
string
required

Unique Identifier for the refund

​
status
enum<string>
required

The status for refunds

Available options:
succeeded,
failed,
pending,
review
​
created_at
string | null

The timestamp at which refund is created

​
error_code
string | null

The code for the error

​
error_message
string | null

The error message

​
merchant_connector_id
string | null

The merchant_connector_id of the processor through which this payment went through

​
metadata
object | null

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

​
profile_id
string | null

The id of business profile for this refund

​
reason
string | null

An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive

​
split_refunds
object

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

​
unified_code
string | null

Error code unified across the connectors is received here if there was an error while calling connector

​
unified_message
string | null

Error message unified across the connectors is received here if there was an error while calling connector

​
updated_at
string | null

The timestamp at which refund is updated

Mandates - Customer Mandates ListRefunds - Update