createSplitLink

Create a payment link that distributes the payment across multiple recipients.

Request

POST /api/v2/createSplitLink

Headers

Header	Required	Description
token	Yes	Your API Key
Content-Type	Yes	application/json

Body Parameters

Field	Type	Required	Description
amount	number	Yes	Total payment amount in EUR (must be > 0)
recipients	array	Yes	Array of recipient objects (see below)
split_type	string	No	"normal" (proportional, default) or "absolute" (fixed amounts)
recipient_note	string	No	Note for identifying the payment
callback_url	string	No	URL or index for browser redirect after payment
payment_endpoint	string	No	Webhook URL(s) for this link. Accepts a URL, index, or comma-separated mix. See Webhooks
cancellable	boolean	No	Whether customer can cancel. Default: true
is_qr_link	boolean	No	Generate a QR code image URL

Recipients Array

Each object in the recipients array:

Field	Type	Required	Description
token	string	Yes	Recipient's recipient_token (SecPaid account attribute)
share	number	Yes	Share value — meaning depends on split_type

split_type = "normal" (default): share is a percentage (0–100). Recipients get their percentage, the link owner gets the remainder. E.g., shares [30, 30] on a €100 payment → recipients get €30 + €30, owner gets €40.

split_type = "absolute": share is a fixed EUR amount each recipient receives. The owner gets the remainder (amount minus sum of shares). Sum of shares must not exceed amount.

Response

Success (ResponseCode: 1)

{
  "data": {
    "is_cancellation": "No",
    "user_id": "b44c4429-4a7b-4e27-85af-c1c2f43f4ffe",
    "amount": 35.39,
    "recipient_note": "Test-Ala",
    "status": "Unused",
    "paymentEndpoint": "https://google.com",
    "callback_url": "https://google.com",
    "servicefee": "1.0",
    "recipients": "[{\"token\":\"testuser-a\",\"share\":10}]",
    "is_split_link": "true",
    "split_type": "normal",
    "bank_transfer": "true",
    "is_qr_link": "false",
    "payment_config": "",
    "bank_statement_description": "",
    "created_at": "2026-05-20 11:19:42",
    "id": 99289,
    "pay_link": "https://app.secpaid.com/payment?link_id=OTkyODk=",
    "qr_img": "https://quickchart.io/chart?chl=https://app.secpaid.com/payment?link_id=OTkyODk=&chs=300x300&cht=qr",
    "transaction_type": "Split"
  },
  "ResponseCode": 1,
  "ResponseMsg": "Link has been created successfully",
  "Result": "True",
  "ServerTime": "CEST"
}

Response Fields

Field	Type	Description
id	integer	Internal link ID
pay_link	string	Payment URL to send to customer
qr_img	string	QR code image URL encoding the pay_link
amount	number	Total payment amount in EUR
recipients	string	JSON-encoded recipients array as stored
is_split_link	string	Always "true" for split links
split_type	string	"normal" or "absolute"
transaction_type	string	"Split" for split links
status	string	Always "Unused" on creation

Error (ResponseCode: 0)

{
  "ResponseCode": 0,
  "ResponseMsg": "Invalid recipient token at index 0",
  "Result": "False",
  "ServerTime": "CEST"
}

Common errors:

ResponseMsg	Cause
Please enter token	Missing token header
No user found with the provided API key.	Invalid API key
Please enter amount	Missing amount field
Invalid recipient token at index N	Token at position N doesn't exist in the system
You cannot use your own token in recipient list at index N	Own API key used as recipient
Share should be less than 100	Normal split: total shares exceed 100
Share should be less than or equal to {amount}	Absolute split: total shares exceed the amount
Share should be greater than zero at index N	A share value is ≤ 0

Examples

cURL (proportional)cURL (absolute)JavaScriptPHP

curl -X POST https://app.secpaid.com/api/v2/createSplitLink \
  -H "Content-Type: application/json" \
  -H "token: YOUR_API_KEY" \
  -d '{
    "amount": 100,
    "split_type": "normal",
    "recipients": [
      {"token": "recipient_a", "share": 6},
      {"token": "recipient_b", "share": 4}
    ],
    "recipient_note": "Project payment",
    "callback_url": "https://yoursite.com/payment/done"
  }'

curl -X POST https://app.secpaid.com/api/v2/createSplitLink \
  -H "Content-Type: application/json" \
  -H "token: YOUR_API_KEY" \
  -d '{
    "amount": 100,
    "split_type": "absolute",
    "recipients": [
      {"token": "recipient_a", "share": 60.00},
      {"token": "recipient_b", "share": 40.00}
    ],
    "recipient_note": "Project payment"
  }'

const response = await fetch("https://app.secpaid.com/api/v2/createSplitLink", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "token": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    amount: 100,
    split_type: "absolute",
    recipients: [
      { token: "recipient_a", share: 60.00 },
      { token: "recipient_b", share: 40.00 }
    ],
    recipient_note: "Project payment",
    callback_url: "https://yoursite.com/payment/done"
  })
});

$response = Http::withHeaders([
    'token' => 'YOUR_API_KEY',
])->post('https://app.secpaid.com/api/v2/createSplitLink', [
    'amount' => 100,
    'split_type' => 'absolute',
    'recipients' => [
        ['token' => 'recipient_a', 'share' => 60.00],
        ['token' => 'recipient_b', 'share' => 40.00],
    ],
    'recipient_note' => 'Project payment',
]);

Notes

• Each recipient must have a valid recipient_token in the SecPaid system
• You cannot use your own token in the recipients list — the owner's share is always the remainder
• With split_type: "absolute", the sum of all shares must not exceed the amount
• With split_type: "normal", the sum of all shares must not exceed 100
• Only the link owner's payment_endpoint receives the webhook — recipients do not get individual notifications
• With encryption enabled, a second webhook is sent to the owner containing the full split breakdown
• See Split Links concept for detailed split math and fee distribution