Refunds

Create and manage refunds for successful payments

Refunds - Create

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/refunds

api-key (header)

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

Refunds - Create › Request Body

RefundRequest

payment_id

string · minLength: 30 · maxLength: 30 · required

The payment id against which refund is to be initiated

Example: pay_mbabizu24mvu3mela5njyhpit4

refund_id

string | null · minLength: 30 · maxLength: 30

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.

Example: ref_mbabizu24mvu3mela5njyhpit4

merchant_id

string | null · maxLength: 255

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44

amount

integer | null · int64 · min: 100

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

Example: 6540

reason

string | null · maxLength: 255

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

Example: Customer returned the product

refund_type

string · enum

To indicate whether to refund needs to be instant or scheduled

Enum values:

scheduled

instant

Default: Instant

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.

object

Merchant connector details used to make payments.

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

all_keys_required

boolean | null

If true, returns stringified connector raw response body

Refunds - Create › Responses

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 · int64 · min: 100 · 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

Example: 6540

currency

string · required

The three-letter ISO currency code

status

RefundStatus · enum · required

The status for refunds

Enum values:

succeeded

failed

pending

review

connector

string · required

The connector used for the refund and the corresponding payment

Example: stripe

reason

string | null

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

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

error_message

string | null

The error message

error_code

string | null

The code for the error

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

created_at

string | null · date-time

The timestamp at which refund is created

updated_at

string | null · date-time

The timestamp at which refund is updated

profile_id

string | null

The id of business profile for this refund

merchant_connector_id

string | null

The merchant_connector_id of the processor through which this payment went through

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

issuer_error_code

string | null

Error code received from the issuer in case of failed refunds

issuer_error_message

string | null

Error message received from the issuer in case of failed refunds

raw_connector_response

string | null

Contains whole connector response

connector_refund_id

string | null

A unique identifier for a payment provided by the connector

object

A fee snapshot summary for one business transaction.

POST/refunds

curl https://paysw-wiki.lab.next-on.pro/dev-router/refunds \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 654,
  "payment_id": "{{payment_id}}",
  "refund_type": "instant"
}'

Example Request Body

{
  "amount": 654,
  "payment_id": "{{payment_id}}",
  "refund_type": "instant"
}

json

application/json

Example Responses

