Recipient Tokens

To use the Split Link feature, you need the recipient token of each person who will receive a share of the payment. Recipients must have a registered SecPaid account.

What Is a Recipient Token?

A recipient token is a unique identifier associated with a SecPaid user. It is used in the recipients array when creating a split link and tells SecPaid where to route each share of the payment.

Your own API key is used in the token header for authentication. The recipient's token goes in the request body — the two are separate.

Obtaining Recipient Tokens

Development environment: Recipients can find their token in their SecPaid account settings under the profile or API section. They can set it themselves for testing purposes.

Production environment: Contact compute@spacepitch.org to obtain a recipient token for a specific user after they have registered and verified their SecPaid account.

Usage

Pass recipient tokens in the recipients array of createSplitLink:

curl --location 'https://app.secpaid.com/api/v2/createSplitLink' \
--header 'token: YOUR_OWN_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 100.00,
    "recipient_note": "Service payment",
    "recipients": [
        { "token": "RECIPIENT_TOKEN", "share": 50 },
        { "token": "ANOTHER_RECIPIENT_TOKEN", "share": 50 }
    ]
}'

Schema

{
    "recipients": [
        { "token": "recipient_token", "share": 50 }
    ],
    "amount": 100.00,
    "recipient_note": "Demo payment"
}

Field	Description
token	The recipient's SecPaid recipient token
share	Their share as a percentage (for split_type: "normal") or fixed EUR amount (for split_type: "absolute")

Important Notes

• Your own API key authenticates the request — it goes in the token header.
• Recipient tokens go in the recipients body array — never in the header.
• You can include multiple recipients in a single request.
• Always keep recipient tokens confidential.
• For split_type: "normal", the sum of all share values should equal 100.

See Split Links for full split link documentation and examples.