POST
/
v2
/
refunds
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/refunds \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 654,
  "merchant_reference_id": "ref_123",
  "payment_id": "{{payment_id}}",
  "refund_type": "instant"
}'
{
  "id": "<string>",
  "payment_id": "<string>",
  "merchant_reference_id": "ref_mbabizu24mvu3mela5njyhpit4",
  "amount": 6540,
  "currency": "AED",
  "status": "succeeded",
  "reason": "<string>",
  "metadata": {},
  "error_details": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "connector": "authipay",
  "profile_id": "<string>",
  "merchant_connector_id": "<string>",
  "connector_refund_reference_id": "<string>"
}

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 initiated

Required string length: 30
Example:

"pay_mbabizu24mvu3mela5njyhpit4"

​
merchant_reference_id
string
required

Unique Identifier for the Refund given by the Merchant.

Required string length: 1 - 64
Example:

"ref_mbabizu24mvu3mela5njyhpit4"

​
merchant_id
string | null

The identifier for the Merchant Account

Maximum 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. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, this will default to the amount_captured of the payment

Required range: x >= 100
Example:

6540

​
reason
string | null

Reason for the refund. Often useful for displaying to users and your customer support executive.

Maximum length: 255
Example:

"Customer returned the product"

​
refund_type
enum<string>
default:Instant

To indicate whether the refund needs to be instant or scheduled

Available options:
scheduled,
instant
​
metadata
object | null

Metadata is useful for storing additional, unstructured information on an object.

​
merchant_connector_details
object

Merchant connector details

Response

Refund created

​
id
string
required

Global Refund Id for the refund

​
payment_id
string
required

The payment id against which refund is initiated

​
amount
integer
required

The refund amount

Required range: x >= 100
Example:

6540

​
currency
enum<string>
required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options:
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
​
status
enum<string>
required

The status for refunds

Available options:
succeeded,
failed,
pending,
review
​
created_at
string<date-time>
required

The timestamp at which refund is created

​
updated_at
string<date-time>
required

The timestamp at which refund is updated

​
connector
enum<string>
required
Available options:
authipay,
adyenplatform,
stripe_billing_test,
phonypay,
fauxpay,
pretendpay,
stripe_test,
adyen_test,
checkout_test,
paypal_test,
aci,
adyen,
affirm,
airwallex,
amazonpay,
archipel,
authorizedotnet,
bambora,
bamboraapac,
bankofamerica,
barclaycard,
billwerk,
bitpay,
bluesnap,
blackhawknetwork,
bluecode,
boku,
braintree,
breadpay,
cashtocode,
celero,
chargebee,
checkbook,
checkout,
coinbase,
coingate,
custombilling,
cryptopay,
ctp_mastercard,
ctp_visa,
cybersource,
datatrans,
deutschebank,
digitalvirgo,
dlocal,
dwolla,
ebanx,
elavon,
facilitapay,
fiserv,
fiservemea,
fiuu,
flexiti,
forte,
getnet,
globalpay,
globepay,
gocardless,
gpayments,
hipay,
helcim,
hyperswitch_vault,
inespay,
iatapay,
itaubank,
jpmorgan,
juspaythreedsserver,
klarna,
mifinity,
mollie,
moneris,
multisafepay,
netcetera,
nexinets,
nexixpay,
nmi,
nomupay,
noon,
nordea,
novalnet,
nuvei,
opennode,
paybox,
payload,
payme,
payone,
paypal,
paysafe,
paystack,
paytm,
payu,
peachpayments,
phonepe,
placetopay,
powertranz,
prophetpay,
rapyd,
razorpay,
recurly,
redsys,
santander,
shift4,
silverflow,
square,
stax,
stripe,
stripebilling,
taxjar,
threedsecureio,
tokenio,
trustpay,
tsys,
vgs,
volt,
wellsfargo,
wise,
worldline,
worldpay,
worldpayvantiv,
worldpayxml,
signifyd,
plaid,
riskified,
xendit,
zen,
zsl
​
profile_id
string
required

The id of business profile for this refund

​
merchant_connector_id
string
required

The merchant_connector_id of the processor through which this payment went through

​
merchant_reference_id
string | null

Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refunds initiated against the same payment.

Required string length: 30
Example:

"ref_mbabizu24mvu3mela5njyhpit4"

​
reason
string | null

An arbitrary string attached to the object

​
metadata
object | null

Metadata is useful for storing additional, unstructured information on an object

​
error_details
object
​
connector_refund_reference_id
string | null

The reference id of the connector for the refund