Payout Merchant onboarding
Register a Payout Merchant account for your seller (Marketplace Use Case)
Get started
As a Platform Merchant (Platform Business), you are required to register a "Payout Merchant" account for each of your sellers via our APIs.
Key prerequisites:
- We only accept Japanese entities (both Corporations and Sole Proprietorships) to register a Payout Merchant account.
- 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 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 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.
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 |
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 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 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.
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
Updated about 1 month ago