Create Split Sessions via API

FairShare lets you create split sessions programmatically through the API.

This is best for merchants who want to create split sessions from their own backend, checkout, or application flow.

On This Page

• Authentication
• Create a Split Session
• Examples by Split Type
• Response
• Related Endpoints

Integration Options

You have two ways to use this:

Option	Description
Build your own API flow	Call the FairShare API directly from your backend and control the session creation flow yourself
Use the embeddable button	Add the FairShare button to your checkout and let it handle split session creation automatically

If you want full control over the experience, use the API directly. If you want a faster integration, use the embeddable button.

Authentication

To create split sessions through the API, include your merchant API key in the x-api-key header.

x-api-key: YOUR_API_KEY

Use your sandbox API key in sandbox and your live API key in live.

If you have not set up credentials yet, see API Keys.

Create a Split Session

Use this endpoint:

POST https://api.fairsharepay.com/api/v1/split-sessions

Request Fields

The request body contains the split session configuration.

Field	Type	Required	Description
totalAmountQar	number	Yes	Total amount for the split session in QAR
items	array of objects	Required for ITEM_CLAIM	Items available in the split session
currency	string	Yes	Currency code for the session
splitType	string	Yes	Type of split session
expectedContributors	integer	Required for EQUAL_COUNT	Number of contributors expected for equal split sessions. Must be between 2 and 10
meta	string	No	Optional metadata, up to 1024 characters
successRedirectUrl	string	Recommended	Redirect URL after a successful payment flow
cancelRedirectUrl	string	Recommended	Redirect URL if the user cancels
detailTitle	string	No	Title or label shown for the split session
failedRedirectUrl	string	Recommended	Redirect URL if the payment fails
expiryMinutes	integer	Yes	Session expiry time in minutes. Must be between 1 and 60

Split Types

The splitType field supports the following values:

Value	Dashboard Label	Description
ITEM_CLAIM	Pick Items	Contributors select items and pay for what they picked
PROPORTIONAL_POOL	Flexible Amount	Contributors pay any amount toward the total
EQUAL_COUNT	Split Evenly	The total is divided equally across a fixed number of contributors

Items Object

If you use ITEM_CLAIM, include an items array.

Each item supports the following fields:

Field	Type	Required	Description
id	string	Yes	Your item identifier
description	string	Yes	Item name or description
price	number	Yes	Price per unit
quantity	integer	Yes	Quantity available. Must be at least 1
imageUrl	string	No	Optional image URL

Examples by Split Type

Pick Items

Use ITEM_CLAIM when contributors should choose what they are paying for.

{
  "totalAmountQar": 120,
  "currency": "QAR",
  "splitType": "ITEM_CLAIM",
  "detailTitle": "Team dinner",
  "expiryMinutes": 15,
  "successRedirectUrl": "https://example.com/success",
  "cancelRedirectUrl": "https://example.com/cancel",
  "failedRedirectUrl": "https://example.com/failed",
  "items": [
    {
      "id": "pizza-1",
      "description": "Pizza",
      "price": 40,
      "quantity": 2,
      "imageUrl": "https://example.com/pizza.png"
    },
    {
      "id": "drink-1",
      "description": "Soft Drink",
      "price": 20,
      "quantity": 2
    }
  ]
}

Flexible Amount

Use PROPORTIONAL_POOL when contributors can each pay any amount toward the total.

{
  "totalAmountQar": 300,
  "currency": "QAR",
  "splitType": "PROPORTIONAL_POOL",
  "detailTitle": "Office gift",
  "expiryMinutes": 30,
  "successRedirectUrl": "https://example.com/success",
  "cancelRedirectUrl": "https://example.com/cancel",
  "failedRedirectUrl": "https://example.com/failed"
}

Split Evenly

Use EQUAL_COUNT when everyone should pay an equal share.

{
  "totalAmountQar": 200,
  "currency": "QAR",
  "splitType": "EQUAL_COUNT",
  "expectedContributors": 4,
  "detailTitle": "Group order",
  "expiryMinutes": 20,
  "successRedirectUrl": "https://example.com/success",
  "cancelRedirectUrl": "https://example.com/cancel",
  "failedRedirectUrl": "https://example.com/failed"
}

Response

When the split session is created successfully, FairShare returns the session details.

Common response fields include:

Field	Description
id	Split session ID
splitSessionLink	Shareable session link
total	Total session amount
collected	Amount collected so far
status	Current session status
createdAt	Creation timestamp
expiresAt	Expiry timestamp
completedAt	Completion timestamp, if completed
refundedAt	Refund timestamp, if refunded
currency	Session currency
gateway	Connected payment gateway
environment	SANDBOX or LIVE
splitType	Session split type
expectedContributors	Expected contributor count
minContribution	Minimum contribution, if applicable
detailTitle	Session title
leadContributorName	Lead contributor name
leadContributorEmail	Lead contributor email
meta	Metadata
items	Session items

Split Session Statuses

A split session can return the following statuses:

Status	Meaning
PENDING	Session created and awaiting contributions
PARTIAL	Session has received some contributions but is not complete
SUCCEEDED	Payment flow succeeded
EXPIRED	Session expired before completion
COMPLETED	Session was fully completed
REFUNDED	Session was refunded

Related Endpoints

Get a Split Session

GET https://api.fairsharepay.com/api/v1/split-sessions/{id}

Use this to retrieve the current details of a split session.

Recommended Flow

• Create the split session through your backend
• Receive the splitSessionLink in the response
• Redirect the user to that link or send it directly
• Use webhooks or GET /api/v1/split-sessions/{id} to track progress

Important

• Call these APIs from your backend, not from frontend code
• Use the API key that matches your current environment
• Use ITEM_CLAIM for Pick Items
• Use PROPORTIONAL_POOL for Flexible Amount
• Use EQUAL_COUNT for Split Evenly