Create a sub-merchant

POSThttps://api.omise.co/sub_merchants

Create a new sub-merchant under your platform account. Sub-merchants can be individuals or businesses that process payments through your marketplace or platform.

---

Request Parameters

Required - 6 fieldsRequired Parameters

▼

`name`STRING(required)

Sub-merchant display name (business name or individual name).

Example:"Acme Electronics Store"

`type`STRING(required)

Sub-merchant type.

Example:"business"

Values:individual, business

`email`STRING(required)

Primary contact email for the sub-merchant.

Example:"contact@acme-electronics.com"

`bank_account.brand`STRING(required)

Bank code (bbl, kbank, scb, ktb, bay, tmb, etc.).

Example:"kbank"

`bank_account.number`STRING(required)

Bank account number for settlements (no spaces or dashes).

Example:"1234567890"

`bank_account.name`STRING(required)

Account holder name as registered with bank (must match exactly).

Example:"ACME ELECTRONICS CO LTD"

Business - 4 fieldsBusiness Information

▼

`business_name`STRING(optional)

Registered legal business name (required for business type).

Example:"Acme Electronics Co., Ltd."

`business_registration_number`STRING(optional)

Official business registration number (required for business type).

Example:"0123456789012"

`tax_id`STRING(optional)

Tax identification number.

Example:"1234567890123"

`business_category`STRING(optional)

Business category or industry code.

Example:"electronics_retail"

Values:electronics_retail, fashion, food_beverage, health_beauty, home_garden, services, other

Contact - 4 fieldsContact Information

▼

Additional - 3 fieldsAdditional Parameters

▼

---

Responses

200

Successful creation

Sub-merchant created successfully. Note that status: pending by default until verification completes.

Response includes:

• id - Unique sub-merchant identifier (subm_xxx)
• status - Current status (pending, active, suspended, deactivated, rejected)
• livemode - Whether this is a live or test sub-merchant
• created_at - Creation timestamp
• bank_account - Bank account details (number masked for security)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Missing required fields (name, type, email, bank_account fields)
• Invalid email format
• Invalid bank account format
• Invalid sub-merchant type
• 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

404

Not found

Platform account not found or sub-merchant feature not enabled.

Common causes:

• Account is not a platform account
• Sub-merchant feature not enabled
• Contact support to enable platform features

422

Unprocessable entity

Sub-merchant validation failed.

Common causes:

• Duplicate sub-merchant (email or business registration already exists)
• Invalid bank account number
• Business category not supported in your region
• Missing required business information for business type

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/sub_merchants \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "name=Acme Electronics Store" \
  -d "type=business" \
  -d "email=contact@acme-electronics.com" \
  -d "business_name=Acme Electronics Co., Ltd." \
  -d "business_registration_number=0123456789012" \
  -d "tax_id=1234567890123" \
  -d "bank_account[brand]=kbank" \
  -d "bank_account[number]=1234567890" \
  -d "bank_account[name]=ACME ELECTRONICS CO LTD"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

sub_merchant = Omise::SubMerchant.create({
  name: 'Acme Electronics Store',
  type: 'business',
  email: 'contact@acme-electronics.com',
  business_name: 'Acme Electronics Co., Ltd.',
  business_registration_number: '0123456789012',
  tax_id: '1234567890123',
  bank_account: {
    brand: 'kbank',
    number: '1234567890',
    name: 'ACME ELECTRONICS CO LTD'
  }
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

sub_merchant = omise.SubMerchant.create(
    name='Acme Electronics Store',
    type='business',
    email='contact@acme-electronics.com',
    business_name='Acme Electronics Co., Ltd.',
    business_registration_number='0123456789012',
    tax_id='1234567890123',
    bank_account={
        'brand': 'kbank',
        'number': '1234567890',
        'name': 'ACME ELECTRONICS CO LTD'
    }
)

Node.js

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

const subMerchant = await omise.subMerchants.create({
  name: 'Acme Electronics Store',
  type: 'business',
  email: 'contact@acme-electronics.com',
  business_name: 'Acme Electronics Co., Ltd.',
  business_registration_number: '0123456789012',
  tax_id: '1234567890123',
  bank_account: {
    brand: 'kbank',
    number: '1234567890',
    name: 'ACME ELECTRONICS CO LTD'
  }
});

PHP

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

$subMerchant = OmiseSubMerchant::create([
    'name' => 'Acme Electronics Store',
    'type' => 'business',
    'email' => 'contact@acme-electronics.com',
    'business_name' => 'Acme Electronics Co., Ltd.',
    'business_registration_number' => '0123456789012',
    'tax_id' => '1234567890123',
    'bank_account' => [
        'brand' => 'kbank',
        'number' => '1234567890',
        'name' => 'ACME ELECTRONICS CO LTD'
    ]
]);

Java

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

BankAccount bankAccount = new BankAccount();
bankAccount.brand("kbank");
bankAccount.number("1234567890");
bankAccount.name("ACME ELECTRONICS CO LTD");

SubMerchant subMerchant = client.subMerchants().create()
    .name("Acme Electronics Store")
    .type("business")
    .email("contact@acme-electronics.com")
    .businessName("Acme Electronics Co., Ltd.")
    .businessRegistrationNumber("0123456789012")
    .taxId("1234567890123")
    .bankAccount(bankAccount)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var subMerchant = await client.SubMerchants.Create(new CreateSubMerchantRequest
{
    Name = "Acme Electronics Store",
    Type = "business",
    Email = "contact@acme-electronics.com",
    BusinessName = "Acme Electronics Co., Ltd.",
    BusinessRegistrationNumber = "0123456789012",
    TaxId = "1234567890123",
    BankAccount = new BankAccount
    {
        Brand = "kbank",
        Number = "1234567890",
        Name = "ACME ELECTRONICS CO LTD"
    }
});

Go

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

subMerchant, _ := client.SubMerchants().Create(&operations.CreateSubMerchant{
    Name:                       "Acme Electronics Store",
    Type:                       "business",
    Email:                      "contact@acme-electronics.com",
    BusinessName:               "Acme Electronics Co., Ltd.",
    BusinessRegistrationNumber: "0123456789012",
    TaxId:                      "1234567890123",
    BankAccount: &operations.BankAccount{
        Brand:  "kbank",
        Number: "1234567890",
        Name:   "ACME ELECTRONICS CO LTD",
    },
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check all required fields are provided
authentication_failure	Invalid API key	Verify your secret key is correct
invalid_bank_account	Bank account number invalid	Verify account number is correct
duplicate_merchant	Sub-merchant already exists	Check if email or registration number is already used
unsupported_bank	Bank not supported	Check supported banks list
platform_not_enabled	Platform features not enabled	Contact support to enable platform account

Sub-Merchant Types

Type	Description
individual	Personal accounts for individual sellers
business	Corporate or business accounts

Sub-Merchant Statuses

Status	Description
pending	Awaiting verification
active	Verified and can process payments
suspended	Temporarily disabled
deactivated	Permanently removed
rejected	Verification failed

---

🔑API Credentials

▼

Try it out

Required - 6 fields

▼

name(Required)

type(Required)

email(Required)

bank_account[brand](Required)

bank_account[number](Required)

bank_account[name](Required)

Recommended - 4 fields

▼

Additional - 4 fields

▼

Your IP: ...Loading...