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 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,
    "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.

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

(2) field_properties

field_properties provide information on the properties of the field.

3. Upload files for payout merchant

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. Submit fields

Based on the requested_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 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

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.

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

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

(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 to ensure the bank account information is entered 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. Review submitted information

Querying the Liveapplication: Show 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