Transfer API

Create and retrieve transfers to your bank account or third-party bank accounts. Third-party transfer recipients have to be verified by Omise.

Attributes

Name Type Description
object string

The string transfer.

id object_id

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

livemode boolean

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

location string

API path to retrieve the current transfer object.

amount integer

Transfer amount in smallest unit of transfer currency.

bank_account bank_account

Destination bank account for transfer.

created datetime

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

currency currency_lowercase

Currency for transfer as three-letter ISO 4217 code.

deleted boolean

Whether transfer is deleted.

fail_fast boolean

Whether the transfer will avoid retrying in the case of failure: true if the transfer will not be retried, false if it will be retried.

failure_code string

Failure code for transfer. One of insufficient_balance, invalid_recipient, transfers_suspended, transfer_deleted, transfer_sent, or transfer_failed.

failure_message string

Message describing the failure if failure_code exists.

fee integer

Omise transfer fee.

metadata object

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

paid boolean

Whether transfer was paid.

paid_at datetime

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

recipient object_id

Recipient identifier for transfer.

schedule object_id

Schedule associated with transfer.

sendable boolean

Whether transfer is able to be sent. For transfer to be marked as sendable, amount must be less than the available amount, recipient must be verified and active, transfer must not have already been sent, and transfers must not be suspended for this account. Transfer may still fail if any of the above requirements are not met at the time of transfer initiation.

sent boolean

Whether transfer was sent.

sent_at datetime

UTC datetime of the transfer send event in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

transaction string

Transaction identifier of the transfer.

Example

  • JSON Response

Create a transfer

- POST https://api.omise.co/transfers

Creates and returns a new transfer.

Request Parameters

Name Type Description
amount integer

(optional) Amount for transfer in smallest currency unit. Use the Balance API to ensure this value is less than or equal to the transferable (available) balance. Default: transferable balance amount.

fail_fast boolean

(optional) Whether the transfer will avoid retrying in the case of failure: true if the transfer will not be retried, false if it will be retried. Default: false.

metadata object

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

recipient object_id

(optional) Recipient identifier for transfer. Use the Recipients API to ensure recipient is verified and active.

Example

  • Create a transfer

  • Create a transfer to a third-party recipient

  • Create a transfer while adding metadata

Retrieve a transfer

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

Returns the transfer matching :id.

Example

  • Retrieve a transfer

Update a transfer

- PATCH https://api.omise.co/transfers/{id}

Returns the updated transfer.

Request Parameters

Name Type Description
amount integer

(optional) Amount for transfer in smallest currency unit. Use the Balance API to ensure this value is less than or equal to the transferable (available) balance. Default: transferable balance amount.

metadata object

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

Example

  • Update a transfer

  • Update transfer metadata

Destroy a transfer

- DELETE https://api.omise.co/transfers/{id}

Destroys the transfer matching :id.

Example

  • Destroy a transfer

  • JSON Response

List transfers

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

Returns a list of transfers 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 transfers

Mark a transfer as paid

- POST https://api.omise.co/transfers/{id}/mark_as_paid

This endpoint allows you to manually mark a test transfer as paid. This can be useful for testing purposes.

Example

  • Mark a test transfer as paid

Mark a transfer as sent

- POST https://api.omise.co/transfers/{id}/mark_as_sent

This endpoint allows you to manually mark a test transfer as sent. This can be useful for testing purposes.

Example

  • Mark a test transfer as sent