Hello Clever Developer Docs

構築するもの

1つの Payments Account（receiving account）で Payin を作成し、allocation_profile を付与します。Payin が支払われると、Hello Clever はプラットフォーム手数料を receiving account に残し、各加盟店の取り分をそれぞれの Payments Account（recipient accounts）に移します。分配の計算方法と適用タイミングは Platform Fees and Fund Splitting を参照してください。

事前準備

Dedicated Balance を利用する Clever Connect アカウント。
Payin の通貨で fund splitting が有効になっていること。担当のアカウントマネージャーにお問い合わせください。
その通貨の有効な allocation profile を Merchant Portal で作成済みであること。その 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 で取得します。

"allocation_profile": {
  "uuid": "map_tBdQGAAjkqx9",
  "recipients": ["WJWAOSCM", "4A0FWJPW"]
}

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

receiving account のキーを使って Get Allocation Recipient Accounts（GET /api/v2/merchant_allocation_profiles/accounts）を呼び出します。同じ通貨のその他の Payments Account が返されます。receiving account は常に除外されます。

Request

curl --request GET \
  --url https://api.cleverhub.co/api/v2/merchant_allocation_profiles/accounts \
  --header 'app-id: <app-id>' \
  --header 'secret-key: <secret-key>'

Response

{
  "currency": "AUD",
  "accounts": [
    { "account_uuid": "WJWAOSCM", "account_name": "Store North" },
    { "account_uuid": "4A0FWJPW", "account_name": "Store South" }
  ]
}

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

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

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

分配結果を取得する

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

方法 A: v2 の Payin

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

Request

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"]
    }
  }'

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

Response (excerpt)

{
  "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 は任意です。省略すると、顧客がチェックアウト時に決済手段を選びます。

Request

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"]
    }
  }'

Response

{
  "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 に分配が返されます。

Response (excerpt)

{
  "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 }
      ]
    }
  }
}

カード決済では、カードへの請求後に 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 を開いてテストカードで支払います。

連携の基本

プラットフォーム連携

API ユースケース

Clever AI コネクター

AI ツール

セキュリティとコンプライアンス

Split Payins with Platform Fees

構築するもの

事前準備

`allocation_profile` オブジェクト

方法 A: v2 の Payin

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

レスポンスのフィールド

Webhook

エラー

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

​構築するもの

​事前準備

​allocation_profile オブジェクト

​方法 A: v2 の Payin

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

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

​Webhook

​エラー

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

構築するもの

事前準備

`allocation_profile` オブジェクト

方法 A: v2 の Payin

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

レスポンスのフィールド

Webhook

エラー

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