はじめに

「マーケットプレイス加盟店」事業者として、マーケットプレイス向けを導入するには、API 経由で販売者/ユーザーごとに「マーケットプレイス事業者」アカウントを登録する必要があります。

マーケットプレイス事業者アカウントを登録するには、次の前提条件を確認する必要があります。

1. マーケットプレイス事業者アカウントの登録は、日本の法人様 (法人および個人事業主を含む) のみ受け付けております。
2. 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"

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 は、ユーザーに表示されるフォーム コンポーネントのタイプを指示して、期待される値の区別と書式設定を支援するためのものです。

(2) field_properties

field_properties は、フィールドのプロパティに関する情報を提供します。

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) 企業情報

以下は、会社関連の必須情報をまとめたリストです。

(2) 個人情報

以下は代表取締役および申請者に関する必須情報をまとめたリストです。

法人の場合:

• 代表取締役と申請者は同一人物でもかまいません。
• 申請者は、法人契約に関する決定権を有する人物でなければなりません。

個人事業主の場合:

• 代表取締役と申請者が同一人物の場合は、representative_director に関する項目のみ入力してください。

(3) 銀行口座情報

以下は、銀行口座関連の必須情報をまとめたリストです。

• 法人の場合は、お申込みいただいた法人名義のみ口座登録が可能です。個人事業主の場合は、代表者名または屋号のみで口座を登録できます。
• 銀行口座情報を正しく入力するために、まずこちらのガイドをお読みください。

❗️

払い出しが遅れる可能性があります

口座名義人名が間違っている場合、払い出しの受け取りが遅れる可能性があります。銀行通帳に記載されている半角カナ名を正確に入力してください。

6.送信した情報の確認

Liveapplication: Show をもう一度クエリすると、送信したすべての情報を submitted_fields 配列で確認できます。その際、以前提出した情報 (ある場合) も表示されます。

7.Webhook を設定する

Webhook を設定してイベントにサブスクライブすると、マーケットプレイス事業者の申請の審査ステータスが更新された直後に通知を受け取ることができます。

• Platform Model の Webhook イベントの詳細はこちら