Split Links & Recipients

A split link distributes a single payment between you (the link owner) and one or more recipients. When the customer pays, the platform automatically splits the funds — each party receives their share after fees.

How It Works

flowchart LR
    C[Customer] -->|"Pays €100"| S[SecPaid]
    S -->|"€40 (remainder)"| O[You - Link Owner]
    S -->|"€36 (share: 6)"| R1[Recipient A]
    S -->|"€24 (share: 4)"| R2[Recipient B]

1. You create a split link specifying recipients and their shares
2. Customer pays the full amount via the single pay_link
3. SecPaid splits the payment: recipients get their defined shares, you (the owner) get the remainder
4. Only your payment_endpoint is notified (the one set on the link)

Owner always receives the remainder

The link owner (you) automatically receives whatever portion of the payment is not allocated to recipients. You do not add yourself to the recipients array — in fact, using your own token in the recipients list will cause an error.

Recipient Tokens

Each recipient in your SecPaid system has a unique recipient token — a SecPaid account attribute called recipient_token. You reference recipients by this token when creating split links.

Getting Recipient Tokens

Every user has a recipient token visible in their dashboard:

1. Navigate to Settings → API & Integrations
2. The Recipient Token field shows the token (e.g., aeltai-receiver)

When creating split links, you reference other users by their recipient token. Ask your recipients for their token, or look them up via the admin panel.

Token Format

Recipient tokens are alphanumeric strings, e.g.: receivera, usertoken123, merchant_abc

Split Types

SecPaid supports two split calculation modes:

Normal Split (Proportional)

split_type: "normal" (default)

Shares are percentage points. The recipients get their defined percentages, and the owner gets the remainder (100 minus total shares).

Example: Total = €100, two recipients with shares 30 and 30 (total: 60%):

Party	Share	Calculation	Receives
You (owner)	remainder	100 × (100-60)/100	€40.00
Recipient A	30	100 × 30/100	€30.00
Recipient B	30	100 × 30/100	€30.00

{
  "amount": 100,
  "split_type": "normal",
  "recipients": [
    {"token": "recipient_a", "share": 30},
    {"token": "recipient_b", "share": 30}
  ]
}

Total shares must not exceed 100

The sum of all recipient shares must be ≤ 100. If it exceeds 100, the API returns an error.

Absolute Split

split_type: "absolute"

Shares are fixed EUR amounts. Each recipient gets exactly the specified amount, and the owner gets the remainder (total amount minus sum of all shares).

Example: Total = €100, two recipients receive €25 each:

Party	Share (EUR)	Receives
You (owner)	remainder	€50.00
Recipient A	25.00	€25.00
Recipient B	25.00	€25.00

{
  "amount": 100,
  "split_type": "absolute",
  "recipients": [
    {"token": "recipient_a", "share": 25.00},
    {"token": "recipient_b", "share": 25.00}
  ]
}

Absolute split validation

The sum of all share values must not exceed the amount. If it does, the API returns an error.

Giving the Full Amount to Recipients

If you want recipients to get the entire payment (owner keeps nothing):

• Normal: Set shares that add up to exactly 100 (e.g., [{"share": 60}, {"share": 40}])
• Absolute: Set shares that add up to exactly the amount (e.g., [{"share": 60.00}, {"share": 40.00}] for a €100 link)

Service Fees

The platform charges a service fee on each party's share individually. Each party may have a different fee percentage configured on their account. Additionally, a PSP (payment service provider) fee is deducted.

Example: €615,649.94 split payment with split_type: "normal":

Party	Gross Amount	SecPaid Fee	PSP Fee	Net Amount	Payout Status
Owner (you)	€9,234.74	€13,544.40	—	€592,870.80	InProgress
Recipient A	€55.25	€0.83	€1.29	€53.13	Pending
Recipient B	€14.99	€0.16	€0.35	€14.49	Pending

A smaller real-world example — €88.19 basic (non-split) card payment:

	Gross Amount	SecPaid Fee	PSP Fee	Net Amount
You	€88.19	€1.33	€3.15	€84.71

Webhooks for Split Links

Only the link owner's payment_endpoint is called — recipients do not receive individual webhooks. The payment_endpoint is stored on the link itself, so it always belongs to the creator.

Standard webhook (same as regular links):

{
  "ResponseCode": 1,
  "data": {
    "pay_id": 12345,
    "note": "Project payment",
    "amount": 100.00,
    "user_id": "owner-uuid",
    "status": "Success"
  }
}

With encryption enabled, the owner receives a second webhook containing the full split breakdown:

[
  {"user_id": "owner-uuid", "user_token": null, "amount": 40.00, "service_fee": 1.16, "service_fee_psp": 0.29, "net_amount": 38.55, "pay_id": 12345, "payment_method": null},
  {"user_id": "recipient-a-uuid", "user_token": "tok_a", "amount": 30.00, "service_fee": 0.87, "service_fee_psp": 0.22, "net_amount": 28.91, "pay_id": 12345, "payment_method": null},
  {"user_id": "recipient-b-uuid", "user_token": "tok_b", "amount": 30.00, "service_fee": 0.87, "service_fee_psp": 0.22, "net_amount": 28.91, "pay_id": 12345, "payment_method": null}
]

Note

The second webhook with split details is only sent when encryption is enabled on the link (is_encryption: "true"). Both webhooks are sent to the same payment_endpoint URL(s).

Limitations

• Maximum recipients per link: not formally limited, but keep it reasonable
• Each recipient token must exist in the system — invalid tokens cause the entire request to fail
• You cannot use your own token in the recipients list — the owner's share is always the remainder
• Recipient tokens are case-sensitive

Related

• createSplitLink API Reference
• Webhooks & Callbacks