Documentation Index

Fetch the complete documentation index at: https://docs.xendit.co/llms.txt

Use this file to discover all available pages before exploring further.

For archived content, access the previous documentation here or the previous API reference here.

Create account (v3)

  • Updated on Jul 9, 2026
  • Published on Jul 9, 2026
Prev Next
Post
/v3/accounts

Creates a new sub-account linked to your master account.

The v3 Accounts API provides richer sub-account management with explicit identity and configuration options. It supersedes the v2 /v2/accounts endpoint.

Key changes from v2:

  • email is now required on create
  • Sub-account identity (country + entity type) is now required on create
  • configuration replaces configurations with a new shape
  • Webhook recipient values changed: MASTER → MASTER_ACCOUNT, SUB → SUB_ACCOUNT
  • Response includes identity and configuration objects instead of top-level legal_name / country_of_incorporation

The API key used for the request determines which master account the sub-account is linked to — you do not need to pass a business ID or environment mode explicitly.

Use an API key with Account Write permission to perform this request.

Country of incorporation

By default, identity.country_of_incorporation must match your master account's country of operation. Cross-country sub-accounts are only allowed if explicitly enabled for your account — contact your account manager to enable this.

Entity types by country

Available identity.entity_type values depend on identity.country_of_incorporation:

Country Available entity types
ID CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, NON_PROFIT, INDIVIDUAL, COOPERATIVE
PH CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, INDIVIDUAL, ONE_PERSON_CORPORATION
VN CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, LIMITED_LIABILITY_COMPANY
TH CORPORATION, PARTNERSHIP, NON_PROFIT, INDIVIDUAL
MY CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, NON_PROFIT
SG CORPORATION, PARTNERSHIP
HK CORPORATION, PARTNERSHIP
MX CORPORATION, SOLE_PROPRIETORSHIP, PARTNERSHIP, NON_PROFIT

Any other country of incorporation follows the SG entity type list.

Test mode restrictions

When using a Test API key, the following constraints apply:

Field Restriction
identity.entity_type Must be CORPORATION
identity.country_of_incorporation Must match your master account's country
configuration.users.send_email_invite Must be false or omitted
configuration.webhooks.recipient Must be MASTER_ACCOUNT or omitted

Sub-accounts created in Test mode are provisioned immediately with status LIVE, and their identity and configuration are returned with default values. They are only available in Test mode and will never go live.

Security
HTTP
Type basic
Body parameters
Corporation (SG)
{
  "name": "Acme Corp",
  "email": "owner@acme.com",
  "identity": {
    "country_of_incorporation": "SG",
    "entity_type": "CORPORATION"
  },
  "configuration": {
    "users": {
      "send_email_invite": true
    },
    "webhooks": {
      "recipient": "MASTER_ACCOUNT"
    }
  }
}
Minimal request (ID, defaults)

The entire configuration block is optional for every entity type. When omitted, no email invite is sent (send_email_invite: false) and webhooks default to MASTER_ACCOUNT.

{
  "name": "Toko Berkah",
  "email": "owner@tokoberkah.co.id",
  "identity": {
    "country_of_incorporation": "ID",
    "entity_type": "INDIVIDUAL"
  }
}
Test mode

With a Test API key, entity_type must be CORPORATION, the country must match your master account's country, and configuration must be omitted or use the default values.

{
  "name": "Acme Corp (Test)",
  "email": "owner@acme.com",
  "identity": {
    "country_of_incorporation": "SG",
    "entity_type": "CORPORATION"
  }
}
Expand All
object
name
string Required

Sub-account display name

email
string (email) Required

Email address for the sub-account owner. This becomes the sub-account's default email address, and is the first email to receive the invitation (when configuration.users.send_email_invite is true) to access the dashboard and continue filling in the sub-account's KYC information.

identity

The legal identity of the sub-account's business.

country_of_incorporation is an ISO 3166-1 alpha-2 country code. It must match your master account's country of operation unless cross-country sub-accounts are explicitly enabled for your account.

The available entity_type values depend on country_of_incorporation — see the per-country variants below. Any country not listed follows the Singapore (SG) entity type list.

