Refund API

Create and retrieve refunds on undisputed, captured charges. The charge must have fewer than 15 partial refunds and must also have been captured for no longer than 365 days. If the charge is fully refunded prior to its settlement, the refund is processed as a void.

Note: Some payment methods may have refundable periods shorter than 365 days. Please refer to the documentation for each payment method for more details.

Attributes

Name Type Description
object string

The string refund.

id string

The refund identifier matching /rfnd(_test)?_[0-9a-z]+/.

livemode boolean

Whether this is a live (true) or test (false) refund.

location string

API path to retrieve the current refund object.

acquirer_reference_number string

Reference number for the refund initiated by the merchant. This information is sent as part of the settlement report to Visa and Master Card.

amount integer

Refund amount in smallest unit of charge currency.

approval_code string

The reference number for approved transactions by issuer banks. This code helps merchants easily investigate issues with banks.

charge object_id_expandable

Charge identifier associated with this refund.

created_at string

UTC datetime of refund creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

currency string

Currency for refund as three-letter ISO 4217 code.

funding_amount integer

For refunds of multi-currency charges, amount after exchange into account funding currency (funding_currency) specified in the smallest unit of funding_currency.

For refunds of non-multi-currency charges, amount specified in the smallest unit of currency.

funding_currency string

Currency for account as three-letter ISO 4217 code. This is the settlement currency for all charges.

merchant_name string

The name of the sub-merchant who initiated the refund.

Note: This field is applicable only if the merchant uses the Payfac solution. To enroll in Payfac, contact Opn Support.

merchant_uid string

The ID of the sub-merchant who initiated the refund.

Note: This field is applicable only if the merchant uses the Payfac solution. To enroll in Payfac, contact Opn Support.

metadata object

Custom metadata (e.g. {answer: 42}) for refund. The maximum field length is 15.000 characters.

status string

Status of the refund.

terminal string

Original charge point of sale within a branch.

transaction object_id_expandable

Transaction identifier associated with this refund.

voided boolean

Whether refunded charge was voided instead. Charges are voided if refund is processed before settlement time.

Example

  • JSON Response

Create a refund

- POST https://api.omise.co/charges/{id}/refunds

Creates and returns a new refund on charge matching :id.

Request Parameters

Name Type Description
amount integer

(required) Refund amount in smallest unit of charge currency.

metadata object

(optional) Custom metadata (e.g. {answer: 42}) for refund. The maximum field length is 15.000 characters.

void boolean

(optional, one of: true, false) Whether to only process refund as a void, if possible.

By default, if refund is requested before charge settlement, it is processed as a void, otherwise it is processed as a normal refund.

Example

  • Create a refund

  • Create a refund while adding metadata

List refunds for charge

- GET https://api.omise.co/charges/{id}/refunds

Returns a list of refunds belonging to charge matching :id.

Request Parameters

Name Type Description
from string

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

limit integer

(optional, default: 20) Number of records returned.

offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

order string

(optional, default: chronological, one of: chronological, reverse_chronological) Order of records returned.

to string

(optional) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all refunds for a charge

List refunds

- GET https://api.omise.co/refunds

Returns a list of refunds belonging to your account.

Request Parameters

Name Type Description
from string

(optional, default: 1970-01-01T00:00:00Z) Earliest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

limit integer

(optional, default: 20) Number of records returned.

offset integer

(optional, default: 0) Offset of the first record returned (i.e. how many records to skip from the beginning).

order string

(optional, default: chronological, one of: chronological, reverse_chronological) Order of records returned.

to string

(optional) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all refunds

Retrieve a refund

- GET https://api.omise.co/charges/{id}/refunds/{refund_id}

Returns the refund matching :refund_id belonging to charge matching :id.

Example

  • Retrieve a refund

Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more