---
title: "Refunds - Create"
method: POST
path: "/refunds"
tags: ["Refunds"]
---

# Refunds - Create

`POST /refunds`

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

## Request body

- RefundRequest
  - `payment_id` string, required — The payment id against which refund is to be initiated
  - `refund_id` string, nullable — 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.
  - `merchant_id` string, nullable — The identifier for the Merchant Account
  - `amount` integer, nullable — 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
  - `reason` string, nullable — 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`
  - `refund_type` 'scheduled' | 'instant' — To indicate whether to refund needs to be instant or scheduled
  - `metadata` object, nullable — 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` MerchantConnectorDetailsWrap — Merchant connector details used to make payments.
    - `creds_identifier` string, required — Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info, like encoded_data in this field. And do not send the string "null".
    - `encoded_data` MerchantConnectorDetails
      - `connector_account_details` object, nullable — Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object.
      - `metadata` object, nullable — Metadata is useful for storing additional, unstructured information on an object.
  - `split_refunds` union — Charge specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for more details.
    - object
      - `stripe_split_refund` StripeSplitRefundRequest, required — Charge specific fields for controlling the revert of funds from either platform or connected account for Stripe. Check sub-fields for more details.
        - `revert_platform_fee` boolean, nullable — Toggle for reverting the application fee that was collected for the payment. If set to false, the funds are pulled from the destination account.
        - `revert_transfer` boolean, nullable — Toggle for reverting the transfer that was made during the charge. If set to false, the funds are pulled from the main platform's account.
    - object
      - `adyen_split_refund` AdyenSplitData, required — Fee information for Split Payments to be charged on the payment being collected for Adyen
        - `store` string, nullable — The store identifier
        - `split_items` AdyenSplitItem[], required — Data for the split items
          - `amount` integer, required — The amount of the split item
          - `split_type` 'BalanceAccount' | 'AcquiringFees' | 'PaymentFee' | 'AdyenFees' | 'AdyenCommission' | 'AdyenMarkup' | 'Interchange' | 'SchemeFee' | 'Commission' | 'TopUp' | 'Vat', required
          - `account` string, nullable — The unique identifier of the account to which the split amount is allocated.
          - `reference` string, required — Unique Identifier for the split item
          - `description` string, nullable — Description for the part of the payment that will be allocated to the specified account.
    - object
      - `xendit_split_refund` XenditSplitSubMerchantData, required — Fee information to be charged on the payment being collected for sub-merchant via xendit
        - `for_user_id` string, required — The sub-account user-id that you want to make this transaction for.
  - `all_keys_required` boolean, nullable — If true, returns stringified connector raw response body

## Response `200`

Refund created

- RefundResponse
  - `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 for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc
  - `currency` string, required — The three-letter ISO currency code
  - `status` 'succeeded' | 'failed' | 'pending' | 'review', required — The status for refunds
  - `reason` string, nullable — An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive
  - `metadata` object, nullable — 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
  - `error_message` string, nullable — The error message
  - `error_code` string, nullable — The code for the error
  - `unified_code` string, nullable — Error code unified across the connectors is received here if there was an error while calling connector
  - `unified_message` string, nullable — Error message unified across the connectors is received here if there was an error while calling connector
  - `created_at` string, date-time, nullable — The timestamp at which refund is created
  - `updated_at` string, date-time, nullable — The timestamp at which refund is updated
  - `connector` string, required — The connector used for the refund and the corresponding payment
  - `profile_id` string, nullable — The id of business profile for this refund
  - `merchant_connector_id` string, nullable — The merchant_connector_id of the processor through which this payment went through
  - `split_refunds` union — Charge specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for more details.
    - object
      - `stripe_split_refund` StripeSplitRefundRequest, required — Charge specific fields for controlling the revert of funds from either platform or connected account for Stripe. Check sub-fields for more details.
        - `revert_platform_fee` boolean, nullable — Toggle for reverting the application fee that was collected for the payment. If set to false, the funds are pulled from the destination account.
        - `revert_transfer` boolean, nullable — Toggle for reverting the transfer that was made during the charge. If set to false, the funds are pulled from the main platform's account.
    - object
      - `adyen_split_refund` AdyenSplitData, required — Fee information for Split Payments to be charged on the payment being collected for Adyen
        - `store` string, nullable — The store identifier
        - `split_items` AdyenSplitItem[], required — Data for the split items
          - `amount` integer, required — The amount of the split item
          - `split_type` 'BalanceAccount' | 'AcquiringFees' | 'PaymentFee' | 'AdyenFees' | 'AdyenCommission' | 'AdyenMarkup' | 'Interchange' | 'SchemeFee' | 'Commission' | 'TopUp' | 'Vat', required
          - `account` string, nullable — The unique identifier of the account to which the split amount is allocated.
          - `reference` string, required — Unique Identifier for the split item
          - `description` string, nullable — Description for the part of the payment that will be allocated to the specified account.
    - object
      - `xendit_split_refund` XenditSplitSubMerchantData, required — Fee information to be charged on the payment being collected for sub-merchant via xendit
        - `for_user_id` string, required — The sub-account user-id that you want to make this transaction for.
  - `issuer_error_code` string, nullable — Error code received from the issuer in case of failed refunds
  - `issuer_error_message` string, nullable — Error message received from the issuer in case of failed refunds
  - `raw_connector_response` string, nullable — Contains whole connector response
  - `connector_refund_id` string, nullable — A unique identifier for a payment provided by the connector

## Other responses

- `400` — Missing Mandatory fields

---

[API](https://skmtc.net/hyperswitch/apis/dynamic-routing-openapi-3-0.md) · [All operations](https://skmtc.net/hyperswitch/apis/dynamic-routing-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hyperswitch/dynamic-routing-openapi-3-0/revisions/8fbf69ab2597/schema)