> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Platform Fee & Funds Allocation

> Platform Fee & Funds Allocation の運用ガイドです。加盟店に必要な理由、Merchant Portal と API による4つの設定手順、今回のリリースに含まれる範囲、よくあるエラーの解決方法を説明します。

**Platform Fee & Funds Allocation** を使うと、加盟店は Payin からプラットフォーム手数料を受け取り、残りを同じ取引の中で自社の Payments Account に配分できます。このページは運用ガイドです。対象となる加盟店、加盟店の設定手順、問題が起きたときの確認事項を説明します。

配分の計算方法は [Platform Fees and Fund Splitting](/ja/platform-overview/clever-concepts/platform-fees) を、API の連携全体は [Split Payins with Platform Fees](/ja/developer-reference/api-use-cases/split-payins-with-platform-fees) を参照してください。

このページでは次の用語を使います。

| 用語 | 別の表記 | 意味 |
| - | - | - |
| **Collecting Payments Account** | API ドキュメントとエラーメッセージでは「receiving account」 | Payin を受け取る Payments Account です。プラットフォーム手数料を保持し、そこから Hello Clever の決済手数料を支払います。 |
| **Allocation Accounts** | Merchant Portal では **Recipients**、API では `recipients` | Payin の配分を受け取る、その他の Payments Account です。 |
| **Allocation profile** | | 保存されたルールです。プラットフォーム手数料と、受取スロットごとの配分率を定めます。 |
| **Fund splitting** | | 加盟店が配分を利用できるよう、Hello Clever が通貨ごとに有効化する設定です。 |

***

## この機能が必要な理由

今回のリリースまでは、複数の当事者のために1件の支払いを回収するプラットフォームは、全額を1つの Payments Account で受け取っていました。その後、支払いが届いてから各当事者の取り分を計算し、自分で資金を移す必要がありました。そのため消込の手間が増え、各当事者に資金が届くまでに時間がかかり、プラットフォーム手数料を受け取る仕組みも用意されていませんでした。

この機能では、Hello Clever が Payin の一部として支払いを配分します。各 Allocation Account の取り分はそれぞれの残高に反映されて元の Payin に紐づき、プラットフォーム手数料は Collecting Payments Account に残ります。

### 着目すべきサイン

次のいずれかに当てはまる加盟店は、この機能に適している可能性があります。

| サイン | 例 |
| - | - |
| 1件の顧客の支払いを複数の当事者に渡す必要がある | 複数の販売者の商品を含むマーケットプレイスの注文 |
| 支払いごとに手数料やプラットフォーム手数料を受け取っている | 予約ごとに 10% を受け取る予約プラットフォーム |
| 支払いのたびに自社のアカウント間で資金を移している | フランチャイズの売上から各店舗の取り分を渡す本部 |
| 販売者や店舗ごとに残高を持つ [Clever Connect](/ja/platform-overview/clever-concepts/clever-connect-vs-standard) を運用している、または運用予定である | 顧客企業ごとに Payments Account を持つ SaaS プラットフォーム |

