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_at	datetime	UTC datetime of transfer creation in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
currency	currency	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.
fee_vat	integer	Value-added Tax applied to `fee`
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	datetime	UTC datetime of the transfer payment in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
recipient	object_id	Recipient identifier to which transfer was sent.
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`).
total_fee	integer	Total fee (`fee` + `fee_vat`)
transactions	array	Array of transaction identifiers related to the transfer.

Example

JSON Response

{
  "object": "transfer",
  "id": "trsf_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/transfers/trsf_test_no1t4tnemucod0e51mo",
  "deleted": false,
  "fail_fast": false,
  "paid": false,
  "sent": false,
  "sendable": true,
  "currency": "THB",
  "amount": 47448,
  "fee": 2804,
  "metadata": {},
  "recipient": "recp_test_no1t4tnemucod0e51mo",
  "bank_account": {
    "object": "bank_account",
    "livemode": false,
    "last_digits": "6789",
    "account_number": "123456789",
    "name": "DEFAULT BANK ACCOUNT",
    "type": null,
    "created_at": "2019-12-31T12:59:59Z",
    "brand": "Test Bank",
    "bank_code": "test",
    "branch_code": null
  },
  "failure_code": null,
  "failure_message": null,
  "paid_at": null,
  "sent_at": null,
  "created_at": "2019-12-31T12:59:59Z",
  "transactions": [],
  "schedule": null,
  "fee_vat": 196,
  "net": 44448,
  "total_fee": 3000
}

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 to which transfer was sent. Default: account default recipient identifier

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}");

Request<Transfer> request =new Transfer.CreateRequestBuilder()
        .amount(100000)
        .build();
Transfer transfer = client().sendRequest(request);

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 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}");

Request<Transfer> request =new Transfer.CreateRequestBuilder()
        .amount(100000)
        .recipient("recp_test_4z6p7e0m4k40txecj5o")
        .build();
Transfer transfer = client().sendRequest(request);

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
)

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);

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}");

Request<Transfer> request =
        new Transfer.GetRequestBuilder("trsf_test_4xs5px8c36dsanuwztf").build();
Transfer transfer = client().sendRequest(request);

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")

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

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

curl https://api.omise.co/transfers/trsf_test_5g5iq2185wzdpx2tg3a \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000"

<?php

$transfer = OmiseTransfer::retrieve('trsf_test_4y3miv1nhy0dceit4w4');
$transfer['amount'] = 50000;
$transfer->save();

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

const transfer = await omise.transfers.update(
  'trsf_test_no1t4tnemucod0e51mo',
  { amount: 50000 },
);
console.log(transfer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

transfer = Omise::Transfer.retrieve("trsf_test_4y3miv1nhy0dceit4w4")
transfer.update(amount: 50000)

var transferId = "trsf_test_57po4c8r5hr41flvcw7";
var transfer = await Client.Transfers.Update(transferId, new UpdateTransferRequest
{
    Amount = 733137
});

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

Request<Transfer> request = new Transfer.UpdateRequestBuilder("trsf_test_4xs5px8c36dsanuwztf")
        .amount(200000)
        .build();
Transfer transfer = client().sendRequest(request);

System.out.printf("Transfer amount: %d", transfer.getAmount());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

transfer = omise.Transfer.retrieve("trsf_test_no1t4tnemucod0e51mo")
transfer.update(amount=50000)

# Or alternatively:
transfer.amount = 50000
transfer.update()

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

result := &omise.Transfer{}

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

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Transfer.update("trsf_test_4y3miv1nhy0rceit4w4", amount: 50000)

Update transfer metadata

curl

curl https://api.omise.co/transfers/trsf_test_5g5iq2185wzdpx2tg3a \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "metadata[order_id]=ORDER_ID" \
  -d "metadata[color]=black"

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})");

Request<Transfer> request =
        new Transfer.DestroyRequestBuilder("trsf_test_4xs5px8c36dsanuwztf").build();
Transfer transfer = client().sendRequest(request);

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")

JSON Response

JSON

{
  "object": "transfer",
  "id": "trsf_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/transfers/trsf_test_no1t4tnemucod0e51mo",
  "created_at": "2019-07-23T01:19:30Z",
  "deleted": true,
  "recipient": "recp_test_no1t4tnemucod0e51mo",
  "bank_account": {
    "object": "bank_account",
    "livemode": false,
    "created_at": "2019-07-23T01:19:28Z",
    "last_digits": "1234",
    "name": "Somchai Prasert",
    "type": null,
    "brand": "Bangkok Bank",
    "bank_code": "bbl",
    "branch_code": null
  },
  "sent": false,
  "sent_at": null,
  "paid": false,
  "paid_at": null,
  "amount": 403988123,
  "currency": "THB",
  "transactions": [

  ],
  "schedule": null,
  "fee": 14019,
  "fee_vat": 981,
  "net": 902103038,
  "total_fee": 15000,
  "sendable": false,
  "failure_code": null,
  "failure_message": null,
  "fail_fast": false,
  "metadata": {
  }
}

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

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}");

Request<ScopedList<Transfer>> request = new Transfer.ListRequestBuilder().build();
ScopedList<Transfer> transfers = client().sendRequest(request);

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: