Create a transfer

POSThttps://api.omise.co/transfers

Create a new transfer to send funds from your Omise account balance to a verified recipient's bank account. Transfers can be made to your default recipient or to specific recipients.

---

🔑API Credentials

▼

---

Request Parameters

Recommended - 3 fieldsRecommended Parameters

▼

`amount`INTEGER(optional)

Amount in smallest currency unit (satangs for THB, cents for USD, yen for JPY). If not provided, defaults to your full transferable balance.

Example:100000

Constraints:Minimum: 1 (smallest unit)

`recipient`STRING(optional)

Recipient ID (e.g., recp_test_...). If not provided, uses your account's default recipient.

Example:"recp_test_5xuy4w91xqz7d1w9u0t"

`metadata`OBJECT(optional)

Custom key-value pairs (max 15,000 characters total). Useful for storing transfer references or any custom data.

Example:{"payout_id":"1234","batch":"monthly_payouts"}

Additional - 2 fieldsAdditional Parameters

▼

---

Responses

200

Successful transaction

Transfer created successfully. Check the sent and paid fields to determine transfer status.

Transfer status indicators:

• sendable: true - Transfer can be initiated.
• sent: true - Transfer has been sent to the bank.
• paid: true - Transfer completed, funds received.
• failure_code - Present if transfer failed (see error codes below).

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid recipient ID
• Invalid amount (exceeds available balance)
• Missing bank account information
• Malformed metadata

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

402

Payment required

Transfer processing failed.

Common causes:

• Insufficient balance
• Recipient not verified
• Transfers suspended on your account
• Invalid bank account details

---

Code samples

cURL

curl https://api.omise.co/transfers \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "amount=100000" \
  -d "recipient=recp_test_5xuy4w91xqz7d1w9u0t"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

transfer = Omise::Transfer.create({
  amount: 100000,
  recipient: 'recp_test_5xuy4w91xqz7d1w9u0t'
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

transfer = omise.Transfer.create(
    amount=100000,
    recipient='recp_test_5xuy4w91xqz7d1w9u0t'
)

Node.js

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

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

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$transfer = OmiseTransfer::create([
    'amount' => 100000,
    'recipient' => 'recp_test_5xuy4w91xqz7d1w9u0t'
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Transfer transfer = client.transfers().create()
    .amount(100000L)
    .recipient("recp_test_5xuy4w91xqz7d1w9u0t")
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var transfer = await client.Transfers.Create(new CreateTransferRequest
{
    Amount = 100000,
    Recipient = "recp_test_5xuy4w91xqz7d1w9u0t"
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

transfer, _ := client.Transfers().Create(&operations.CreateTransfer{
    Amount:    100000,
    Recipient: "recp_test_5xuy4w91xqz7d1w9u0t",
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
insufficient_balance	Not enough funds to complete transfer	Wait for charges to clear or reduce amount
invalid_recipient	Recipient ID not found or invalid	Verify recipient exists and is active
transfers_suspended	Transfers disabled on account	Contact Omise support
transfer_deleted	Transfer was deleted	Cannot process deleted transfers
transfer_sent	Transfer already sent	Cannot modify sent transfers
transfer_failed	Transfer processing failed	Check failure_message for details

Transfer Status Indicators

Indicator	Description
sendable: true	Transfer ready to be sent
sent: true	Transfer dispatched to bank
paid: true	Funds successfully received
failure_code	Error occurred (see codes above)

---

Try it out

Recommended - 3 fields

▼

Additional - 2 fields

▼