--- title: "Create Sub-Account" method: POST path: "/merchant/open/institution/v1/accounts/create" --- # Create Sub-Account `POST /merchant/open/institution/v1/accounts/create` ## Request - Base URL: `https://openplatform.gateapi.io` - URL: `https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/create` - Auth: none declared. Required headers: `X-GatePay-Certificate-ClientId`, `X-GatePay-Timestamp`, `X-GatePay-Nonce`, `X-GatePay-Signature` Create a new sub-account for a customer under the institution account and register the account holder information. ## Headers - `X-GatePay-Certificate-ClientId` string, required - `X-GatePay-Timestamp` string, required - `X-GatePay-Nonce` string, required - `X-GatePay-Signature` string, required ## Request body - CreateSubAccountRequest - `request_id` string, required: Unique request ID from caller. - `customer_id` string, required: Customer ID on the platform side. - `display_name` string, required: Display name of the sub-account. - `account_holder` AccountHolder, required - `entity_country` string, required: Entity's country ISO code. For the full list, refer to the official ISO online browsing platform or public ISO 3166-1 alpha-2 tables (e.g. https://www.iban.com/country-codes). - `entity_type` 'INDIVIDUAL' | 'BUSINESS', required: Entity type: individual - INDIVIDUAL, business - BUSINESS. - `entity_name` string, required: Entity name (person's full name / legal business name). - `entity_id_type` 'PASSPORT' | 'NATIONAL_ID' | 'DRIVING_LICENSE' | 'BUSINESS_LICENSE' | 'CERTIFICATE_OF_INCORPORATION', required: ID document type. See Document Type Enumeration (PASSPORT, NATIONAL_ID, DRIVING_LICENSE for individual; BUSINESS_LICENSE, CERTIFICATE_OF_INCORPORATION for business). - `entity_id_number` string, required: ID document number. - `entity_id_expiry` EntityIdExpiry, required - `valid_from` integer, required: Effective date, in milliseconds. - `valid_to` integer: Expiry date, in milliseconds. - `dob` Dob - `year` integer, required: 4-digit year. - `month` integer, required: Month, 1–12. - `day` integer, required: Day of month, 1–31. - `business_registration` BusinessRegistration - `reg_number` string: Registration number. - `reg_country` string: Country of registration. - `established_at` integer: Date of establishment. - `address` Address, required - `line1` string, required: Address line 1. - `line2` string: Address line 2. - `line3` string: Address line 3. - `country` string, required: Country code. - `city` string: City. - `state` string: State / province. - `postal_code` string: Postal code. - `merchant_category` 'GENERAL_RETAIL' | 'SUPERMARKET_CONVENIENCE' | 'FASHION_AND_ACCESSORIES' | 'FOOD_AND_BEVERAGE' | 'DIGITAL_CONTENT_AND_SAAS' | 'GAMING_AND_ENTERTAINMENT' | 'TRAVEL_AND_TICKETING' | 'RIDE_HAILING_AND_TRANSPORT' | 'HOSPITALITY_AND_LEISURE' | 'EDUCATION' | 'HEALTHCARE_AND_WELLNESS' | 'FINANCIAL_SERVICES' | 'CRYPTO_AND_WEB3' | 'UTILITIES_AND_BILLS' | 'CHARITY_AND_NONPROFIT' | 'OTHER', required: Merchant category. See Merchant Category Enumeration. - `website` string: Business website. - `user_agreement` boolean, required: Whether the user has signed the agreement. - `ubo_list` Ubo[]: List of legal representative(s) and/or ultimate beneficial owner(s) (UBO). Required when entity_type is BUSINESS. - `country` string, required: Country ISO code. - `full_name` string, required: Full name of the individual. - `dob` Dob, required - `year` integer, required: 4-digit year. - `month` integer, required: Month, 1–12. - `day` integer, required: Day of month, 1–31. - `id_type` 'PASSPORT' | 'NATIONAL_ID' | 'DRIVING_LICENSE', required: Type of identification document for the individual. - `id_number` string, required: Identification document number. - `id_expiry` EntityIdExpiry, required - `valid_from` integer, required: Effective date, in milliseconds. - `valid_to` integer: Expiry date, in milliseconds. - `relationship` Relationship, required - `is_representative` boolean: Whether the individual is a legal representative. - `is_owner` boolean: Whether the individual is a beneficial owner. - `percent_ownership` string: Required when is_owner is true; represents the ownership percentage, for example 30.01. - `metadata` object: Additional key–value metadata. ## Response `200` Success - CreateSubAccountResponseWrapper - `status` string - `code` string - `errorMessage` string - `data` CreateSubAccountResponse - `request_id` string: Request ID. - `status` 'INIT' | 'PENDING' | 'ACTIVE' | 'FAIL' | 'RISK_SUSPEND' | 'NONE': Account status: initial - INIT, processing - PENDING, created - ACTIVE, creation failed - FAIL, risk control suspended - RISK_SUSPEND, not enabled - NONE. - `created` string: Creation time (milliseconds). - `customer_id` string: Customer ID on the platform side. - `display_name` string: Display name. - `account_holder` AccountHolder - `entity_country` string, required: Entity's country ISO code. For the full list, refer to the official ISO online browsing platform or public ISO 3166-1 alpha-2 tables (e.g. https://www.iban.com/country-codes). - `entity_type` 'INDIVIDUAL' | 'BUSINESS', required: Entity type: individual - INDIVIDUAL, business - BUSINESS. - `entity_name` string, required: Entity name (person's full name / legal business name). - `entity_id_type` 'PASSPORT' | 'NATIONAL_ID' | 'DRIVING_LICENSE' | 'BUSINESS_LICENSE' | 'CERTIFICATE_OF_INCORPORATION', required: ID document type. See Document Type Enumeration (PASSPORT, NATIONAL_ID, DRIVING_LICENSE for individual; BUSINESS_LICENSE, CERTIFICATE_OF_INCORPORATION for business). - `entity_id_number` string, required: ID document number. - `entity_id_expiry` EntityIdExpiry, required - `valid_from` integer, required: Effective date, in milliseconds. - `valid_to` integer: Expiry date, in milliseconds. - `dob` Dob - `year` integer, required: 4-digit year. - `month` integer, required: Month, 1–12. - `day` integer, required: Day of month, 1–31. - `business_registration` BusinessRegistration - `reg_number` string: Registration number. - `reg_country` string: Country of registration. - `established_at` integer: Date of establishment. - `address` Address, required - `line1` string, required: Address line 1. - `line2` string: Address line 2. - `line3` string: Address line 3. - `country` string, required: Country code. - `city` string: City. - `state` string: State / province. - `postal_code` string: Postal code. - `merchant_category` 'GENERAL_RETAIL' | 'SUPERMARKET_CONVENIENCE' | 'FASHION_AND_ACCESSORIES' | 'FOOD_AND_BEVERAGE' | 'DIGITAL_CONTENT_AND_SAAS' | 'GAMING_AND_ENTERTAINMENT' | 'TRAVEL_AND_TICKETING' | 'RIDE_HAILING_AND_TRANSPORT' | 'HOSPITALITY_AND_LEISURE' | 'EDUCATION' | 'HEALTHCARE_AND_WELLNESS' | 'FINANCIAL_SERVICES' | 'CRYPTO_AND_WEB3' | 'UTILITIES_AND_BILLS' | 'CHARITY_AND_NONPROFIT' | 'OTHER', required: Merchant category. See Merchant Category Enumeration. - `website` string: Business website. - `user_agreement` boolean, required: Whether the user has signed the agreement. - `ubo_list` Ubo[]: List of legal representative(s) and/or ultimate beneficial owner(s) (UBO). Required when entity_type is BUSINESS. - `country` string, required: Country ISO code. - `full_name` string, required: Full name of the individual. - `dob` Dob, required - `year` integer, required: 4-digit year. - `month` integer, required: Month, 1–12. - `day` integer, required: Day of month, 1–31. - `id_type` 'PASSPORT' | 'NATIONAL_ID' | 'DRIVING_LICENSE', required: Type of identification document for the individual. - `id_number` string, required: Identification document number. - `id_expiry` EntityIdExpiry, required - `valid_from` integer, required: Effective date, in milliseconds. - `valid_to` integer: Expiry date, in milliseconds. - `relationship` Relationship, required - `is_representative` boolean: Whether the individual is a legal representative. - `is_owner` boolean: Whether the individual is a beneficial owner. - `percent_ownership` string: Required when is_owner is true; represents the ownership percentage, for example 30.01. - `metadata` object: Additional key–value metadata. ## Changes - **2026-09-04** `62d31c7e909a`: 6 warning - added the new `ACTIVE` enum value to the `data/status` response property for the response status `200` - added the new `FAIL` enum value to the `data/status` response property for the response status `200` - added the new `INIT` enum value to the `data/status` response property for the response status `200` - added the new `NONE` enum value to the `data/status` response property for the response status `200` - …2 more [Operation history](https://skmtc.dev/gate/apis/gatepay-institutional-api/changes/merchant/open/institution/v1/accounts/create/post.md) --- [API](https://skmtc.dev/gate/apis/gatepay-institutional-api.md) - [All operations](https://skmtc.dev/gate/apis/gatepay-institutional-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gate/apis/gatepay-institutional-api/revisions/4627cdb35251?raw)