Transfers API

The Transfers API allows you to transfer funds from your Omise account balance to recipient bank accounts. Transfers are the final step in the payout process, moving funds to merchants, vendors, or individuals.

Overview

Transfers enable you to:

• Send funds to recipients - Transfer money from your Omise balance to bank accounts
• Schedule payouts - Control when funds are sent to recipients
• Track transfer status - Monitor pending, sent, paid, and failed transfers
• Manage metadata - Attach custom data for reconciliation and reporting
• Handle failures - Identify and retry failed transfers

Transfer Lifecycle

1. Create - Initiate a transfer to a recipient
2. Pending - Transfer is queued for processing
3. Sent - Transfer has been submitted to the banking system
4. Paid - Funds successfully reached the recipient's bank account
5. Failed - Transfer failed (insufficient balance, invalid account, etc.)

Key Concepts

Recipients

Transfers require a recipient - a verified bank account destination. You must create a recipient before initiating transfers.

Balance Requirements

Transfers deduct from your available balance. Ensure sufficient funds before creating transfers.

Processing Time

• Thailand: 1-2 business days for local bank transfers
• International: 3-7 business days depending on destination country

Transfer Limits

Transfer limits depend on your account settings and recipient verification status. Contact support for custom limits.

Authentication

All transfer endpoints require your secret key for authentication. Never expose your secret key in client-side code.

Available Endpoints

Method	Endpoint	Description
POST	/transfers	Create a new transfer
GET	/transfers/:id	Retrieve a specific transfer
GET	/transfers	List all transfers
PATCH	/transfers/:id	Update a transfer
DELETE	/transfers/:id	Cancel a pending transfer

Common Use Cases

Marketplace Payouts

Transfer funds to sellers after successful transactions with automatic fee deductions.

Affiliate Commissions

Schedule monthly transfers to affiliates based on performance metrics stored in metadata.

Refunds to Bank Accounts

Process refunds directly to customer bank accounts instead of original payment method.

Vendor Payments

Pay suppliers and vendors with automated transfers integrated with your accounting system.

Transfer Failure Codes

When a transfer fails, the failure_code attribute indicates the reason:

Code	Message	Description
insufficient_balance	"insufficient balance"	Transfer amount exceeds available funds
invalid_recipient	"invalid recipient"	Recipient is invalid or unverified
invalid_bank_account	"invalid bank account"	Bank account details are incorrect
transfers_suspended	"transfers suspended"	Transfers are suspended for the account
transfer_deleted	"transfer deleted"	Attempting to process a deleted transfer
transfer_sent	"transfer already sent"	Attempting to resend an already-sent transfer
transfer_failed	"transfer failed"	General transfer processing failure
bank_not_found	"bank not found"	Specified bank was not found
account_not_found	"account not found"	Bank account could not be located
name_mismatch	"name mismatch"	Account holder name doesn't match

Transfer Status Values

Status	Description
pending	Transfer is queued for processing
sent	Transfer submitted to banking system
paid	Funds reached recipient's bank account
failed	Transfer failed (check failure_code)

Best Practices

• Verify recipients before initiating transfers
• Check balance to ensure sufficient funds
• Use metadata for reconciliation and tracking
• Implement webhooks to monitor transfer status changes
• Handle failures gracefully with retry logic
• Test thoroughly in test mode before processing live transfers

Related Resources

• Recipients API - Manage recipient bank accounts
• Balance API - Check available balance
• Transactions API - View transaction history
• Webhooks - Receive transfer status updates

---

Need help? Contact support@omise.co for transfer limits, processing times, or integration assistance.