Transfer API

⚠️

Don't leave your account unprotected.

Two-factor Authentication (2FA) helps prevent unauthorized access and protects your Omise account from misuse.

We strongly recommend enabling it now to keep your account secure.

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	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.
balance_hold_at	string	TBD
bank_account	bank_account	Destination bank account for transfer.
created	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	Omise transfer 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 Omise 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 Omise Support.
metadata	object	Custom metadata (e.g. `{"answer": 42}`) for transfer.
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	string	Recipient identifier for transfer.
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`).
split_transfer_group_id	string	TBD
transaction	object_id_expandable	Transaction identifier of the transfer.

Example

JSON Response

{
  "object": "transfer",
  "id": "trsf_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/transfers/trsf_test_no1t4tnemucod0e51mo",
  "fail_fast": false,
  "paid": false,
  "sent": false,
  "sendable": true,
  "currency": "thb",
  "amount": 47448,
  "fee": 3000,
  "metadata": {},
  "recipient": "recp_test_no1t4tnemucod0e51mo",
  "transaction": null,
  "schedule": null,
  "bank_account": {
    "object": "bank_account",
    "account_type": null,
    "bank_code": null,
    "branch_code": null,
    "brand": "test",
    "created": "2019-12-31T12:59:59Z",
    "last_digits": "6789",
    "name": "DEFAULT BANK ACCOUNT"
  },
  "failure_code": null,
  "failure_message": null,
  "created": "2019-12-31T12:59:59Z",
  "paid_at": null,
  "sent_at": null
}

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 for transfer. Use the Recipients API to ensure recipient is verified and active.
split_transfer	boolean	(optional, one of: `true`, `false`) Split transfer

Example

Create a transfer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/transfers \
  -u $OMISE_SECRET_KEY: \
  -d "amount=100000" \
  -d "fail_fast=true"

<?php

$transfer = OmiseTransfer::create(array(
  'amount' => 100000
));

const omise = require('omise')({
  secretKey: 'skey_test_5tql5ydqyrd76sfv0wd',
});

const transfer = await omise.transfers.create({ amount: '20000' });
console.log(transfer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

transfer = Omise::Transfer.create(amount: 100000)

var transfer = await Client.Transfers.Create(new CreateTransferRequest
{
    Amount = 200000,
    FailFast = true,
});

Console.WriteLine($"created transfer: {transfer.Id}");

Transfer transfer = client.transfers()
  .create(new Transfer.Create().amount(100000));
System.out.printf("created transfer: %s", transfer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

transfer = omise.Transfer.create(amount=100000)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Transfer{}

err := client.Do(result, &operations.CreateTransfer{
	Amount: 32100,
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Transfer.create(amount: 100000)

Create a transfer while adding metadata

curl
php
node.js

curl https://api.omise.co/transfers \
  -u $OMISE_SECRET_KEY: \
  -d "amount=10000" \
  -d "fail_fast=true" \
  -d "metadata[order_id]=ORDER-1234" \
  -d "metadata[color]=black"

<?php

$transfer = OmiseTransfer::create(array(
    'amount'    => 10000,
    'fail_fast' => true,
    'metadata'  => array(
        'order_id' => 'ORDER_ID',
        'color'    => 'pink'
    )
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const transfer = await omise.transfers.create({
  amount: '100000',
  recipient: 'recp_test_no1t4tnemucod0e51mo',
  metadata: {
    order_id: 'ord_test_no1t4tnemucod0e51mo',
    color: 'pink',
  },
});
console.log(transfer);

Create a transfer to a third-party recipient

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/transfers \
  -u $OMISE_SECRET_KEY: \
  -d "amount=100000" \
  -d "recipient=recp_test_5g03h1x1mbpgxp8h1fh"

<?php

$transfer = OmiseTransfer::create(array(
  'amount' => 100000,
  'recipient' => 'recp_test_4z6p7e0m4k40txecj5o'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const transfer = await omise.transfers.create({
  amount: '100000',
  recipient: 'recp_test_no1t4tnemucod0e51mo',
});
console.log(transfer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

transfer = Omise::Transfer.create({
  recipient: "recp_test_4z6p7e0m4k40txecj5o",
  amount: 100000,
})

var recipientId = "recp_test_560ph01r04muv1a28ze";
var transfer = await Client.Transfers.Create(new CreateTransferRequest
{
    Amount = 200000,
    FailFast = true,
    Recipient = recipientId,
});

Console.WriteLine($"created transfer: {transfer.Id}");

Transfer transfer = client.transfers()
  .create(new Transfer.Create()
          .amount(100000)
          .recipient("recp_test_4z6p7e0m4k40txecj5o"));
System.out.printf("created transfer: %s", transfer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

transfer = omise.Transfer.create(
    amount=100000, recipient="recp_test_no1t4tnemucod0e51mo"
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Transfer{}

err := client.Do(result, &operations.CreateTransfer{
	Amount:    32100,
	Recipient: "recp_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Transfer.create(
  recipient: "recp_test_4z6p7e0m4k40txecj5o",
  amount:    100000
)

Destroy a transfer

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

Destroys the transfer matching :id.

Example

Destroy a transfer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/transfers/trsf_test_5g5iq2185wzdpx2tg3a \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

<?php

$transfer = OmiseTransfer::retrieve('trsf_test_4y3miv1nhy0dceit4w4');
$transfer->destroy();
$transfer->isDestroyed(); # => true

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const transfer = await omise.transfers.destroy('trsf_test_no1t4tnemucod0e51mo');
console.log(transfer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

transfer = Omise::Transfer.retrieve("trsf_test_4y3miv1nhy0rceit4w4")
transfer.destroy
transfer.destroyed? # => true

var transfer = RetrieveTransfer();
transfer = await Client.Transfers.Destroy(transfer.Id);
Console.WriteLine($"destroyed transfer: {transfer.Id} ({transfer.Deleted})");

Transfer transfer = client.transfers().destroy("trsf_test_4xs5px8c36dsanuwztf");
System.out.printf("destroyed transfer: %s", transfer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

transfer = omise.Transfer.retrieve("trsf_test_no1t4tnemucod0e51mo")
transfer.destroy()
transfer.destroyed  # => true

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Deletion{}

err := client.Do(result, &operations.DestroyTransfer{
	TransferID: "trsf_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Transfer.destroy("trsf_test_4y3miv1nhy0rceit4w4")

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/transfers \
  -u $OMISE_SECRET_KEY:

<?php

$transfers = OmiseTransfer::retrieve();

const omise = require('omise')({
  secretKey: 'skey_test_5tql5ydqyrd76sfv0wd',
});

const transfer = await omise.transfers.list();
console.log(transfer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

transfers = Omise::Transfer.retrieve

var transfers = await Client.Transfers.GetList(order: Ordering.ReverseChronological);
Console.WriteLine($"total transfers: {transfers.Total}");

ScopedList<Transfer> transfers = client.transfers().list();
System.out.printf("returned transfers: %d", transfers.getData().size());
System.out.printf("total no. of transfers: %d", transfers.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

transfers = omise.Transfer.retrieve()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.TransferList{}

err := client.Do(result, &operations.ListTransfers{
	operations.List{
		Limit: 100,
		From:  time.Now().Add(-1 * time.Hour),
	},
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Transfer.list

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

curl

curl https://api.omise.co/transfers/trsf_test_5g5iq2185wzdpx2tg3a/mark_as_paid \
  -X POST \
  -u $OMISE_SECRET_KEY:

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

curl

curl https://api.omise.co/transfers/trsf_test_5g5iq2185wzdpx2tg3a/mark_as_sent \
  -X POST \
  -u $OMISE_SECRET_KEY:

Retrieve a transfer

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

Returns the transfer matching :id.

Example

Retrieve a transfer

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/transfers/trsf_test_5g5iq2185wzdpx2tg3a \
  -u $OMISE_SECRET_KEY:

<?php

$transfer = OmiseTransfer::retrieve('trsf_test_4xs5px8c36dsanuwztf');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const transfer = await omise.transfers.retrieve('trsf_test_no1t4tnemucod0e51mo');
console.log(transfer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

transfer = Omise::Transfer.retrieve("trsf_test_4xs5px8c36dsanuwztf")

var transferId = "trsf_test_560ph0660cgiag1xjeh";
var transfer = await Client.Transfers.Get(transferId);
Console.WriteLine($"transfer amount: {transfer.Amount}");

Transfer transfer = client.transfers().get("trsf_test_4xs5px8c36dsanuwztf");
System.out.printf("transfer amount: %d", transfer.getAmount());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

transfer = omise.Transfer.retrieve("trsf_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Transfer{}

err := client.Do(result, &operations.RetrieveTransfer{
	TransferID: "trsf_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Transfer.retrieve("trsf_test_4y3miv1nhy0rceit4w4")