---
title: "Payout Merchant Onboarding"
description: "How to register and onboard a Payout Merchant account for your sellers via the KOMOJU API, including live application fields, bank account setup, and webhook configuration."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/platform-model/payout-merchant-onboarding"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/platform-model/payout-merchant-onboarding.md"
language: en
last_modified: "2026-03-26"
---

# Get started

As a Platform Merchant (Marketplace Business), you are required to register a "Payout Merchant" account for each of your sellers via our APIs.

Key prerequisites:

1. We only accept **Japanese entities** (both Corporations and Sole Proprietorships) to register a Payout Merchant account.
2. Payout Merchant must have a **Japanese Bank Account** to receive payouts in JPY from KOMOJU.

# 1) Create a Payout Merchant account

Request [Merchant: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/platform-model/POST/merchants) API to create a Payout Merchant account with `platform_role` set to `payout`.

```curl
curl -X POST https://komoju.com/api/v1/merchants \
-u <platform merchant secret key>: \
-d name='New Payout Merchant 1' \
-d platform_role="payout"

```

| Request Attribute | Type | Description |
| --- | --- | --- |
| `name` | string | Payout Merchant's name |
| `platform_role` | dropdown | The role of sub-merchant account. Please specify it as `payout` here. |

# 2. Query the payout merchant's live_application for required fields

Request [Live Application: Show](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/platform-model/GET/live_application/%7Bmerchant_id%7D) API with payout merchant's `uuid` you received from the previous step.

```curl
curl -X GET https://komoju.com/api/v1/live_application/{id}?locale=en \
-u platform_merchant_secret_key:

```

Response example

```json
{
    "merchant_id": "5td723eoi9txn8sj545ww2mv1",
    "status": "incomplete",
    "payouts_enabled": false,
    "requested_fields": [
        {
            "field_type": "phone_number",
            "field": "company_information.company_phone",
            "field_name": "Company Phone",
            "field_properties": {
                "minLength": 1,
                "pattern": "^([() \\-_+]*[0-9]){10}[() \\-_+0-9]*$"
            },
            "optional": false
        },
      	...
    ],
    "newly_requested_fields": [],
    "errored_fields": []
}

```

Within the `requested_fields` array, you'll find the required information for Payout Merchant registration. If a field's `optional` parameter is set to `false`, the Payout Merchant must provide the relevant information. If set to `true`, they can skip it if they don't have the corresponding details.

Following is the breakdown of each field property.

```json
"field": "visa_mastercard_credit_card.access_restrictions",
"field_name": "Implemented (to be implemented)",
"field_description": "Restrict IP addresses accessible to administrators; if IP addresses cannot be restricted, set access restrictions such as basic authentication on the administrator screen.",
"field_type": "checkbox",
"field_properties": {}
"optional": false

```

- `field` is the property name that should be used when submitting information for that field.
- `field_name` is the localized name for the field that should be shown to the user.
- `field_description` is a localized explanation of what the field is asking.
- `field_type` is the type of component that should be displayed.
- `field_properties` includes information about restrictions on the value of the field.
- `optional` represents whether the field is required or not.

**(1) field_types**

Different `field_types` are meant to help direct the types of form components shown to the user to help differentiate and format expected values.

| Type | Description |
| --- | --- |
| string | A string |
| dropdown | A dropdown of values. `field_properties['enum']` will contain the translation ↔ value pairings |
| radio | A radio selection. `field_properties['enum']` will contain the translation ↔ value pairings |
| checkbox | A true/false checkbox field. |
| url | a URL |
| text | a text box intended for longer values (ex: descriptions) than `string` |
| email | an email |
| date | Datepicker that formats the date as "YYYY-MM-DD" |
| integer | a non-negative integer field |
| file_upload | A field that allows multiple files to be uploaded. The file should be uploaded to the merchant file upload endpoint. The value of the field should then be a list of the `id`s of the files uploaded. |
| single_file_upload | A field that allows one file to be uploaded. The file should be uploaded to the merchant file upload endpoint. The value of the field should then be the `id` of the file uploaded. |
| service_agreement | Should be represented as a checkbox, but will also have an extra `external_links` field property that links to the actual service agreement(s) |
| multi_select | A field that allows a list of selected options. `field_properties['items']['enum']` will contain the translation ↔ value pairings. |

**(2) field_properties**

`field_properties` provide information on the properties of the field.

| Property | Description | Example |
| --- | --- | --- |
| enum | A dictionary of option ↔ value mapping. The option is localized based on `locale` | `"enum": {"Sole Proprietor": "sole_proprietor", "Corporation": "corporation"}` |
| minLength | minimum length of the string/text | `"minLength": 1` |
| minimum | minimum value for fields of `integer` field_type | `"minimum": 0` |
| maximum | maximum value for fields of `integer` field_type | `"maximum": 2147483647` |
| format | Follows the possible built-in formats as specified by [https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats). Currently only `date` or `email` | `"format": "email"` |
| pattern | Regex pattern for formatting values | `"pattern": "^([() \\-_+]*[0-9]){10}[() \\-_+0-9]*$"` |
| external_links | a list of URLs linking to hosted service agreements | `"external_links": ["https://example.com"]` |