OneOf
Indonesia (ID)
object (Indonesia (ID))
country_of_incorporation
string Required
Valid values[ "ID" ]
entity_type
string Required
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "NON_PROFIT", "INDIVIDUAL", "COOPERATIVE" ]
Philippines (PH)
object (Philippines (PH))
country_of_incorporation
string Required
Valid values[ "PH" ]
entity_type
string Required
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "INDIVIDUAL", "ONE_PERSON_CORPORATION" ]
Vietnam (VN)
object (Vietnam (VN))
country_of_incorporation
string Required
Valid values[ "VN" ]
entity_type
string Required
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "LIMITED_LIABILITY_COMPANY" ]
Thailand (TH)
object (Thailand (TH))
country_of_incorporation
string Required
Valid values[ "TH" ]
entity_type
string Required
Valid values[ "CORPORATION", "PARTNERSHIP", "NON_PROFIT", "INDIVIDUAL" ]
Malaysia (MY)
object (Malaysia (MY))
country_of_incorporation
string Required
Valid values[ "MY" ]
entity_type
string Required
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "NON_PROFIT" ]
Singapore (SG)
object (Singapore (SG))
country_of_incorporation
string Required
Valid values[ "SG" ]
entity_type
string Required
Valid values[ "CORPORATION", "PARTNERSHIP" ]
Hong Kong (HK)
object (Hong Kong (HK))
country_of_incorporation
string Required
Valid values[ "HK" ]
entity_type
string Required
Valid values[ "CORPORATION", "PARTNERSHIP" ]
Mexico (MX)
object (Mexico (MX))
country_of_incorporation
string Required
Valid values[ "MX" ]
entity_type
string Required
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "NON_PROFIT" ]
configuration
object (AccountConfigurationV3)

Optional behaviour configuration for the sub-account

users
object
send_email_invite
boolean Required

If true, sends an email invitation to email on account creation so the owner can access the sub-account dashboard and continue filling in the sub-account's KYC information. Available for every entity type. Only applies in Live mode.

Defaultfalse
webhooks
object
recipient
string Required

Where webhooks for the sub-account's transactions are delivered:

  • MASTER_ACCOUNT — webhooks are sent to the URLs configured in the master account's settings (default)
  • SUB_ACCOUNT — webhooks are sent to the URLs configured in the sub-account's own settings
Valid values[ "MASTER_ACCOUNT", "SUB_ACCOUNT" ]
Default"MASTER_ACCOUNT"
Responses
200

Sub-account created successfully. Returns a Sub-Account V3 object.

Corporation (SG)
{
  "id": "5cafeb170a2b18519b1b8761",
  "name": "Acme Corp",
  "email": "owner@acme.com",
  "status": "REGISTERED",
  "identity": {
    "country_of_incorporation": "SG",
    "entity_type": "CORPORATION"
  },
  "configuration": {
    "users": {
      "send_email_invite": true
    },
    "webhooks": {
      "recipient": "MASTER_ACCOUNT"
    }
  },
  "created_at": "2026-07-07T10:00:00Z",
  "updated_at": "2026-07-07T10:00:00Z"
}
Minimal request (ID, defaults)
{
  "id": "5cafeb170a2b18519b1b8762",
  "name": "Toko Berkah",
  "email": "owner@tokoberkah.co.id",
  "status": "REGISTERED",
  "identity": {
    "country_of_incorporation": "ID",
    "entity_type": "INDIVIDUAL"
  },
  "configuration": {
    "users": {
      "send_email_invite": false
    },
    "webhooks": {
      "recipient": "MASTER_ACCOUNT"
    }
  },
  "created_at": "2026-07-07T10:00:00Z",
  "updated_at": "2026-07-07T10:00:00Z"
}
Test mode

Test mode sub-accounts are provisioned immediately with status LIVE, and identity and configuration are returned with default values.

{
  "id": "5cafeb170a2b18519b1b8763",
  "name": "Acme Corp (Test)",
  "email": "owner@acme.com",
  "status": "LIVE",
  "identity": {
    "country_of_incorporation": "SG",
    "entity_type": "CORPORATION"
  },
  "configuration": {
    "users": {
      "send_email_invite": false
    },
    "webhooks": {
      "recipient": "MASTER_ACCOUNT"
    }
  },
  "created_at": "2026-07-07T10:00:00Z",
  "updated_at": "2026-07-07T10:00:00Z"
}
Expand All
object

A Sub-Account V3 object

id
string

ID of the sub-account. Use this in the for-user-id header to create transactions on behalf of the sub-account.

Example5cafeb170a2b18519b1b8761
name
string

Sub-account display name

email
string (email)

Email address of the sub-account owner

status
string

Status of the sub-account. Sub-accounts created in Test mode always report LIVE.

Valid values[ "REGISTERED", "AWAITING_DOCS", "PENDING_VERIFICATION", "AWAITING_RESUBMISSION", "LIVE", "DECLINED", "DORMANT", "SUSPENDED", "CLOSED" ]
identity

The legal identity of the sub-account's business.

country_of_incorporation is an ISO 3166-1 alpha-2 country code. It must match your master account's country of operation unless cross-country sub-accounts are explicitly enabled for your account.

