> ## 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 > Operations guide to Platform Fee & Funds Allocation: why merchants need it, the four setup steps in the Merchant Portal and API, what this release includes, and how to resolve common errors. **Platform Fee & Funds Allocation** lets a merchant keep a platform fee on a Payin and allocate the rest to its own Payments Accounts in the same transaction. This page is the operations guide: who it is for, how to set a merchant up step by step, and what to check when something fails. For how the allocation is calculated, see [Platform Fees and Fund Splitting](/platform-overview/clever-concepts/platform-fees). For the full API integration, see [Split Payins with platform fees](/developer-reference/api-use-cases/split-payins-with-platform-fees). This page uses these terms: | Term | Also shown as | Meaning | | - | - | - | | **Collecting Payments Account** | "Receiving account" in the API docs and error messages | The Payments Account that takes the Payin. It keeps the platform fee and pays Hello Clever's processing fee from it. | | **Allocation Accounts** | **Recipients** in the Merchant Portal; `recipients` in the API | The other Payments Accounts that receive an allocation share of the Payin. | | **Allocation profile** | | The saved rule: the platform fee and one allocation share per recipient slot. | | **Fund splitting** | | The per-currency setting Hello Clever enables so a merchant can use allocation. | *** ## Why this feature exists Before this release, a platform that collected one payment for several parties received the whole amount into one Payments Account. It then had to work out each party's share and move the money itself after the payment arrived. That meant extra reconciliation, a delay before each party saw its money, and no built-in way to keep a platform fee. With this feature, Hello Clever allocates the payment as part of the Payin. Each Allocation Account's share appears in its own balance, linked to the original Payin, and the platform fee stays in the Collecting Payments Account. ### Signals to look for A merchant is a likely fit when one or more of these is true: | Signal | Example | | - | - | | One customer payment is owed to more than one party | A marketplace order containing items from several sellers | | The merchant charges a commission or platform fee on each payment | A booking platform that keeps 10% of each booking | | The merchant moves money between its own accounts after every payment | Head office passing each location its share of a franchise sale | | The merchant runs, or plans to run, [Clever Connect](/platform-overview/clever-concepts/clever-connect-vs-standard) with a balance per seller or location | A SaaS platform with a Payments Account per customer business | The merchant must also meet the [prerequisites](#before-you-start). A merchant on the Aggregated Balance model cannot use this feature, because the balance model cannot be changed after onboarding. *** ## Before you start Confirm all three before taking the merchant through the steps: * **Dedicated Balance.** In the Merchant Portal, open **Payments Accounts** > **All Balances**. The line under the page title reads **Dedicated balance** for a Dedicated Balance account. * **A supported currency.** Fund splitting can be enabled for AUD, USD, JPY, VND, ARS, IDR, INR, and KES. * **Fund splitting enabled for that currency.** Hello Clever enables it per currency. Without it, every request fails with `Fund splitting is not enabled for this currency`. *** ## Getting a merchant started **1. Step 1: Create a Payments Account to collect payments** The merchant clicks **Create account** in the top-right corner of the [Merchant Portal](/portal/overview) and [adds a Payments Account](/portal/balances#adding-an-account) for collecting customer payments. This is the **Collecting Payments Account**. The merchant creates Payins with this account's `app-id` and `secret-key`. **2. Step 2: Create the Allocation Accounts** The merchant adds one Payments Account for each party that will receive a share, for example one per seller, again with **Create account**. Each must be in the same currency as the Collecting Payments Account. New accounts appear in the **Payments Accounts** table on the **All Balances** screen with the status **Active**. To list the Allocation Accounts, call [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts) with the **Collecting Payments Account's** `app-id` and `secret-key`. The response gives each account's `account_uuid`. The Collecting Payments Account is never listed, because it cannot receive an allocation share. **3. Step 3: Configure an allocation profile** Allocation profiles are created in the Merchant Portal. 1. Select the currency, open **Payments Accounts** > **All Balances**, and click **Manage allocation profiles**. The **Allocation Profiles** list shows each profile and its status. 2. Click **+** next to **Allocation Profiles**. 3. Under **General**, enter a **Profile name**. 4. Under **Allocation Rules**, enter the **Platform fee**: a percentage of the transaction amount, plus an optional fixed amount in the profile currency. Leave the fixed amount at `0.00` for a percentage-only fee. 5. Under **Recipients**, enter an **Allocation share** for each slot (**Recipient 1**, **Recipient 2**, and so on). A profile has up to five slots. The allocation shares must add up to **100%** on their own. The platform fee is taken first and is not part of that total: the shares divide what is left after it. You do not choose accounts here: they are named in the API call in step 4. 6. Review **Live Preview**. Enter a typical **Transaction amount** and select each **Payment method** the merchant accepts: PayID, Visa, Mastercard, American Express (Amex), and Diners, each domestic and international, plus **Other card**. Each method shows its **Processing fee**. The **Collecting Payments Account** panel shows the amount allocated to each recipient, **Platform fee collected**, **Processing fee**, and **Amount (Net)**. Each recipient panel shows its **Transaction amount** and **Amount (Net)**. 7. Click **Save**. The profile appears in the list as **Active**. 8. Select the profile and click the copy icon next to **Profile ID** (`map_...`). The merchant needs this ID in step 4. > [!WARNING] > > If Live Preview shows a warning that the platform fee isn't enough to cover the processing fee, Payins at that amount and method **will be rejected**. The portal still lets you save the profile. Raise the platform fee or add a fixed amount before going live. > [!NOTE] > > A saved profile cannot be edited in this release: the **Edit** button is unavailable. To change an allocation, create a new profile and click **Deactivate** on the old one. A deactivated profile cannot be used on new Payins. **4. Step 4: Use the APIs to process payments and allocate funds** The merchant adds an `allocation_profile` object to each v2 Payin, or to each Payment Gateway 3 payin link, using the Collecting Payments Account's keys: ```json theme={null} "allocation_profile": { "uuid": "map_12OndtdVndcO", "recipients": ["WJWAOSCM", "4A0FWJPW"] } ``` * `uuid`: the Profile ID from step 3. The profile must be **Active** and in the Payin currency. * `recipients`: the `account_uuid` values from step 2, in slot order. The first account receives the Recipient 1 share. Send exactly one Allocation Account per slot, each only once, and never the Collecting Payments Account. The response returns the applied allocation in `allocation_profile`. For a payin link, it appears once the customer has paid. Have the merchant test the full flow in sandbox first. See [Split Payins with platform fees](/developer-reference/api-use-cases/split-payins-with-platform-fees) for complete requests, responses, and sandbox testing. *** ## Checking the result For example, with a profile set to a 5% platform fee, a fixed amount of AUD 2.00, Recipient 1 at 40%, and Recipient 2 at 60% (40 + 60 = 100), an AUD 1,000.00 PayID Payin is allocated like this: | Account | Calculation | Amount (AUD) | | - | - | - | | Collecting Payments Account, platform fee | 1,000.00 × 5% + 2.00 | 52.00, less the PayID processing fee | | Recipient 1 | (1,000.00 − 52.00) × 40% | 379.20 | | Recipient 2 | (1,000.00 − 52.00) × 60% | 568.80 | What the merchant sees: * **Allocation Accounts:** each share appears as its own Payin in that account's history, linked to the original Payin. Allocation Accounts do not receive a separate webhook. * **Collecting Payments Account:** the original Payin, with the platform fee it collected. The webhook goes to this account's endpoint, as for any Payin. * **Card payments:** the allocation appears after the card is charged, once the card brand and processing fee are known. Bank transfer, PayID, QR, and other non-card Payins are allocated when the Payin is created. * **Settlement:** each Payments Account settles its own balance. If the customer pays more or less than the requested amount, the allocation is recalculated on the amount received. *** ## Refunds Refund an allocated Payin from the original Payin in the Collecting Payments Account. The refund is taken from that account's balance, and Allocation Account shares are **not** reversed automatically. Before refunding, check the Collecting Payments Account holds enough funds. Refunds cannot be started from an Allocation Account's share. *** ## Release scope | In this release | Not in this release | | - | - | | Creating allocation profiles in the Merchant Portal | **Editing** an allocation profile. The **Edit** button is unavailable. | | Live Preview of the allocation and processing fees | **Allocation version history** | | Deactivating a profile | | | Listing Allocation Accounts through the API | | | Allocating v2 Payins and Payment Gateway 3 payin links with `allocation_profile` | | *** ## Troubleshooting Payins with an invalid allocation are rejected before any money moves. The full list of error messages is in [Split Payins with platform fees](/developer-reference/api-use-cases/split-payins-with-platform-fees#errors). | Error message | Fix | | - | - | | `Fund splitting is not enabled for this currency...` | Ask Hello Clever to enable fund splitting for the currency. Check the currency is supported. | | `This feature is only available for merchants with dedicated balance mode enabled.` | The merchant is on Aggregated Balance. The feature is unavailable on this account. | | `Allocation profile not found or inactive.` | Check the Profile ID was copied correctly and the profile shows **Active**. | | `Allocation profile currency does not match payin currency.` | Use a profile created under the Payin currency. | | `Allocation profile recipients count does not match.` | Send one Allocation Account per slot in the profile. | | `Each allocation recipient must be a different account.` | Remove the duplicate account. | | `The receiving account cannot be one of the allocation recipients.` | Remove the Collecting Payments Account from `recipients`. | | `One or more recipient accounts are invalid for this merchant/currency.` | Use `account_uuid` values from Get Allocation Recipient Accounts, called with the Collecting Payments Account's keys. | | `Platform fee must be lower than the payin amount...` | Raise the Payin amount, or create a profile with a lower platform fee. | | `Platform fee is lower than the transaction fee for this payin...` | Create a profile with a higher platform fee or a fixed amount, then deactivate the old one. Check Live Preview for the amount and method. | ## Related topics - [Platform Fees and Fund Splitting](/platform-overview/clever-concepts/platform-fees.md) - [Split Payins with Platform Fees](/developer-reference/api-use-cases/split-payins-with-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.