Hello Clever Developer Docs

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.

Prerequisites

A Clever Connect 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. 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.

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

List the accounts you can split to

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

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

No currency is needed: it is taken from the receiving account behind the app-id.

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.

Read the split back

Fetch the Payin or the payin link. The applied split is returned in allocation_profile.

Option A: v2 Payins

Add allocation_profile to POST /api/v2/payins.

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

The response includes the applied split:

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

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.

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

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:

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

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.

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.

Integration Basics

Platform Integrations

API Use Cases

Clever AI Connectors

AI Tools

Security & Compliance

Split Payins with Platform Fees

What you’ll build

Prerequisites

The `allocation_profile` object

Option A: v2 Payins

Option B: Payment Gateway 3 payin links

Response fields

Webhooks

Errors

Testing in sandbox

​What you’ll build

​Prerequisites

​The allocation_profile object

​Option A: v2 Payins

​Option B: Payment Gateway 3 payin links

​Response fields

​Webhooks

​Errors

​Testing in sandbox

What you’ll build

Prerequisites

The `allocation_profile` object

Option A: v2 Payins

Option B: Payment Gateway 3 payin links

Response fields

Webhooks

Errors

Testing in sandbox