> ## Documentation Index > Fetch the complete documentation index at: https://api-reference.hyperswitch.io/llms.txt > Use this file to discover all available pages before exploring further. # Refunds - Create > Creates a refund against an already processed payment. In case of some processors, you can even opt to refund only a partial amount multiple times until the original charge amount has been refunded ## OpenAPI ````yaml post /v2/refunds openapi: 3.0.3 info: title: Hyperswitch - API Documentation description: > ## Get started Hyperswitch provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment referred to "sandbox", which you can setup to test API calls without affecting production data. Currently, our sandbox environment is live while our production environment is under development and will be available soon. You can sign up on our Dashboard to get API keys to access Hyperswitch API. ### Environment Use the following base URLs when making requests to the APIs: | Environment | Base URL | |---------------|------------------------------------| | Sandbox | | | Production | | ## Authentication When you sign up on our [dashboard](https://app.hyperswitch.io) and create a merchant account, you are given a secret key (also referred as api-key) and a publishable key. You may authenticate all API requests with Hyperswitch server by providing the appropriate key in the request Authorization header. | Key | Description | |-----------------|-----------------------------------------------------------------------------------------------| | api-key | Private key. Used to authenticate all API requests from your merchant server | | publishable key | Unique identifier for your account. Used to authenticate API requests from your app's client | Never share your secret api keys. Keep them guarded and secure. contact: name: Hyperswitch Support url: https://hyperswitch.io email: support.global@juspay.io license: name: Apache-2.0 version: 0.1.0 servers: - url: https://sandbox.hyperswitch.io description: Sandbox Environment security: [] tags: - name: Merchant Account description: Create and manage merchant accounts - name: Profile description: Create and manage profiles - name: Merchant Connector Account description: Create and manage merchant connector accounts - name: Payments description: Create and manage one-time payments, recurring payments and mandates - name: Refunds description: Create and manage refunds for successful payments - name: Mandates description: Manage mandates - name: Customers description: Create and manage customers - name: Payment Methods description: Create and manage payment methods of customers - name: Disputes description: Manage disputes - name: API Key description: Create and manage API Keys - name: Payouts description: Create and manage payouts - name: payment link description: Create payment link - name: Routing description: Create and manage routing configurations - name: Event description: Manage events paths: /v2/refunds: post: tags: - Refunds summary: Refunds - Create description: >- Creates a refund against an already processed payment. In case of some processors, you can even opt to refund only a partial amount multiple times until the original charge amount has been refunded operationId: Create a Refund requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundsCreateRequest' examples: Create an instant refund to refund partial amount: value: amount: 654 merchant_reference_id: ref_123 payment_id: '{{payment_id}}' refund_type: instant Create an instant refund to refund the whole amount: value: merchant_reference_id: ref_123 payment_id: '{{payment_id}}' refund_type: instant Create an instant refund with reason: value: amount: 6540 merchant_reference_id: ref_123 payment_id: '{{payment_id}}' reason: Customer returned product refund_type: instant required: true responses: '200': description: Refund created content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: Missing Mandatory fields content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseOpenApi' security: - api_key: [] components: schemas: RefundsCreateRequest: type: object required: - payment_id - merchant_reference_id properties: payment_id: type: string description: The payment id against which refund is initiated example: pay_mbabizu24mvu3mela5njyhpit4 maxLength: 30 minLength: 30 merchant_reference_id: type: string description: Unique Identifier for the Refund given by the Merchant. example: ref_mbabizu24mvu3mela5njyhpit4 maxLength: 64 minLength: 1 merchant_id: type: string description: The identifier for the Merchant Account example: y3oqhf46pyzuxjbcn2giaqnb44 nullable: true maxLength: 255 amount: type: integer format: int64 description: >- 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 example: 6540 nullable: true minimum: 100 reason: type: string description: >- Reason for the refund. Often useful for displaying to users and your customer support executive. example: Customer returned the product nullable: true maxLength: 255 refund_type: allOf: - $ref: '#/components/schemas/RefundType' default: Instant nullable: true metadata: type: object description: >- Metadata is useful for storing additional, unstructured information on an object. nullable: true merchant_connector_details: allOf: - $ref: '#/components/schemas/MerchantConnectorAuthDetails' nullable: true return_raw_connector_response: type: boolean description: If true, returns stringified connector raw response body nullable: true additionalProperties: false RefundResponse: type: object required: - id - payment_id - amount - currency - status - created_at - updated_at - connector - profile_id - merchant_connector_id properties: id: type: string description: Global Refund Id for the refund payment_id: type: string description: The payment id against which refund is initiated merchant_reference_id: type: string description: >- Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refunds initiated against the same payment. example: ref_mbabizu24mvu3mela5njyhpit4 nullable: true maxLength: 30 minLength: 30 amount: type: integer format: int64 description: The refund amount example: 6540 minimum: 100 currency: $ref: '#/components/schemas/Currency' status: $ref: '#/components/schemas/RefundStatus' reason: type: string description: An arbitrary string attached to the object nullable: true metadata: type: object description: >- Metadata is useful for storing additional, unstructured information on an object nullable: true error_details: allOf: - $ref: '#/components/schemas/RefundErrorDetails' nullable: true created_at: type: string format: date-time description: The timestamp at which refund is created updated_at: type: string format: date-time description: The timestamp at which refund is updated connector: $ref: '#/components/schemas/Connector' profile_id: type: string description: The id of business profile for this refund merchant_connector_id: type: string description: >- The merchant_connector_id of the processor through which this payment went through connector_refund_reference_id: type: string description: The reference id of the connector for the refund nullable: true raw_connector_response: type: string description: Contains raw connector response nullable: true GenericErrorResponseOpenApi: type: object required: - error_type - message - code properties: error_type: type: string example: invalid_request message: type: string example: 'Missing required param: {param}' code: type: string example: IR_04 RefundType: type: string description: To indicate whether the refund needs to be instant or scheduled enum: - scheduled - instant MerchantConnectorAuthDetails: type: object description: Merchant connector details required: - connector_name - merchant_connector_creds properties: connector_name: $ref: '#/components/schemas/Connector' merchant_connector_creds: type: object description: The merchant connector credentials used for the payment Currency: type: string description: >- The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment. enum: - 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 RefundStatus: type: string description: The status for refunds enum: - succeeded - failed - pending - review RefundErrorDetails: type: object required: - code - message properties: code: type: string message: type: string Connector: type: string enum: - absa_sanlam - 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 - calida - boku - braintree - breadpay - cardinal - cashtocode - celero - chargebee - checkbook - checkout - coinbase - coingate - custombilling - cryptopay - ctp_mastercard - ctp_visa - cybersource - cybersourcedecisionmanager - datatrans - deutschebank - digitalvirgo - dlocal - dwolla - ebanx - envoy - elavon - facilitapay - finix - fiserv - fiservemea - fiservcommercehub - fiuu - flexiti - forte - getnet - gigadat - globalpay - globepay - gocardless - gpayments - hipay - helcim - hyperpg - hyperswitch_vault - interpayments - inespay - iatapay - imerchantsolutions - itaubank - jpmorgan - juspaythreedsserver - klarna - loonio - mifinity - mollie - moneris - multisafepay - netcetera - nexinets - nexixpay - nmi - nomupay - noon - nordea - novalnet - nuvei - opennode - paybox - payload - payme - payone - paypal - paysafe - paystack - paytm - payconex - payu - peachpayments - payjustnow - payjustnowinstore - phonepe - placetopay - powertranz - prophetpay - rapyd - razorpay - recurly - redsys - revolv3 - santander - shift4 - silverflow - square - stax - stripe - stripebilling - taxjar - threedsecureio - tesouro - tokenex - tokenio - trustly - truelayer - trustpay - trustpayments - tsys - tsys_transit - vgs - volt - wellsfargo - wise - worldline - worldpay - worldpayvantiv - worldpayxml - worldpaymodular - signifyd - plaid - riskified - xendit - zen - zift - zsl securitySchemes: api_key: type: apiKey in: header name: Authorization description: >- Format: `api-key=` 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. ````