The available entity_type values depend on country_of_incorporation — see the per-country variants below. Any country not listed follows the Singapore (SG) entity type list.

OneOf
Indonesia (ID)
object (Indonesia (ID))
country_of_incorporation
string
Valid values[ "ID" ]
entity_type
string
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "NON_PROFIT", "INDIVIDUAL", "COOPERATIVE" ]
Philippines (PH)
object (Philippines (PH))
country_of_incorporation
string
Valid values[ "PH" ]
entity_type
string
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "INDIVIDUAL", "ONE_PERSON_CORPORATION" ]
Vietnam (VN)
object (Vietnam (VN))
country_of_incorporation
string
Valid values[ "VN" ]
entity_type
string
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "LIMITED_LIABILITY_COMPANY" ]
Thailand (TH)
object (Thailand (TH))
country_of_incorporation
string
Valid values[ "TH" ]
entity_type
string
Valid values[ "CORPORATION", "PARTNERSHIP", "NON_PROFIT", "INDIVIDUAL" ]
Malaysia (MY)
object (Malaysia (MY))
country_of_incorporation
string
Valid values[ "MY" ]
entity_type
string
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "NON_PROFIT" ]
Singapore (SG)
object (Singapore (SG))
country_of_incorporation
string
Valid values[ "SG" ]
entity_type
string
Valid values[ "CORPORATION", "PARTNERSHIP" ]
Hong Kong (HK)
object (Hong Kong (HK))
country_of_incorporation
string
Valid values[ "HK" ]
entity_type
string
Valid values[ "CORPORATION", "PARTNERSHIP" ]
Mexico (MX)
object (Mexico (MX))
country_of_incorporation
string
Valid values[ "MX" ]
entity_type
string
Valid values[ "CORPORATION", "SOLE_PROPRIETORSHIP", "PARTNERSHIP", "NON_PROFIT" ]
configuration
object (AccountConfigurationV3)

Optional behaviour configuration for the sub-account

users
object
send_email_invite
boolean

If true, sends an email invitation to email on account creation so the owner can access the sub-account dashboard and continue filling in the sub-account's KYC information. Available for every entity type. Only applies in Live mode.

Defaultfalse
webhooks
object
recipient
string

Where webhooks for the sub-account's transactions are delivered:

  • MASTER_ACCOUNT — webhooks are sent to the URLs configured in the master account's settings (default)
  • SUB_ACCOUNT — webhooks are sent to the URLs configured in the sub-account's own settings
Valid values[ "MASTER_ACCOUNT", "SUB_ACCOUNT" ]
Default"MASTER_ACCOUNT"
created_at
string (date-time)

Timestamp of when the sub-account was created

updated_at
string (date-time)

Timestamp of when the sub-account was last updated

400

Invalid request.

Error code Description
API_VALIDATION_ERROR Inputs are failing validation — a required field is missing or malformed
INVALID_DATA_PROVIDED A field value is invalid — unsupported entity type for the given country, cross-country sub-account not allowed, or Test mode restriction violated
MAXIMUM_ACCOUNT_REACHED You have reached the Test mode sub-account limit (500). This limit does not apply in Live mode.
InvalidDataProvided
{
  "error_code": "INVALID_DATA_PROVIDED",
  "message": "Invalid 'identity.entity_type' provided. Check allowed entity types for the provided country."
}
InvalidDataProvidedTestMode
{
  "error_code": "INVALID_DATA_PROVIDED",
  "message": "Invalid 'identity.entity_type' provided. Only CORPORATION is supported in TEST mode."
}
MaximumAccountReached
{
  "error_code": "MAXIMUM_ACCOUNT_REACHED",
  "message": "You may only create 500 Accounts in TEST mode. Contact help@xendit.co if you need a higher limit"
}
object
error_code
string
message
string
401

Unauthorized.

Error code Description
INVALID_CREDENTIALS The API key is missing/invalid, or the account it belongs to is not enabled for xenPlatform
InvalidCredentials
{
  "error_code": "INVALID_CREDENTIALS",
  "message": "Your credentials are not valid to make this request"
}
object
error_code
string
message
string
403

Forbidden.

Error code Description
DISALLOWED_OPERATION Operation not permitted for your account
DisallowedOperation
{
  "error_code": "DISALLOWED_OPERATION",
  "message": "You are not authorized to create accounts"
}
object
error_code
string
message
string
404

Not found.

Error code Description
BUSINESS_NOT_FOUND_ERROR Master account not found
BusinessNotFound
{
  "error_code": "BUSINESS_NOT_FOUND_ERROR",
  "message": "Business not found"
}
object
error_code
string
message
string