{
  "refund_id": "refund_id",
  "payment_id": "payment_id",
  "amount": 6540,
  "currency": "currency",
  "status": "succeeded",
  "reason": "reason",
  "metadata": {},
  "error_message": "error_message",
  "error_code": "error_code",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "connector": "stripe",
  "profile_id": "profile_id",
  "merchant_connector_id": "merchant_connector_id",
  "split_refunds": {
    "stripe_split_refund": {
      "revert_platform_fee": true,
      "revert_transfer": true
    }
  },
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "raw_connector_response": "raw_connector_response",
  "connector_refund_id": "connector_refund_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Refunds - Retrieve

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/refunds/{refund_id}

api-key (header)

Retrieves a Refund. This may be used to get the status of a previously initiated refund

Refunds - Retrieve › path Parameters

refund_id

string · required

The identifier for refund

Refunds - Retrieve › Responses

Refund retrieved

RefundResponse

refund_id

string · required

Unique Identifier for the refund

payment_id

string · required

The payment id against which refund is initiated

amount

integer · int64 · min: 100 · required

Example: 6540

currency

string · required

The three-letter ISO currency code

status

RefundStatus · enum · required

The status for refunds

Enum values:

succeeded

failed

pending

review

connector

string · required

The connector used for the refund and the corresponding payment

Example: stripe

reason

string | null

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

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

error_message

string | null

The error message

error_code

string | null

The code for the error

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

created_at

string | null · date-time

The timestamp at which refund is created

updated_at

string | null · date-time

The timestamp at which refund is updated

profile_id

string | null

The id of business profile for this refund

merchant_connector_id

string | null

The merchant_connector_id of the processor through which this payment went through

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

issuer_error_code

string | null

Error code received from the issuer in case of failed refunds

issuer_error_message

string | null

Error message received from the issuer in case of failed refunds

raw_connector_response

string | null

Contains whole connector response

connector_refund_id

string | null

A unique identifier for a payment provided by the connector

object

A fee snapshot summary for one business transaction.

GET/refunds/{refund_id}

curl https://paysw-wiki.lab.next-on.pro/dev-router/refunds/:refund_id \
  --header 'api-key: <api-key>'

Example Responses

{
  "refund_id": "refund_id",
  "payment_id": "payment_id",
  "amount": 6540,
  "currency": "currency",
  "status": "succeeded",
  "reason": "reason",
  "metadata": {},
  "error_message": "error_message",
  "error_code": "error_code",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "connector": "stripe",
  "profile_id": "profile_id",
  "merchant_connector_id": "merchant_connector_id",
  "split_refunds": {
    "stripe_split_refund": {
      "revert_platform_fee": true,
      "revert_transfer": true
    }
  },
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "raw_connector_response": "raw_connector_response",
  "connector_refund_id": "connector_refund_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Refunds - Update

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/refunds/{refund_id}

api-key (header)

Updates the properties of a Refund object. This API can be used to attach a reason for the refund or metadata fields

Refunds - Update › path Parameters

refund_id

string · required

The identifier for refund

Refunds - Update › Request Body

RefundUpdateRequest

reason

string | null · maxLength: 255

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

Example: Customer returned the product

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.

Refunds - Update › Responses

Refund updated

RefundResponse

refund_id

string · required

Unique Identifier for the refund

payment_id

string · required

The payment id against which refund is initiated

amount

integer · int64 · min: 100 · required

Example: 6540

currency

string · required

The three-letter ISO currency code

status

RefundStatus · enum · required

The status for refunds

Enum values:

succeeded

failed

pending

review

connector

string · required

The connector used for the refund and the corresponding payment

Example: stripe

reason

string | null

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

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

error_message

string | null

The error message

error_code

string | null

The code for the error

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

created_at

string | null · date-time

The timestamp at which refund is created

updated_at

string | null · date-time

The timestamp at which refund is updated

profile_id

string | null

The id of business profile for this refund

merchant_connector_id

string | null

The merchant_connector_id of the processor through which this payment went through

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

issuer_error_code

string | null

Error code received from the issuer in case of failed refunds

issuer_error_message

string | null

Error message received from the issuer in case of failed refunds

raw_connector_response

string | null

Contains whole connector response

connector_refund_id

string | null

A unique identifier for a payment provided by the connector

object

A fee snapshot summary for one business transaction.

POST/refunds/{refund_id}

curl https://paysw-wiki.lab.next-on.pro/dev-router/refunds/:refund_id \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "reason": "Paid by mistake"
}'

Example Request Body

{
  "reason": "Paid by mistake"
}

json

application/json

Example Responses

{
  "refund_id": "refund_id",
  "payment_id": "payment_id",
  "amount": 6540,
  "currency": "currency",
  "status": "succeeded",
  "reason": "reason",
  "metadata": {},
  "error_message": "error_message",
  "error_code": "error_code",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "connector": "stripe",
  "profile_id": "profile_id",
  "merchant_connector_id": "merchant_connector_id",
  "split_refunds": {
    "stripe_split_refund": {
      "revert_platform_fee": true,
      "revert_transfer": true
    }
  },
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "raw_connector_response": "raw_connector_response",
  "connector_refund_id": "connector_refund_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Refunds - List

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/refunds/list

api-key (header)

Lists all the refunds associated with the merchant, or for a specific payment if payment_id is provided

Refunds - List › Request Body

A type representing a range of time for filtering, including a mandatory start time and an optional end time.

RefundListRequest

start_time

string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

end_time

string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

payment_id

string | null

The identifier for the payment

payment_id_in

array | null

Restrict results to refunds for these payment IDs (e.g. customer recent activity).

refund_id

string | null

The identifier for the refund

profile_id

string | null

The identifier for business profile

limit

integer | null · int64

Limit on the number of objects to return

offset

integer | null · int64

The starting point within a list of objects

object

connector

array | null

The list of connectors to filter refunds list

merchant_connector_id

array | null

The list of merchant connector ids to filter the refunds list for selected label

currency

array | null

The list of currencies to filter refunds list

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

refund_status

array | null

The list of refund statuses to filter refunds list

Enum values:

succeeded

failed

pending

review

object[]

Column predicates. Combined with other fields using AND.

Refunds - List › Responses

200

List of refunds

RefundListResponse

count

integer · min: 0 · required

The number of refunds included in the list

total_count

integer · int64 · required

The total number of refunds in the list

RefundResponse[] · required

The List of refund response object

POST/refunds/list

curl https://paysw-wiki.lab.next-on.pro/dev-router/refunds/list \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "start_time": "2024-08-25T15:00:00Z",
  "end_time": "2024-08-25T15:00:00Z",
  "payment_id": "payment_id",
  "payment_id_in": [
    "string"
  ],
  "refund_id": "refund_id",
  "profile_id": "profile_id",
  "limit": 0,
  "offset": 0,
  "amount_filter": {
    "start_amount": 0,
    "end_amount": 0
  },
  "connector": [
    "string"
  ],
  "merchant_connector_id": [
    "string"
  ],
  "currency": [
    "AED"
  ],
  "refund_status": [
    "succeeded"
  ],
  "filters": [
    {}
  ]
}'

Example Request Body

{
  "start_time": "2024-08-25T15:00:00Z",
  "end_time": "2024-08-25T15:00:00Z",
  "payment_id": "payment_id",
  "payment_id_in": [
    "string"
  ],
  "refund_id": "refund_id",
  "profile_id": "profile_id",
  "limit": 0,
  "offset": 0,
  "amount_filter": {
    "start_amount": 0,
    "end_amount": 0
  },
  "connector": [
    "string"
  ],
  "merchant_connector_id": [
    "string"
  ],
  "currency": [
    "AED"
  ],
  "refund_status": [
    "succeeded"
  ],
  "filters": [
    {}
  ]
}

json

Example Responses

{
  "count": 0,
  "total_count": 0,
  "data": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ]
}

json

application/json

Payments Mandates