Transfer API

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

Attributes

Name Type Description
object string

The string transfer.

id string

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_at string

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

currency string

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

Opn Payments transfer fee.

fee_vat integer

Value-added Tax applied to fee

merchant_name string

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

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 transfer.

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 transfer.

net integer

Transfer amount - fee (total_fee)

paid boolean

Whether transfer was paid.

paid_at string

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

recipient object_id_expandable

Recipient identifier to which transfer was sent.

schedule object_id_expandable

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 string

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

total_fee integer

Total fee (fee + fee_vat)

transactions array

Array of transaction identifiers related to the transfer.

Example

  • JSON Response

Callback

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

Returns the status of the transfer (success/failure)

Request Parameters

Name Type Description
failure_code string

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

failure_message string

(optional) Message describing the failure if failure_code exists.

success boolean

(optional, one of: true, false) Success

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, one of: true, false) 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.

idemp_key string

(optional) Idemp key

metadata object

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

recipient string

(optional) Recipient identifier to which transfer was sent. Default: account default recipient identifier

split_transfer boolean

(optional, one of: true, false) Split transfer

Example

  • Create a transfer

  • Create a transfer while adding metadata

  • Create a transfer to a third-party recipient

Destroy a transfer

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

Destroys the transfer matching :id.

Example

  • Destroy a transfer

List transfers

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

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

Retrieve a transfer

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

Returns the transfer matching :id.

Example

  • Retrieve a transfer

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