Refund API

The Refund API allows you to create and retrieve refunds. A refund operates on a given charge which must meet certain requirements in order to be refundable:

  • The charge must not be disputed.
  • The charge must not be fully refunded already
  • The charge must have fewer than 15 refunds already
  • The charge must be captured
  • The charge must have been captured for no longer than 365 days

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

Amount for refund in smallest unit of charge currency.

charge object_id

Charge identifier associated with this refund.

created_at datetime

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

currency currency

Currency for refund as three-letter ISO 4217 code.

funding_amount integer

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

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

funding_currency currency

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 the refund has been voided.

Deprecated Attribute

Name Type Description
status string

Status of the refund.

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) Amount for refund in smallest unit of charge currency.

metadata object

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

void boolean

(optional) Whether to only process void and suppress normal refund if void is unsuccessful. Default: false.

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