Payout Merchant onboarding

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

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

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)
multi_selectA 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

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_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 ofnewly_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.

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, eithercorporation 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)

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

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

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 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_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

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