PaySwitch
PaySwitch API Reference

Refunds

Server

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

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

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

​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

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.


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

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.


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

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

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.


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

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