Get started

As a "Platform Merchant (Marketplace Business)" merchant, you'll need to register a "Payout Merchant" account for each seller/user via our APIs to adopt Marketplace Use Case.

To register a Payout Merchant account, you should check the following prerequisites:

1. We only accept Japanese entities (including 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 API to create a Payout Merchant account with platform_role set to payout.

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

2. Query the payout merchant’s live_application for required fields

Request Liveapplication: Show API with payout merchant's uuid you received from the previous step.

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

Response example

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

Within required_fieldsarray, you'll able to see what kinds of information are required to proceed Payout Merchant registration. Following is the breakdown of each field property.

"field": "company_information.company_phone",
"field_name": "Company Phone",
"field_type": "phone_number",
"field_properties": {
  "minLength": 1,
  "pattern": "^([() \\-_+]*[0-9]){10}[() \\-_+0-9]*$"
}

• 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_type is the type of component that should be displayed.
• field_properties includes information about restrictions on the value of the field.

(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.

(2) field_properties

field_properties provide information on the properties of the field.

3. Uploading files for merchants

Some field_types (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 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 -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:

{
    "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. Submitting fields

Based on the required_fields received in step 2, information can now be submitted for the Payout Merchant via Live Application: Update API.

Here’s an example of submitting company_information.company_name

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 fields now required based on what was just submitted. In the case of company_name, newly_required_fields will be blank as no additional fields rely on the value company_name.

An example of newly_required_fields

If you submit sole_proprietor as the company_information.corporation_type

curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d "company_information.corporation_type=sole_proprietor"

In the response, see that newly_required_fields now includes sole_proprietor_proofs.

"newly_required_fields": [
      {
          "field": "company_information.sole_proprietor_proofs",
          "field_name": "Sole proprietor proofs",
          "field_type": "file_upload",
          "field_properties": {}
      }
  ]

newly_required_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.

5. Completing the live_application

Since the required information can be different based on your user's conditions (eg: corporation, sole proprietorship...etc), our API responses will guide you through the entire onboarding flow step-by-step by providing further fields under required_fields and newly_required_fields arrays.

The live_application fields should continue to be filled out until required_fields, newly_required_fields, and errored_fields are all empty. At that point, the application is considered complete.

Overall, there are mainly three main categories of the required information, you can check the comprehensive items under each category.

(1) Company information

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

(2) Personal Information

Below is the comprehensive list of required Representative Director and Applicant information.

In the case of a corporation:

• It's fine if the Representative Director and Applicant are the same person.
• The Applicant must be the person who has the authority to make decisions on corporate contracts.

In the case of a sole proprietorship:

• Since the Representative Director and the Applicant should be the same person, you only need to fill out representative_directorrelated fields.

(3) Bank Account information

Below is the comprehensive list of required bank account information.

• If you are a corporation, you can only register an account in the name of the corporation you applied for. If you are a sole proprietor, you can only register an account in the name of the representative or business name.
• Please read this guide first to ensure you provide the bank account information correctly.

❗️

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.

6. Checking submitted information

Querying the Liveapplication: Show again to review all submitted information populated under submitted_fields array with any previous information provided.

7. Setup the webhook

You can set up Webhook to subscribe to the events so that you'll receive a notification immediately after the review status of a Payout Merchant's application has any update.

• Learn more about Webhook events for Platform Model here