Payout Merchant onboarding

Register a Payout Merchant account for your seller (Marketplace Use Case)

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 (both Corporation and Sole Proprietorship) to register a Payout Merchant account.
  2. Payout Merchant must have a Japanese Bank Account to receive payouts in JPY from us.

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"
Request AttributeTypeDescription
namestringPayout Merchant's name
platform_roledropdownThe role of sub-merchant account. Please specify it as payouthere.

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",
    "payments_enabled": false,
    "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 register Payout Merchant account. 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.

TypeDescription
stringA string
dropdownA dropdown of values. field_properties['enum'] will contain the translation ↔ value pairings
radioA radio selection. field_properties['enum'] will contain the translation ↔ value pairings
checkboxA true/false checkbox field.
urla URL
texta text box intended for longer values (ex: descriptions) than string
emailan email
dateDatepicker that formats the date as “YYYY-MM-DD”
integera non-negative integer field
file_uploadA 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 ids of the files uploaded.
single_file_uploadA 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_agreementShould be represented as a checkbox, but will also have an extra external_links field property that links to the actual service agreement(s)

(2) field_properties

field_properties provide information on the properties of the field.

PropertyDescriptionExample
enumA dictionary of option ↔ value mapping. The option is localized based on locale"enum": { "Sole Proprietor": "sole_proprietor", "Corporation": "corporation" }
minLengthminimum length of the string/text"minLength": 1
minimumminimum value for fields of integer field_type"minimum": 0
maximummaximum value for fields of integer field_type"maximum": 2147483647
formatFollows the possible built-in formats as specified by https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats

Currently only date or email
"format": "email"
patternRegex pattern for formatting values"pattern": "^([() \-_+]_[0-9]){10}\[() \-_+0-9]\_$"
external_linksa list of URLs linking to hosted service agreements"external_links": ["https://example.com"]

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.

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.

FieldTypeDescription
company_information.company_countrydropdownCountry of company's entity.
- Since only a Japanese entity is supported to use our service, you must select JP.
company_information.corporation_typeradioThe type of company, eithercorporation or sole_proprietor
company_information.company_phonephone_numberCompany's phone number
company_information.share_capital_amountintegerCompany's share capital.
- This field is required when the company type is corporation, .
company_information.share_capital_currencydropdownThe currency of company's share capital.
- This field is required when the company type is corporation, .
company_information.registration_numberstringThe corporate number is a 13-digit unique identifier for every Japanese corporation. (reference)
- This field is required when the company type is corporation.
company_information.company_namestringCompany's name
company_information.company_name_kanastringCompany's Katakana name
company_information.company_name_alphabetstringCompany's Alphabet name
company_information.company_postal_codestringPostal code of company's address
company_information.company_prefecture_statestringPrefecture of company's address
company_information.company_prefecture_state_kanastringPrefecture of company's address in Katakana
company_information.company_citystringCity of company's address
company_information.company_city_kanastringCity of company's address in Katakana
company_information.company_addressstringCompany's address
company_information.company_address_kanastringCompany's address in Katakana

(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 must also be the Applicant, you only need to fill out representative_directorrelated fields.
FieldTypeDescription
representative_director_information.first_namestringRepresentative Director's first name
representative_director_information.first_name_kanastringRepresentative Director's first name in Katakana
representative_director_information.last_namestringRepresentative Director's last name
representative_director_information.last_name_kanastringRepresentative Director's last name in Katakana
representative_director_information.date_of_birthdateRepresentative Director's date of birth
representative_director_information.genderradioRepresentative Director's gender
representative_director_information.countrydropdownCountry of Representative Director's residence address
representative_director_information.postal_codestringPostal code of Representative Director's residence address
representative_director_information.prefecture_statestringPrefecture of Representative Director's residence address
representative_director_information.prefecture_state_kanastringPrefecture of Representative Director's residence address in Katakana
representative_director_information.citystringCity of Representative Director's residence address
representative_director_information.city_kanastringCity of Representative Director's residence address in Katakana
representative_director_information.addressstringAddress of Representative Director's residence address
representative_director_information.address_kanastringAddress of Representative Director's residence address in Katakana
representative_director_information.phonestringPhone number of Representative Director
representative_director_information.identity_document_typedropdownIf the Representative Director is the Applicant, this field is required.
- We support four types of identify documents:
1. Passport
2. Driver's license
3. ID card
4. My Number Card
representative_director_information.identity_frontsingle_file_uploadUpload a picture or scan of the front side of the Representative Director's identity document
(ps. missing)
representative_director_information.identity_backsingle_file_uploadUpload a picture or scan of the back side of the Representative Director's identity document
- Back side is required if providing Driver's License or ID Card.
(ps. missing)
applicant_information.first_namestringApplicant's first name
applicant_information.first_name_kanastringApplicant's first name in Katakana
applicant_information.last_namestringApplicant's last name
applicant_information.last_name_kanastringApplicant's last name in Katakana
applicant_information.countrydropdownCountry of Applicant's residence address
applicant_information.genderradioApplicant's gender
applicant_information.date_of_birthdateApplicant's date of birth
applicant_information.identity_document_typedropdownIf the Applicant is different from the Representative Director, this field is required.
- We support four types of identify documents:
1. Passport
2. Driver's license
3. ID card
4. My Number Card
applicant_information.identity_frontsingle_file_uploadUpload a picture or scan of the front side of the Applicant's identity document
applicant_information.identity_backsingle_file_uploadUpload a picture or scan of the back side of the Applicant's identity document
- Back side is required if providing Driver's License or ID Card.

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

FieldTypeDescription
bank_account_information.transfer_typedropdownLimited to Japanese bank accounts. Therefore, the option is limited to domestic.
bank_account_information.default_frequencydropdownYou can decide the frequency that KOMOJU pays out to your user, either weekly or monthly.
- Learn more about payout frequency here
bank_account_information.zengin_bank_namestringBank's name
bank_account_information.zengin_bank_codestringBank's code
bank_account_information.zengin_branch_namestringBank branch's name
bank_account_information.zengin_branch_codestringBank branch's code
bank_account_information.zengin_account_typedropdownThe bank account type, either ordinary or checking
bank_account_information.zengin_account_numberstringThe bank account number. Please refer to this guide before filling out.
- If the bank of your bank account is under ゆうちょ銀行, please also refer to this guide to see how to convert 8-digit ゆうちょ銀行's account number to 7 digits.
bank_account_information.zengin_account_holder_kanastringAccount 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.currencydropdownLimited to JPY option since we only support Japanese domestic bank accounts for payout.

6. Checking submitted information

Querying the Liveapplication: Show again after submitting information will populate submitted_fields 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