Transfers

Overview

Omise transfers move funds from your account balance to a recipient's bank account. Every recipient is either your default recipient or a third-party recipient you create yourself.

For some Thailand accounts using Payout as a Service (PaaS), a third-party recipient also needs a merchant-recipient relationship type and supporting documents before you can transfer funds to that recipient. The default recipient is not subject to this requirement.

Transfer fee

Omise deducts a transfer fee from the transfer amount.

For most Thailand accounts, the default fee is 30 THB. You can configure your account fee differently. Always check the fee fields on the transfer you create.

The fee is returned on the transfer object:

• fee — Omise transfer fee, in the smallest currency unit
• fee_vat — VAT applied to fee
• total_fee — fee + fee_vat
• net — amount - total_fee (the amount sent to the bank account)

Your transferable balance must cover the transfer amount. For most Thailand accounts, the minimum transferable amount is 30 THB, but you can also configure it per account.

Transfer to your default recipient

By default, Omise creates a recipient for you when you sign up for an account in test mode. When you get your live account, Omise creates a new live recipient using your registration and bank account details.

The following command creates a transfer of 3,500 THB to the default recipient.

curl https://api.omise.co/transfers \
  -X POST \
  -u "$OMISE_SECRET_KEY": \
  -d "amount=350000"

Transfer to a third-party recipient

You can create additional recipients and transfer funds to their bank accounts.

A recipient must complete three steps before you can transfer funds to it: creation, verification, and activation.

A recipient must be verified and active before you can transfer funds to it.

If your account requires merchant-recipient relationship evidence, complete the document upload flow when you create the recipient. You cannot add or change relationship_type or document_ids after the recipient is created. To change them, destroy the recipient and create a new one.

Step 1: Create the recipient

Accounts that require relationship documents (PaaS users, PSP Thailand)

Create the recipient only after you have uploaded the evidence files.

Send a POST request to /recipients with the recipient's details.

Documents: up to 10 files, max 10 MB each. Accepted content types: application/pdf, image/jpeg, image/png, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

1. Get a presigned upload URL

curl https://api.omise.co/recipients/upload_relationship_document \
  -X POST \
  -u "$OMISE_SECRET_KEY": \
  -d "document[filename]=contract.pdf" \
  -d "document[content_type]=application/pdf"

The response includes url, fields, and document_id. Save document_id.

2. Upload the file to the returned URL using the exact fields, with the file as the last form field named file.

3. Create the recipient

The following command demonstrates how to create a recipient using curl.

curl https://api.omise.co/recipients \
  -X POST \
  -u "$OMISE_SECRET_KEY": \
  -d "name=Jane Doe" \
  -d "email=jane.doe@example.com" \
  -d "type=individual" \
  -d "relationship_type=Contractor" \
  -d "document_ids[]=docu_xxxxxxxxxxxxxxxxxxx" \
  -d "bank_account[brand]=test" \
  -d "bank_account[number]=7v2k9dq4x1" \
  -d "bank_account[name]=Jane Doe"

A new recipient starts inactive and unverified.

Accounts that do not require relationship documents

Send a POST request to /recipients with the recipient's details.

The following command demonstrates how to create a recipient using curl.

curl https://api.omise.co/recipients \
  -X POST \
  -u "$OMISE_SECRET_KEY": \
  -d "name=Jane Doe" \
  -d "email=jane.doe@example.com" \
  -d "description=My first other recipient" \
  -d "type=individual" \
  -d "bank_account[brand]=test" \
  -d "bank_account[number]=7v2k9dq4x1" \
  -d "bank_account[name]=Jane Doe"

A new recipient starts inactive and unverified.

Step 2: Wait for verification

Omise verifies each recipient. This process generally takes no more than two business days.

You can transfer to a recipient only after it is verified and active.

Common failure_code values:

• name_mismatch
• account_not_found
• bank_not_found

Step 3: Activate the recipient

You can activate a recipient independently of verification. By default, a recipient stays inactive until you activate it. To activate a recipient, go to the recipient's details and click Activate the recipient.

Step 4: Create the transfer

Send a POST request to /transfers with the amount and the recipient's ID in the recipient parameter.

The following command creates a transfer of 3,500 THB to recipient recp_test_9f3k7m2wq5xz8p1yth6d.

curl https://api.omise.co/transfers \
  -X POST \
  -u "$OMISE_SECRET_KEY": \
  -d "amount=350000" \
  -d "recipient=recp_test_9f3k7m2wq5xz8p1yth6d"

If your account requires relationship evidence, the recipient must already have a relationship_type. Otherwise, create transfer returns: Invalid transfer: recipient relationship_type is required.

If your account does not yet allow third-party payouts, creating a transfer to a non-default recipient returns: The account does not support non-default recipient transfers.

FAQ

What do I need before I can create a transfer?

A transferable balance that meets your account minimum (commonly 30 THB in Thailand), and a verified, active recipient.

Where does the default recipient come from?

Omise creates it automatically. Test mode uses a test recipient. Live mode uses your registration and bank account details.

How do I create a third-party recipient?

POST /recipients with name, type, and bank account. If your account is a PaaS user on PSP Thailand, also upload documents and send relationship_type and document_ids. You cannot change those fields later; destroy the recipient and create a new one.

What steps does a recipient need before I can transfer funds to them?

The recipient must be verified and active. For PaaS users on PSP Thailand, it must also have a relationship type and linked documents.

Why did a recipient fail verification?

Bank-account mismatches use name_mismatch, account_not_found, or bank_not_found. Contact support for other failure codes.

How do I transfer funds to a specific recipient?

Send a POST request to /transfers with the amount and the recipient's ID in the recipient parameter. Omit recipient to transfer to the default recipient.

Related Content

• Recipients API
• Transfers API