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

# Split Payins with Platform Fees

> v2 の Payin と Payment Gateway 3 の決済リンクで allocation profile を送信し、各 Payin からプラットフォーム手数料を受け取って、残りを加盟店の Payments Account に分配します。

## 構築するもの

1つの Payments Account（**receiving account**）で Payin を作成し、`allocation_profile` を付与します。Payin が支払われると、Hello Clever はプラットフォーム手数料を receiving account に残し、各加盟店の取り分をそれぞれの Payments Account（**recipient accounts**）に移します。

分配の計算方法と適用タイミングは [Platform Fees and Fund Splitting](/ja/platform-overview/clever-concepts/platform-fees) を参照してください。

## 事前準備

* Dedicated Balance を利用する [Clever Connect](/ja/platform-overview/clever-concepts/clever-connect-vs-standard) アカウント。
* Payin の通貨で fund splitting が有効になっていること。担当のアカウントマネージャーにお問い合わせください。
* その通貨の有効な allocation profile を [Merchant Portal](/ja/portal/overview) で作成済みであること。その `uuid`（例: `map_tBdQGAAjkqx9`）を控えておきます。
* receiving account の `app-id` と `secret-key`。
* サンドボックスは `https://api.cleverhub.co`、本番環境は `https://api-merchant.helloclever.co` です。

## `allocation_profile` オブジェクト

Payin のリクエストで次のオブジェクトを送信します。

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| `uuid` | string | はい | Payin と同じ通貨の、有効な allocation profile の UUID。 |
| `recipients` | array of strings | はい | 受取アカウントの UUID。profile のスロットごとに1つ、profile の順番どおりに指定します。各アカウントは Payin と同じ通貨で、1回だけ指定し、receiving account は含めません。UUID は [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts) で取得します。 |

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

**1. 分配先にできるアカウントを一覧する**

receiving account のキーを使って [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts)（**GET** `/api/v2/merchant_allocation_profiles/accounts`）を呼び出します。同じ通貨のその他の Payments Account が返されます。receiving account は常に除外されます。

```bash Request theme={null}
curl --request GET \
  --url https://api.cleverhub.co/api/v2/merchant_allocation_profiles/accounts \
  --header 'app-id: <app-id>' \
  --header 'secret-key: <secret-key>'
```

```json Response theme={null}
{
  "currency": "AUD",
  "accounts": [
    { "account_uuid": "WJWAOSCM", "account_name": "Store North" },
    { "account_uuid": "4A0FWJPW", "account_name": "Store South" }
  ]
}
```

`currency` は不要です。`app-id` に紐づく receiving account から取得されます。

**2. allocation profile を指定して Payin を作成する**

v2 の Payin または Payment Gateway 3 の決済リンクに `allocation_profile` を追加します。両方の例を以下に示します。

**3. 分配結果を取得する**

Payin または決済リンクを取得します。適用された分配が `allocation_profile` に返されます。

## 方法 A: v2 の Payin

**POST** `/api/v2/payins` に `allocation_profile` を追加します。

```bash Request theme={null}
curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins \
  --header 'Content-Type: application/json' \
  --header 'app-id: <app-id>' \
  --header 'secret-key: <secret-key>' \
  --data '{
    "currency": "aud",
    "amount": 1000,
    "name": "Testing",
    "gst": false,
    "email": "customer@example.com",
    "payin_method_name": "au_payid_npp_aud",
    "payin_method_params": {},
    "description": "Order 4821",
    "webhook_notification": {
      "endpoint_url": "https://yourserver.co/notifications",
      "authorization_header": "Bearer <token>"
    },
    "allocation_profile": {
      "uuid": "map_tBdQGAAjkqx9",
      "recipients": ["WJWAOSCM", "4A0FWJPW"]
    }
  }'
```

レスポンスには適用された分配が含まれます。

```json Response (excerpt) theme={null}
{
  "uuid": "VMMAOTFQ",
  "status": "pending",
  "currency": "AUD",
  "amount": "1000.0",
  "payment_method": "au_payid_npp_aud",
  "allocation_profile": {
    "uuid": "map_tBdQGAAjkqx9",
    "platform_fee": 5,
    "platform_fee_fixed": 2.0,
    "platform_fee_amount": 52.0,
    "recipients": [
      { "account_uuid": "WJWAOSCM", "amount": 568.8 },
      { "account_uuid": "4A0FWJPW", "amount": 379.2 }
    ]
  }
}
```

## 方法 B: Payment Gateway 3 の決済リンク

**POST** `/api/v3/payin_links` に `allocation_profile` を追加します。`payin_method_code` は任意です。省略すると、顧客がチェックアウト時に決済手段を選びます。

