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.

Attributes

Name Type Description
object string

The string refund.

id object_id

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.

amount integer

Refund amount in smallest unit of charge currency.

charge object_id

Charge identifier associated with this refund.

created datetime

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

currency currency_lowercase

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 currency_lowercase

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

metadata object

Custom metadata (e.g. {"answer": 42}) for refund.

transaction object_id

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.

void boolean

(optional) 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

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

List refunds

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

Returns a list of refunds belonging to your account.

Request Parameters

Name Type Description
from datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List all refunds

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 datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List all refunds for a charge