加盟店は[事前準備](#before-you-start)の条件も満たす必要があります。残高モデルはオンボーディング後に変更できないため、Aggregated Balance を利用する加盟店はこの機能を使えません。

***

## 事前準備

加盟店に手順を案内する前に、次の3点をすべて確認してください。

* **Dedicated Balance。** Merchant Portal で **Payments Accounts** > **All Balances** を開きます。Dedicated Balance のアカウントでは、ページタイトルの下に **Dedicated balance** と表示されます。
* **対応通貨。** Fund splitting は AUD、USD、JPY、VND、ARS、IDR、INR、KES で有効化できます。
* **その通貨で fund splitting が有効になっていること。** Hello Clever が通貨ごとに有効化します。有効になっていない場合、すべてのリクエストが `Fund splitting is not enabled for this currency` で失敗します。

***

## 加盟店の利用開始手順

**1. ステップ1: 支払いを回収する Payments Account を作成する**

加盟店は [Merchant Portal](/ja/portal/overview) の右上にある **Create account** をクリックし、顧客の支払いを回収するための [Payments Account を追加](/ja/portal/balances#adding-an-account)します。これが **Collecting Payments Account** です。

加盟店は、このアカウントの `app-id` と `secret-key` を使って Payin を作成します。

**2. ステップ2: Allocation Accounts を作成する**

加盟店は、取り分を受け取る当事者ごとに Payments Account を1つずつ追加します（たとえば販売者ごとに1つ）。これも **Create account** から行います。どのアカウントも Collecting Payments Account と同じ通貨である必要があります。新しいアカウントは **All Balances** 画面の **Payments Accounts** の表に、ステータス **Active** で表示されます。

Allocation Accounts を一覧するには、**Collecting Payments Account** の `app-id` と `secret-key` を使って [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts) を呼び出します。レスポンスには各アカウントの `account_uuid` が含まれます。Collecting Payments Account は配分を受け取れないため、一覧には含まれません。

**3. ステップ3: allocation profile を設定する**

allocation profile は Merchant Portal で作成します。

1. 通貨を選び、**Payments Accounts** > **All Balances** を開いて **Manage allocation profiles** をクリックします。**Allocation Profiles** の一覧に、各 profile とそのステータスが表示されます。
2. **Allocation Profiles** の横にある **+** をクリックします。
3. **General** で **Profile name** を入力します。
4. **Allocation Rules** で **Platform fee** を入力します。取引金額に対する割合に、profile の通貨での任意の固定額を加えたものです。割合のみの手数料にする場合は、固定額を `0.00` のままにします。
5. **Recipients** で、スロットごとに **Allocation share** を入力します（**Recipient 1**、**Recipient 2** など）。1つの profile に設定できるスロットは最大5つです。配分率はそれだけで合計 **100%** にする必要があります。プラットフォーム手数料は先に差し引かれ、この合計には含まれません。配分率は手数料を差し引いた残りを分けるものです。ここではアカウントを選びません。アカウントはステップ4の API 呼び出しで指定します。
6. **Live Preview** を確認します。一般的な **Transaction amount** を入力し、加盟店が受け付ける **Payment method** を1つずつ選びます。対象は PayID、Visa、Mastercard、American Express (Amex)、Diners（それぞれ国内と海外）と **Other card** です。各手段に **Processing fee** が表示されます。**Collecting Payments Account** のパネルには、各受取先への配分額、**Platform fee collected**、**Processing fee**、**Amount (Net)** が表示されます。各受取先のパネルには **Transaction amount** と **Amount (Net)** が表示されます。
7. **Save** をクリックします。profile が一覧に **Active** として表示されます。
8. profile を選び、**Profile ID**（`map_...`）の横にあるコピーアイコンをクリックします。加盟店はステップ4でこの ID を使います。

> [!WARNING]
>
> プラットフォーム手数料が決済手数料を賄えないという警告が Live Preview に表示された場合、その金額と決済手段の Payin は**拒否されます**。それでも Portal では profile を保存できます。本番運用の前に、プラットフォーム手数料を引き上げるか固定額を追加してください。

> [!NOTE]
>
> 今回のリリースでは、保存した profile を編集できません。**Edit** ボタンは使用できません。配分を変更するには、新しい profile を作成し、古い profile の **Deactivate** をクリックします。無効にした profile は新しい Payin に使えません。

**4. ステップ4: API で支払いを処理し、資金を配分する**

加盟店は Collecting Payments Account のキーを使い、各 v2 Payin または各 Payment Gateway 3 の決済リンクに `allocation_profile` オブジェクトを追加します。

```json theme={null}
"allocation_profile": {
  "uuid": "map_12OndtdVndcO",
  "recipients": ["WJWAOSCM", "4A0FWJPW"]
}
```

* `uuid`: ステップ3の Profile ID です。profile は **Active** で、Payin と同じ通貨である必要があります。
* `recipients`: ステップ2の `account_uuid` を、スロットの順番どおりに指定します。最初のアカウントが Recipient 1 の取り分を受け取ります。スロットごとに Allocation Account をちょうど1つ、それぞれ1回だけ指定し、Collecting Payments Account は指定しません。

レスポンスの `allocation_profile` に、適用された配分が返されます。決済リンクの場合は、顧客の支払い後に表示されます。まずサンドボックスで一連の流れを加盟店にテストしてもらってください。リクエスト、レスポンス、サンドボックスでのテストの全体は [Split Payins with Platform Fees](/ja/developer-reference/api-use-cases/split-payins-with-platform-fees) を参照してください。

***

## 結果の確認

たとえば、プラットフォーム手数料 5%、固定額 AUD 2.00、Recipient 1 を 40%、Recipient 2 を 60%（40 + 60 = 100）に設定した profile では、AUD 1,000.00 の PayID の Payin は次のように配分されます。

| アカウント | 計算 | 金額 (AUD) |
| - | - | - |
| Collecting Payments Account、プラットフォーム手数料 | 1,000.00 × 5% + 2.00 | 52.00（ここから PayID の決済手数料を差し引く） |
| Recipient 1 | (1,000.00 − 52.00) × 40% | 379.20 |
| Recipient 2 | (1,000.00 − 52.00) × 60% | 568.80 |

加盟店に表示される内容:

* **Allocation Accounts:** 各取り分は、そのアカウントの履歴に独立した Payin として表示され、元の Payin に紐づきます。Allocation Accounts には個別の Webhook は送信されません。
* **Collecting Payments Account:** 受け取ったプラットフォーム手数料とともに元の Payin が表示されます。Webhook は、通常の Payin と同様にこのアカウントのエンドポイントに送信されます。
* **カード決済:** カードへの請求後、カードブランドと決済手数料が判明した時点で配分が表示されます。銀行振込、PayID、QR などカード以外の Payin は、Payin の作成時に配分されます。
* **精算:** 各 Payments Account が自分の残高を精算します。

顧客の支払額が請求額より多い、または少ない場合、配分は受け取った金額で再計算されます。

***

## 返金

配分された Payin は、Collecting Payments Account にある元の Payin から返金します。返金はこのアカウントの残高から差し引かれ、Allocation Accounts の取り分は自動では**戻されません**。返金の前に、Collecting Payments Account に十分な資金があることを確認してください。Allocation Account の取り分から返金を始めることはできません。

***

## リリースの範囲

| 今回のリリースに含まれるもの | 今回のリリースに含まれないもの |
| - | - |
| Merchant Portal での allocation profile の作成 | allocation profile の**編集**。**Edit** ボタンは使用できません。 |
| 配分と決済手数料の Live Preview | **配分のバージョン履歴** |
| profile の無効化 | |
| API による Allocation Accounts の一覧取得 | |
| `allocation_profile` による v2 Payin と Payment Gateway 3 決済リンクの配分 | |

***

## トラブルシューティング

配分が無効な Payin は、資金が動く前に拒否されます。エラーメッセージの一覧は [Split Payins with Platform Fees](/ja/developer-reference/api-use-cases/split-payins-with-platform-fees#errors) を参照してください。

| エラーメッセージ | 対処 |
| - | - |
| `Fund splitting is not enabled for this currency...` | その通貨で fund splitting を有効化するよう Hello Clever に依頼します。通貨が対応しているかも確認します。 |
| `This feature is only available for merchants with dedicated balance mode enabled.` | 加盟店は Aggregated Balance を利用しています。このアカウントではこの機能を使えません。 |
| `Allocation profile not found or inactive.` | Profile ID が正しくコピーされているか、profile が **Active** と表示されているかを確認します。 |
| `Allocation profile currency does not match payin currency.` | Payin と同じ通貨で作成した profile を使います。 |
| `Allocation profile recipients count does not match.` | profile のスロットごとに Allocation Account を1つ指定します。 |
| `Each allocation recipient must be a different account.` | 重複しているアカウントを削除します。 |
| `The receiving account cannot be one of the allocation recipients.` | `recipients` から Collecting Payments Account を削除します。 |
| `One or more recipient accounts are invalid for this merchant/currency.` | Collecting Payments Account のキーで呼び出した Get Allocation Recipient Accounts の `account_uuid` を使います。 |
| `Platform fee must be lower than the payin amount...` | Payin 金額を引き上げるか、プラットフォーム手数料を下げた profile を作成します。 |
| `Platform fee is lower than the transaction fee for this payin...` | プラットフォーム手数料を引き上げるか固定額を加えた profile を作成し、古い profile を無効にします。Live Preview で金額と決済手段を確認してください。 |


## Related topics

- [2026年10月](/ja/release-notes/2026-10.md)
- [Platform Fees and Fund Splitting](/ja/platform-overview/clever-concepts/platform-fees.md)
- [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.