マーケットプレイス事業者のオンボーディング
「マーケットプレイス事業者」アカウントを登録する
はじめに
「マーケットプレイス加盟店」事業者として、マーケットプレイス向けを導入するには、API 経由で販売者/ユーザーごとに「マーケットプレイス事業者」アカウントを登録する必要があります。
マーケットプレイス事業者アカウントを登録するには、次の前提条件を確認する必要があります。
- マーケットプレイス事業者アカウントの登録は、日本の法人様 (法人および個人事業主を含む) のみ受け付けております。
- KOMOJU から日本円で払い出しを受け取るには、日本の銀行口座をお持ちであることが条件となります。
1.マーケットプレイス事業者アカウントを作成する
Merchant: Create をリクエストし、platform_role
を 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"
リクエスト属性 | 型 | 説明 |
---|---|---|
name | string | マーケットプレイス事業者名 |
platform_role | dropdown | サブ加盟店アカウントの役割。ここでは payout と指定してください。 |
2.マーケットプレイス事業者の live_application に必須フィールドを問い合わせる
Liveapplication: Show API を前のステップで受け取ったマーケットプレイス事業者の uuid
を使用してリクエストします。
curl -X GET https://komoju.com/api/v1/live_application/{id}?locale=en \
-u platform_merchant_secret_key:
レスポンス例
{
"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": []
}
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]*$"
}
field
は、そのフィールドの情報を送信するときに使用するプロパティ名です。field_name
は、ユーザーに表示される、ローカライズされたフィールドの名前です。field_type
は、表示されるコンポーネントのタイプです。field_properties
には、フィールドの値の制限事項に関する情報が含まれています。
(1) field_types
異なる field_types
は、ユーザーに表示されるフォーム コンポーネントのタイプを指示して、期待される値の区別と書式設定を支援するためのものです。
型 | 説明 |
---|---|
string | 文字列 |
dropdown | 値のドロップダウン。field_properties['enum'] には翻訳 ↔︎ 値のペアが含まれます。 |
radio | ラジオボタンでの選択。field_properties['enum'] には翻訳 ↔︎ 値のペアが含まれます。 |
checkbox | true/false のチェックボックスフィールド。 |
url | URL |
text | string よりも長い値 (説明など) を入力するためのテキストボックス |
E メール | |
date | 日付を「YYYY-MM-DD」としてフォーマットする日付ピッカー |
integer | 非負の整数フィールド |
file_upload | 複数のファイルをアップロードできるフィールド。ファイルは加盟店ファイルアップロードエンドポイントにアップロードする必要があります。フィールドの値は、アップロードされたファイルの id のリストになります。 |
single_file_upload | 1 つのファイルをアップロードできるフィールド。ファイルは加盟店ファイルアップロードエンドポイントにアップロードする必要があります。フィールドの値は、アップロードされたファイルの id になります。 |
service_agreement | チェックボックスとして表す必要がありますが、実際のサービス利用規約契約にリンクする追加の external_links フィールドプロパティも含まれます。 |
(2) field_properties
field_properties
は、フィールドのプロパティに関する情報を提供します。
Property | 型 | 例 |
---|---|---|
enum | オプション ↔ 値のマッピング辞書。オプションは locale に従ってローカライズされます。 | "enum": { "Sole Proprietor": "sole_proprietor", "Corporation": "corporation" } |
minLength | 文字列またはテキストの最小長 | "minLength": 1 |
minimum | integer field_type のを持つフィールドの最小値 | "minimum": 0 |
maximum | integer field_type のを持つフィールドの最大値 | "maximum": 2147483647 |
format | https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats で指定された可能な組み込み形式に従います。 現在は date または email のみです。 | "format": "email" |
pattern | 値をフォーマットするための正規表現パターン | "pattern": "^([() \-_+]_[0-9]){10}\[() \-_+0-9]\_$" |
external_links | ホスト型サービス契約にリンクしている URL のリスト | "external_links": ["https://example.com"] |
3.事業者のファイルのアップロード
一部の field_type
(single_file_upload
、file_upload
) では、まず事業者ファイル API 経由でファイルをアップロードし、次に UUID を live_application の値として送信する必要があります。
File: Create API をリクエストし、マーケットプレイス事業者のオンボーディング用のファイルをアップロードします。
アップロードできる形式は jpg、png、pdf のみです。また、各ファイルのサイズの上限は 10 MB です。
curl -X POST https://komoju.com/api/v1/merchants/{id}/files \
-u platform_merchant_secret_key: \
-F "paper=/path/to/file"
レスポンスは次のようになります。
{
"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.フィールドの送信
ステップ 2 で受け取った required_fields
に基づき、マーケットプレイス事業者の情報を Live Application: Update API 経由で送信できます。
次の例では、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"
成功した場合、レスポンスには、送信された内容に基づいて必要となった追加フィールドが含まれます。company_name
の場合、値 company_name
に依存する追加フィールドがないため、newly_required_fields
は空白になります。
newly_required_fields
の例
company_information.corporation_type
を sole_proprietor
として送信した場合
curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
-u platform_merchant_secret_key: \
-d "company_information.corporation_type=sole_proprietor"
レスポンスに newly_required_fields
に 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
は update
時にのみ表示され、live_application への最後の更新の結果としてフォームに追加される新しいフィールドを返します。
5.live_application の完了
必要な情報はユーザーの状況 (法人、個人事業主など) に応じて異なる可能性があるため、API レスポンスでは、required_fields
配列と newly_required_fields
配列の下に追加のフィールドを提供することで、オンボーディングフロー全体をステップごとにガイドします。
live_application フィールドは、required_fields
、newly_required_fields
、errored_fields
がすべて空白になるまで入力し続ける必要があります。その時点で、申請が完了したとみなされます。
必要な情報は大きく 3 つのカテゴリーに分かれており、それぞれのカテゴリーで大まかな項目を確認できます。
(1) 企業情報
以下は、会社関連の必須情報をまとめたリストです。
フィールド | 型 | 説明 |
---|---|---|
company_information.company_country | dropdown | 会社の事業体の国。 - 現時点で KOMOJU のサービスを利用できるのは日本の法人様のみであるため、 JP を選択する必要があります。 |
company_information.corporation_type | radio | 会社の種類。corporation または sole_proprietor 。 |
company_information.company_phone | phone_number | 会社の電話番号 |
company_information.share_capital_amount | integer | 会社の株式資本 - 会社の種類が corporation の場合、このフィールドは必須です。 |
company_information.share_capital_currency | dropdown | 会社の株式資本の通貨。 - 会社の種類が corporation の場合、このフィールドは必須です。 |
company_information.registration_number | string | 法人番号は、すべての日本法人が持つ 13 桁の一意の識別子です。(参照 ) - 会社の種類が corporation の場合、このフィールドは必須です。 |
company_information.company_name | string | 会社名 |
company_information.company_name_kana | string | 会社名のカタカナ表記 |
company_information.company_name_alphabet | string | 会社名のアルファベット表記 |
company_information.company_postal_code | string | 会社の住所の郵便番号 |
company_information.company_prefecture_state | string | 会社の住所の都道府県 |
company_information.company_prefecture_state_kana | string | 会社の住所の都道府県のカタカナ表記 |
company_information.company_city | string | 会社の住所の市区町村 |
company_information.company_city_kana | string | 会社の住所の市区町村のカタカナ表記 |
company_information.company_address | string | 会社の住所 |
company_information.company_address_kana | string | 会社の住所のカタカナ表記 |
company_information.company_url (*) | url | 会社の公式サイトの URL。 - マーケットプレイス事業者に企業サイトがない場合は、null のままで問題ありません。 |
(2) 個人情報
以下は代表取締役および申請者に関する必須情報をまとめたリストです。
法人の場合:
- 代表取締役と申請者は同一人物でもかまいません。
- 申請者は、法人契約に関する決定権を有する人物でなければなりません。
個人事業主の場合:
- 代表取締役と申請者が同一人物の場合は、
representative_director
に関する項目のみ入力してください。
フィールド | 型 | 説明 |
---|---|---|
representative_director_information.first_name | string | 代表取締役の名 |
representative_director_information.first_name_kana | string | 代表取締役の名のカタカナ表記 |
representative_director_information.last_name | string | 代表取締役の姓 |
representative_director_information.last_name_kana | string | 代表取締役の姓のカタカナ表記 |
representative_director_information.date_of_birth | date | 代表取締役の生年月日 |
representative_director_information.gender | radio | 代表取締役の性別 |
representative_director_information.country | dropdown | 代表取締役の自宅住所の国 |
representative_director_information.postal_code | string | 代表取締役の自宅住所の郵便番号 |
representative_director_information.prefecture_state | string | 代表取締役の自宅住所の都道府県 |
representative_director_information.prefecture_state_kana | string | 代表取締役の自宅住所の都道府県のカタカナ表記 |
representative_director_information.city | string | 代表取締役の自宅住所の市区町村 |
representative_director_information.city_kana | string | 代表取締役の自宅住所の市区町村のカタカナ表記 |
representative_director_information.address | string | 代表取締役の自宅住所の番地 |
representative_director_information.address_kana | string | 代表取締役の自宅住所の番地のカタカナ表記 |
representative_director_building.name_kana (*) | string | 代表取締役の自宅住所の建物名。 - 住所に建物名がない場合は、null のままで問題ありません。 |
representative_director_building.name_kana (*) | string | 代表取締役の自宅住所の建物名のカタカナ表記 -住所に建物名がない場合は、null のままで問題ありません。 |
representative_director_information.phone | string | 代表取締役の電話番号 |
applicant_information.country | dropdown | 申請者の自宅住所の国 - 会社の種類が corporation の場合、このフィールドは必須です。 |
applicant_information.first_name | string | 申請者の名 - 会社の種類が corporation の場合、このフィールドは必須です。 |
applicant_information.first_name_kana | string | 申請者の名のカタカナ表記 - 会社の種類が corporation の場合、このフィールドは必須です。 |
applicant_information.last_name | string | 申請者の姓 - 会社の種類が corporation の場合、このフィールドは必須です。 |
applicant_information.last_name_kana | string | 申請者の姓のカタカナ表記 - 会社の種類が corporation の場合、このフィールドは必須です。 |
applicant_information.gender | radio | 申請者の性別 - 会社の種類が corporation の場合、このフィールドは必須です。 |
applicant_information.date_of_birth | date | 申請者の生年月日 - 会社の種類が corporation の場合、このフィールドは必須です。 |
(3) 銀行口座情報
以下は、銀行口座関連の必須情報をまとめたリストです。
- 法人の場合は、お申込みいただいた法人名義のみ口座登録が可能です。個人事業主の場合は、代表者名または屋号のみで口座を登録できます。
- 銀行口座情報を正しく入力するために、まずこちらのガイドをお読みください。
払い出しが遅れる可能性があります
口座名義人名が間違っている場合、払い出しの受け取りが遅れる可能性があります。銀行通帳に記載されている半角カナ名を正確に入力してください。
フィールド | 型 | 説明 |
---|---|---|
bank_account_information.transfer_type | dropdown | 日本の銀行口座に限ります。したがって、オプションは domestic に限定されます。 |
bank_account_information.default_frequency | dropdown | KOMOJU が貴社のユーザーに支払う頻度を、weekly (週次) または monthly (月次) に設定できます。- 払い出しの詳細については、こちら |
bank_account_information.zengin_bank_name | string | 銀行名 |
bank_account_information.zengin_bank_code | string | 銀行コード |
bank_account_information.zengin_branch_name | string | 銀行支店名 |
bank_account_information.zengin_branch_code | string | 銀行支店コード |
bank_account_information.zengin_account_type | dropdown | 銀行口座の種類。ordinary または checking 。 |
bank_account_information.zengin_account_number | string | 銀行口座番号。 - 記入する前に、こちらのガイド をよくお読みください。ゆうちょ銀行の口座をお持ちの場合は、ゆうちょ銀行の口座番号 8 桁を 7 桁に変換する方法について、こちらのガイド もご参照ください。 |
bank_account_information.zengin_account_holder_kana | string | 口座名義人のカタカナ名。 - 口座名義人が間違っていると、払い出しが遅れる場合があります。銀行の通帳に記載されているとおりに、半角カナ名を正確に入力してください。 |
bank_account_information.currency | dropdown | 払い出しは日本国内の銀行口座のみ対応しているため、JPY オプションに制限されます。 |
6.送信した情報の確認
Liveapplication: Show をもう一度クエリすると、送信したすべての情報を submitted_fields
配列で確認できます。その際、以前提出した情報 (ある場合) も表示されます。
7.Webhook を設定する
Webhook を設定してイベントにサブスクライブすると、マーケットプレイス事業者の申請の審査ステータスが更新された直後に通知を受け取ることができます。
- Platform Model の Webhook イベントの詳細はこちら
Updated 3 months ago