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

Attribute

Name Type Description
object string

The string refund.

id object_id

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

location string

API path to retrieve the current refund object.

amount integer

Amount for refund in smallest currency unit.

charge object_id

CHARGE_ID associated with this refund.

created datetime

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

currency string

Currency for refund as three-letter ISO 4217 code.

metadata object

Custom metadata (e.g. {"customer-id": 42}) for refund.

transaction object_id

TRANSACTION_ID associated with this refund.

voided boolean

Whether the refund has been voided.

Example

  • Json Response

List all refunds

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

Returns a list of all refund objects belonging to your account.

Request Parameter

Name Type Description
offset integer

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

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

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

order string

(optional, default: chronological) Order in which to return records. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all refunds

List all refunds of a particular charge

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

Returns a list of refund objects that belong to the charge.

Request Parameter

Name Type Description
offset integer

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

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

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

order string

(optional, default: chronological) Order in which to return records. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all refunds of a particular charge

Create a refund

- POST https://api.omise.co/charges/CHARGE_ID/refunds

Returns a new refund object.

Request Parameter

Name Type Description
amount integer

(required) Amount for refund in the smallest currency unit.

void boolean

(optional, default: false) The boolean flag to only process void and suppress the normal refund if unsuccessfully void.

metadata object

(optional) Custom metadata (e.g. {"customer-id": 42}) to attach to the refund.

Example

  • Create a refund

Retrieve a refund

- GET https://api.omise.co/charges/CHARGE_ID/refunds/REFUND_ID

Returns an existing refund object.

Example

  • Retrieve a refund