```bash Request theme={null}
curl --request POST \
  --url https://api.cleverhub.co/api/v3/payin_links \
  --header 'Content-Type: application/json' \
  --header 'app-id: <app-id>' \
  --header 'secret-key: <secret-key>' \
  --data '{
    "amount": 1000,
    "payin_method_code": "au_payid_npp_aud",
    "description": "Order 4821",
    "sender_info": {
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Smith"
    },
    "allocation_profile": {
      "uuid": "map_tBdQGAAjkqx9",
      "recipients": ["WJWAOSCM", "4A0FWJPW"]
    }
  }'
```

```json Response theme={null}
{
  "uuid": "pi_CebQjio5F0V9",
  "payment_url": "https://paylink.cleverhub.co/cGlfQ2ViUWppbzVGMFY5",
  "expires_at": "2026-10-12T08:04:11.620Z"
}
```

この時点ではまだ支払いがないため、リンクは分配されていません。顧客が支払うと、**GET** `/api/v3/payin_links/{uuid}` の `transaction_info.allocation_profile` に分配が返されます。

```json Response (excerpt) theme={null}
{
  "uuid": "pi_CebQjio5F0V9",
  "payin_method_code": "au_payid_npp_aud",
  "amount": 1000,
  "transaction_info": {
    "uuid": "pi_CebQjio5F0V9",
    "currency": "AUD",
    "amount": 1000.0,
    "paid_amount": 1000.0,
    "status": "received",
    "allocation_profile": {
      "uuid": "map_tBdQGAAjkqx9",
      "platform_fee": 5,
      "platform_fee_fixed": 2.0,
      "platform_fee_amount": 52.0,
      "recipients": [
        { "account_uuid": "WJWAOSCM", "amount": 568.8 },
        { "account_uuid": "4A0FWJPW", "amount": 379.2 }
      ]
    }
  }
}
```

> [!NOTE]
>
> カード決済では、カードへの請求後に `allocation_profile` が表示されます。Hello Clever は、カードブランドに応じた正しい決済手数料を適用するために、分配の前にカード情報の確定を待ちます。

## レスポンスのフィールド

`allocation_profile` は、分配された Payin でのみ返されます。

| フィールド | 説明 |
| - | - |
| `uuid` | 適用された allocation profile。 |
| `platform_fee` | プラットフォーム手数料率。 |
| `platform_fee_fixed` | 固定プラットフォーム手数料（Payin の通貨）。 |
| `platform_fee_amount` | receiving account が保持するプラットフォーム手数料の合計: `amount × platform_fee% + platform_fee_fixed`。 |
| `recipients[].account_uuid` | 受取アカウントの UUID。 |
| `recipients[].amount` | そのアカウントに移された金額。 |

分配は適用時に保存されます。その後 allocation profile を変更しても、分配済みの Payin には影響しません。

## Webhook

Payin の Webhook は、他の Payin と同様に receiving account の `endpoint_url` に送信されます。受取アカウントには、取り分についての個別の Webhook は送信されません。

## エラー

リクエストは、`errors.message` に次のいずれかのメッセージを含めて拒否されます。

| メッセージ | 確認事項 |
| - | - |
| `Fund splitting is not enabled for this currency. Please contact your administrator for assistance.` | Payin の通貨で fund splitting が有効になっている必要があります。 |
| `This feature is only available for merchants with dedicated balance mode enabled.` | 加盟店が Dedicated Balance を利用している必要があります。 |
| `Allocation profile not found or inactive.` | profile の `uuid` と、profile が有効であることを確認します。 |
| `Allocation profile currency does not match payin currency.` | Payin と同じ通貨の profile を使います。 |
| `Allocation profile recipients count does not match.` | profile のスロットごとに受取先を1つ指定します。 |
| `Each allocation recipient must be a different account.` | 重複しているアカウントの UUID を削除します。 |
| `The receiving account cannot be one of the allocation recipients.` | `recipients` から receiving account を削除します。 |
| `One or more recipient accounts are invalid for this merchant/currency.` | アカウント一覧のエンドポイントで取得した、Payin と同じ通貨のアカウント UUID を使います。 |
| `Platform fee must be lower than the payin amount - can't apply this allocation profile.` | 金額を引き上げるか、プラットフォーム手数料を下げます。 |
| `Platform fee is lower than the transaction fee for this payin - can't apply this allocation profile.` | プラットフォーム手数料は、選んだ決済手段の決済手数料を賄える額である必要があります。 |

## サンドボックスでのテスト

* カード以外の手段では、**POST** `/api/v3/payins/simulate` に `{"uuid": "<payin link uuid>", "action": "completed"}` を送信して、決済リンクを支払済みにします。支払額の過不足をテストするには、別の `amount` を渡します。分配は受け取った金額で再計算されます。
* カードの場合は、`payment_url` を開いてテストカードで支払います。


## Related topics

- [Platform Fees and Fund Splitting](/ja/platform-overview/clever-concepts/platform-fees.md)
- [Setting Up Platform Fee & Funds Allocation](/ja/platform-overview/clever-concepts/platform-fee-setup.md)
- [Multi-Currency Payment API](/ja/api/v2/introduction.md)


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