# 3. Upload files for payout merchant

Some `field_type`s (`single_file_upload`, `file_upload`) require that files be uploaded via our merchant file API first, then the UUID(s) submitted as the value for the live_application.

Request [File: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/platform-model/POST/merchants/%7Bmerchant_id%7D/files) API to upload the files for Payout Merchant onboarding.

We only accept jpg, png, and pdf formats. Besides, each file size should be smaller than 10MB.

```curl
curl -X POST https://komoju.com/api/v1/merchants/{id}/files \
  -u platform_merchant_secret_key: \
  -F "paper=/path/to/file"

```

The response will look like:

```json
{
    "id": "6ssx1zxovw3fgmdsdd1zuzr5u",
    "resource": "file",
    "filename": "blank.png",
    "size": 998,
    "mime_type": "image/png",
    "created_at": "2023-01-10T12:16:00.819+09:00",
    "updated_at": "2023-01-10T12:16:01.085+09:00"
}

```

# 4. Submit fields

Based on the `requested_fields` received in [step 2](https://docs.priv.staging.komoju-dev.tools/#2-query-the-payout-merchants-live_application-for-required-fields), information can now be submitted for the Payout Merchant via [Live Application: Update](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/platform-model/PATCH/live_application/%7Bmerchant_id%7D) API.

Here's an example of submitting `company_information.company_name`

```bash
curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d "company_information.company_name=My Company"

```

If successful, the response will include any additional required fields based on what was just submitted. In the case of `company_name`, `newly_requested_fields` will be blank as no additional fields rely on the value `company_name`.

**An example of `newly_requested_fields`**

If you submit `JP` as the `company_information.company_country`

```bash
curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d "company_information.company_country=JP"

```

In the response, see that `newly_requested_fields` now includes `company_information.company_name_kana`.

```json
"newly_requested_fields": [
      {
          "field": "company_information.company_name_kana",
          "field_name": "Company Name (Kana)",
          "field_type": "string",
          "field_properties": {
                "minLength": 1,
                "pattern": "^[ァ-ンｧ-ﾝﾞﾟ|{ﾞﾟ}　ーｰ －-]+$"
            }
      }
  ]

```

`newly_requested_fields` are only shown upon `update` and return new fields that should be added to the form as a result of the last update to live_application.

**For fields that allow multiple values (`multi_select`, `file_upload` field_types)**

Submit an array of values.

```curl
curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d '{
    "visa_mastercard_credit_card.countermeasures_during_card_registration":
      [ "access_restrictions_during_card_registration"]
  }'

```

# 5. Complete the Live Application

The required information may vary based on the seller's type (e.g., corporation, sole proprietorship). Our API responses will guide you through the entire onboarding process, providing additional fields under the `requested_fields` and `newly_requested_fields` arrays as needed.

The live application must be completed by filling out all fields until `requested_fields`, `newly_requested_fields`, and `errored_fields` are empty. At this stage, the status field of the application should be set to `pending`.

The information required typically falls into three categories:

## (1) Company information

Below is the comprehensive list of required company-related information.

| Field | Type | Optional | Description |
| --- | --- | --- | --- |
| `company_information.company_country` | dropdown | false | Country of company's entity. Since only a Japanese entity is supported to use our service, you must select `JP`. |
| `company_information.corporation_type` | radio | false | The type of company, either `corporation` or `sole_proprietor` |
| `company_information.company_phone` | phone_number | false | Company's phone number |
| `company_information.share_capital_amount` | integer | false | Company's share capital. This field is required when the company type is `corporation`. |
| `company_information.share_capital_currency` | dropdown | false | The currency of the company's share capital. This field is required when the company type is `corporation`. |
| `company_information.registration_number` | string | false | The corporate number is a **13-digit unique identifier** for every Japanese corporation. ([reference](https://www.houjin-bangou.nta.go.jp/en/setsumei/)). This field is required when the company type is `corporation`. |
| `company_information.company_name` | string | false | Company's name |
| `company_information.company_name_kana` | string | false | Company's Katakana name |
| `company_information.company_name_alphabet` | string | false | Company's Alphabet name |
| `company_information.company_postal_code` | string | false | Postal code of company's address |
| `company_information.company_prefecture_state` | string | false | Prefecture of company's address |
| `company_information.company_prefecture_state_kana` | string | false | Prefecture of company's address in Katakana |
| `company_information.company_city` | string | false | City of company's address |
| `company_information.company_city_kana` | string | false | City of company's address in Katakana |
| `company_information.company_address` | string | false | Company's address |
| `company_information.company_address_kana` | string | false | Company's address in Katakana |
| `company_information.company_url` | url | true | The URL of the company's official site. |

## (2) Personal Information

Below is the required information for the Representative Director and Applicant.

For Corporations:

- The Representative Director and Applicant can be the same person.
- The Applicant must have the authority to make decisions on corporate contracts.

For Sole Proprietorships:

- The Representative Director and Applicant should be the same person, so you only have to complete the `representative_director` fields.

| Field | Type | Optional | Description |
| --- | --- | --- | --- |
| `representative_director_information.first_name` | string | false | Representative Director's first name |
| `representative_director_information.first_name_kana` | string | false | Representative Director's first name in Katakana |
| `representative_director_information.last_name` | string | false | Representative Director's last name |
| `representative_director_information.last_name_kana` | string | false | Representative Director's last name in Katakana |
| `representative_director_information.date_of_birth` | date | false | Representative Director's date of birth |
| `representative_director_information.gender` | radio | false | Representative Director's gender |
| `representative_director_information.country` | dropdown | false | Country of Representative Director's residence address |
| `representative_director_information.postal_code` | string | false | Postal code of Representative Director's residence address |
| `representative_director_information.prefecture_state` | string | false | Prefecture of Representative Director's residence address |
| `representative_director_information.prefecture_state_kana` | string | false | Prefecture of Representative Director's residence address in Katakana |
| `representative_director_information.city` | string | false | City of Representative Director's residence address |
| `representative_director_information.city_kana` | string | false | City of Representative Director's residence address in Katakana |
| `representative_director_information.address` | string | false | Address of Representative Director's residence address |
| `representative_director_information.address_kana` | string | false | Address of Representative Director's residence address in Katakana |
| `representative_director_information.address_building_name` | string | true | The building name of Representative Director's residence address. |
| `representative_director_information.address_building_name_kana` | string | true | The building name in Katakana of Representative Director's residence address. |
| `representative_director_information.phone` | string | false | Phone number of Representative Director |
| `applicant_information.country` | dropdown | false | Country of Applicant's residence address. This field is required when the company type is `corporation`. |
| `applicant_information.first_name` | string | false | Applicant's first name. This field is required when the company type is `corporation`. |
| `applicant_information.first_name_kana` | string | false | Applicant's first name in Katakana. This field is required when the company type is `corporation`. |
| `applicant_information.last_name` | string | false | Applicant's last name. This field is required when the company type is `corporation`. |
| `applicant_information.last_name_kana` | string | false | Applicant's last name in Katakana. This field is required when the company type is `corporation`. |
| `applicant_information.gender` | radio | false | Applicant's gender. This field is required when the company type is `corporation`. |
| `applicant_information.date_of_birth` | date | false | Applicant's date of birth. This field is required when the company type is `corporation`. |

## (3) Bank Account information

Below is the required bank account information.

For Corporations:

- You can only register a bank account under the same name as the corporation applying.

For Sole Proprietorships:

- You can only register a bank account under the name of the representative or the business name.

Before proceeding, please read [this guide](https://help.komoju.com/hc/en-us/articles/4747456646174) to ensure the bank account information is entered correctly.

> ❌ **Error:** **Possible payout delay**
>
> If the account holder name is incorrect, there may be a delay in receiving the payout. Please make sure to accurately enter the half-width kana name as it appears in your bank passbook.

| Field | Type | Optional | Description |
| --- | --- | --- | --- |
| `bank_account_information.transfer_type` | dropdown | false | Limited to Japanese bank accounts. Therefore, the option is limited to `domestic`. |
| `bank_account_information.default_frequency` | dropdown | false | You can decide the frequency that KOMOJU pays out to your user, either `weekly` or `monthly`. Learn more about payout frequency [here](https://help.komoju.com/hc/en-us/articles/4747518278302). |
| `bank_account_information.zengin_bank_name` | string | false | Bank's name |
| `bank_account_information.zengin_bank_code` | string | false | Bank's code |
| `bank_account_information.zengin_branch_name` | string | false | Bank branch's name |
| `bank_account_information.zengin_branch_code` | string | false | Bank branch's code |
| `bank_account_information.zengin_account_type` | dropdown | false | The bank account type, either `ordinary` or `checking` |
| `bank_account_information.zengin_account_number` | string | false | The bank account number. Please refer to [this guide](https://help.komoju.com/hc/en-us/articles/4747456646174) before filling out. If the bank of your bank account is under ゆうちょ銀行, please also refer to [this guide](https://www.jp-bank.japanpost.jp/kojin/sokin/koza/kj_sk_kz_furikomi_ksk.html) to see how to convert 8-digit ゆうちょ銀行's account number to 7 digits. |
| `bank_account_information.zengin_account_holder_kana` | string | false | Account holder's Katakana name. If the account holder's name is incorrect, there may be a delay in receiving the payout. Please make sure to accurately enter the **half-width kana name** as it appears in your bank passbook. |
| `bank_account_information.currency` | dropdown | false | Limited to `JPY` option since we only support Japanese domestic bank accounts for payout. |

# 6. Review submitted information

Query the [Live Application: Show](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/platform-model/GET/live_application/%7Bmerchant_id%7D) again to review all submitted information populated under `submitted_fields` array with any previous information provided.

# 7. Set up webhook

You can set up webhooks to subscribe to events and receive notifications when there are updates to the review status of a Payout Merchant's application.

- Learn more about Webhook events for Platform Model [here](https://docs.priv.staging.komoju-dev.tools/en/docs/platform-model/webhooks-in-the-platform-model.md)