Sign in

v1

latestOpenAPI 3.0.02026-07-26168846732.2 KB
Refunds

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

post/refunds

Request body

payment_idstring required

The payment id against which refund is to be initiated

refund_idstring 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_idstring nullable

The identifier for the Merchant Account

amountinteger 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

reasonstring 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

metadataobject 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.

all_keys_requiredboolean nullable

If true, returns stringified connector raw response body

Example request

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "refund_id": "ref_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "y3oqhf46pyzuxjbcn2giaqnb44",
  "amount": 6540,
  "reason": "Customer returned the product",
  "split_refunds": {
    "adyen_split_refund": {
      "split_items": [
        {
          "amount": 6540
        }
      ]
    }
  }
}

Response

Refund created

refund_idstring required

Unique Identifier for the refund

payment_idstring required

The payment id against which refund is initiated

amountinteger 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

currencystring required

The three-letter ISO currency code

status'succeeded' | 'failed' | 'pending' | 'review' required

The status for refunds

reasonstring nullable

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

metadataobject 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_messagestring nullable

The error message

error_codestring nullable

The code for the error

unified_codestring nullable

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

unified_messagestring nullable

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

created_atstring date-time nullable

The timestamp at which refund is created

updated_atstring date-time nullable

The timestamp at which refund is updated

connectorstring required

The connector used for the refund and the corresponding payment

profile_idstring nullable

The id of business profile for this refund

merchant_connector_idstring nullable

The merchant_connector_id of the processor through which this payment went through

issuer_error_codestring nullable

Error code received from the issuer in case of failed refunds

issuer_error_messagestring nullable

Error message received from the issuer in case of failed refunds

raw_connector_responsestring nullable

Contains whole connector response

connector_refund_idstring nullable

A unique identifier for a payment provided by the connector

Example response

{
  "amount": 6540,
  "connector": "stripe",
  "split_refunds": {
    "adyen_split_refund": {
      "split_items": [
        {
          "amount": 6540
        }
      ]
    }
  }
}