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

> Keep a platform fee on each Payin and split the rest across merchant Payments Accounts by sending an allocation profile on v2 Payins and Payment Gateway 3 payin links.

## What you'll build

You create a Payin in one Payments Account (the **receiving account**) and attach an `allocation_profile`. When the Payin is paid, Hello Clever keeps your platform fee in the receiving account and moves each merchant's share into its own Payments Account (the **recipient accounts**).

For how the split is calculated and when it is applied, see [Platform Fees](/platform-overview/clever-concepts/platform-fees).

## Prerequisites

* A [Clever Connect](/platform-overview/clever-concepts/clever-connect-vs-standard) account on Dedicated Balance.
* Fund splitting enabled for the Payin currency. Contact your account manager.
* An active allocation profile in that currency, created in the [Merchant Portal](/portal/overview). Note its `uuid` (for example `map_tBdQGAAjkqx9`).
* The `app-id` and `secret-key` of the receiving account.
* Sandbox `https://api.cleverhub.co`; production `https://api-merchant.helloclever.co`.

## The `allocation_profile` object

Send this object on the Payin request:

| Field | Type | Required | Description |
| - | - | - | - |
| `uuid` | string | Yes | UUID of an active allocation profile in the Payin currency. |
| `recipients` | array of strings | Yes | Recipient account UUIDs, one per profile slot, in the profile's order. Each account must be in the Payin currency, appear only once, and must not be the receiving account. Get the UUIDs from [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts). |

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

<Steps>
  <Step title="List the accounts you can split to">
    Call [Get Allocation Recipient Accounts](/api/platform-fee/get-allocation-recipient-accounts) (**GET** `/api/v2/merchant_allocation_profiles/accounts`) with the receiving account's keys. It returns the other Payments Accounts in the same currency. The receiving account is always left out.

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

    No `currency` is needed: it is taken from the receiving account behind the `app-id`.
  </Step>

  <Step title="Create the Payin with an allocation profile">
    Add `allocation_profile` to a v2 Payin or a Payment Gateway 3 payin link. Both are shown below.
  </Step>

  <Step title="Read the split back">
    Fetch the Payin or the payin link. The applied split is returned in `allocation_profile`.
  </Step>
</Steps>

## Option A: v2 Payins

Add `allocation_profile` to **POST** `/api/v2/payins`.

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

The response includes the applied split:

```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 }
    ]
  }
}
```

## Option B: Payment Gateway 3 payin links

Add `allocation_profile` to **POST** `/api/v3/payin_links`. `payin_method_code` is optional: leave it out to let the customer pick a method at checkout.

```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"
}
```

The link is not split yet: nothing has been paid. Once the customer pays, **GET** `/api/v3/payin_links/{uuid}` returns the split in `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 }
      ]
    }
  }
}
```

<Info>
  For card payments, `allocation_profile` appears once the card has been charged. Hello Clever waits for the card brand to apply the right processing fee before splitting.
</Info>

## Response fields

`allocation_profile` is only returned on a Payin that was split.

| Field | Description |
| - | - |
| `uuid` | The allocation profile that was applied. |
| `platform_fee` | Platform fee percentage. |
| `platform_fee_fixed` | Fixed platform fee, in the Payin currency. |
| `platform_fee_amount` | Total platform fee kept by the receiving account: `amount × platform_fee% + platform_fee_fixed`. |
| `recipients[].account_uuid` | Recipient account UUID. |
| `recipients[].amount` | Amount moved to that account. |

The split is saved when it is applied. Later edits to the allocation profile do not change Payins that were already split.

## Webhooks

The webhook for the Payin is sent to the receiving account's `endpoint_url`, as for any other Payin. Recipient accounts do not receive a separate webhook for their share.

## Errors

The request is rejected with one of these messages in `errors.message`:

| Message | What to check |
| - | - |
| `Fund splitting is not enabled for this currency. Please contact your administrator for assistance.` | Fund splitting must be enabled for the Payin currency. |
| `This feature is only available for merchants with dedicated balance mode enabled.` | The merchant must be on Dedicated Balance. |
| `Allocation profile not found or inactive.` | Check the profile `uuid` and that the profile is active. |
| `Allocation profile currency does not match payin currency.` | Use a profile in the Payin currency. |
| `Allocation profile recipients count does not match.` | Send one recipient per profile slot. |
| `Each allocation recipient must be a different account.` | Remove duplicate account UUIDs. |
| `The receiving account cannot be one of the allocation recipients.` | Remove the receiving account from `recipients`. |
| `One or more recipient accounts are invalid for this merchant/currency.` | Use account UUIDs from the accounts endpoint, in the Payin currency. |
| `Platform fee must be lower than the payin amount - can't apply this allocation profile.` | Increase the amount, or lower the platform fee. |
| `Platform fee is lower than the transaction fee for this payin - can't apply this allocation profile.` | The platform fee must cover the processing fee for the chosen method. |

## Testing in sandbox

* For non-card methods, use **POST** `/api/v3/payins/simulate` with `{"uuid": "<payin link uuid>", "action": "completed"}` to mark a payin link as paid. Pass a different `amount` to test under or over payment: the split is recalculated on the amount received.
* For cards, open `payment_url` and pay with a test card.


## Related topics

- [Platform Fees and Fund Splitting](/platform-overview/clever-concepts/platform-fees.md)
- [October 2026](/release-notes/2026-10.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.