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
• Check Split Session Availability
• Create a Split Session
• Examples by Split Type
• Response
• Error Handling
• 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-SplitPay-API-Key header.

X-SplitPay-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.

Idempotency

To safely retry create-session requests, send an Idempotency-Key header.

Idempotency-Key: 6f82d2e3-5252-4f3c-b45d-c238c5f9c7ce

• This header is optional but strongly recommended.
• Maximum length is 120 characters.
• Reusing the same key with the exact same payload returns the original split session.
• Reusing the same key with a different payload returns a conflict error.

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
totalAmount	number	Yes	Total amount for the split session
items	array of objects	Required for ITEM_CLAIM	Items available in the split session
currency	string	Yes	ISO currency code for the session
splitType	string	Yes	Type of split session
expectedContributors	integer	No (required before contributions for EQUAL_COUNT)	Number of contributors for equal split sessions. Must be between 2 and 10
convenienceFeeType	string	No	Convenience fee mode. Values: NONE, FIXED_PER_CONTRIBUTION (defaults to NONE)
convenienceFeeValue	number	No	Convenience fee value (defaults to 0.00)
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
failedRedirectUrl	string	Recommended	Redirect URL if the payment fails
detailTitle	string	No	Title or label shown for the split session
expiryMinutes	integer	No	Session expiry time in minutes. Must be between 1 and 60 (defaults to 15)

Check Split Session Availability

Before showing a FairShare split-payments option on your own website or checkout, call this endpoint to confirm that the merchant can currently create split sessions in that environment.

This check is recommended before you display or enable a split payment option in your product.

Use this endpoint:

GET https://api.fairsharepay.com/api/v1/split-sessions/availability

Authentication:

X-SplitPay-API-Key: YOUR_API_KEY

The environment is inferred from the API key you send:

• Sandbox key (sdbx_...) checks sandbox availability
• Live key (live_...) checks live availability

This endpoint is designed to be safe to call before split-session creation. It tells you whether the merchant is currently eligible to create split sessions and, if not, returns blockers explaining what still needs attention.

What It Returns

Field	Type	Description
environment	string	Environment derived from the API key
canCreateSplitSession	boolean	Whether split session creation should work right now
blockers	array of strings	Machine-readable blockers explaining why it is unavailable
merchantStatus	string	Current merchant status
hasPaymentMethodOnFile	boolean	Whether the merchant has a payment method on file
gateway	string or null	Connected PSP for that environment, if present
connectionStatus	string or null	PSP connection status for that environment, if present

Common Blockers

Blocker	Meaning
MERCHANT_PROFILE_INCOMPLETE	Merchant profile is not active yet
LIVE_PAYMENT_METHOD_REQUIRED	Live mode is blocked until a payment method is on file
PSP_CONNECTION_MISSING	No PSP connection exists for the environment
PSP_CONNECTION_NOT_ACTIVE	A PSP connection exists but is not active

Example Success Response

{
  "environment": "LIVE",
  "canCreateSplitSession": true,
  "blockers": [],
  "merchantStatus": "ACTIVE",
  "hasPaymentMethodOnFile": true,
  "gateway": "STRIPE",
  "connectionStatus": "ACTIVE"
}

Example Unavailable Response

{
  "environment": "LIVE",
  "canCreateSplitSession": false,
  "blockers": [
    "LIVE_PAYMENT_METHOD_REQUIRED",
    "PSP_CONNECTION_MISSING"
  ],
  "merchantStatus": "ACTIVE",
  "hasPaymentMethodOnFile": false,
  "gateway": null,
  "connectionStatus": null
}

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.

{
  "totalAmount": 120,
  "currency": "QAR",
  "splitType": "ITEM_CLAIM",
  "convenienceFeeType": "NONE",
  "convenienceFeeValue": 0,
  "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.

{
  "totalAmount": 300,
  "currency": "QAR",
  "splitType": "PROPORTIONAL_POOL",
  "convenienceFeeType": "FIXED_PER_CONTRIBUTION",
  "convenienceFeeValue": 2.5,
  "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.

{
  "totalAmount": 200,
  "currency": "QAR",
  "splitType": "EQUAL_COUNT",
  "expectedContributors": 4,
  "convenienceFeeType": "NONE",
  "convenienceFeeValue": 0,
  "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
created	Creation timestamp
expiresAt	Expiry timestamp
completedAt	Completion timestamp, if completed
refundedAt	Refund timestamp, if refunded
currency	Session currency
gateway	Connected payment gateway
splitType	Session split type
expectedContributors	Expected contributor count
minContribution	Minimum contribution (for proportional pool)
convenienceFeeType	Session convenience fee mode
convenienceFeeValue	Session convenience fee value
detailTitle	Session title
leadContributorName	Lead contributor name
leadContributorEmail	Lead contributor email
meta	Metadata
items	Session items

Example Success Response

{
  "id": "9f6e96d3-7b18-4f0e-96b8-e2eb9f6a2a1c",
  "splitSessionLink": "https://app.fairsharepay.com/contributor/9f6e96d3-7b18-4f0e-96b8-e2eb9f6a2a1c",
  "total": 200.00,
  "collected": 0.00,
  "authorizedAmount": 0.00,
  "status": "PENDING",
  "created": "2026-04-08T10:15:30Z",
  "expiresAt": "2026-04-08T10:35:30Z",
  "completedAt": null,
  "refundedAt": null,
  "currency": "QAR",
  "gateway": "STRIPE",
  "splitType": "EQUAL_COUNT",
  "expectedContributors": 4,
  "minContribution": null,
  "convenienceFeeType": "FIXED_PER_CONTRIBUTION",
  "convenienceFeeValue": 2.50,
  "detailTitle": "Group order",
  "leadContributorName": null,
  "leadContributorEmail": null,
  "meta": "order-123",
  "successRedirectUrl": "https://example.com/success",
  "cancelRedirectUrl": "https://example.com/cancel",
  "failedRedirectUrl": "https://example.com/failed",
  "items": [],
  "contributions": []
}

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

Error Handling

The API returns structured ApiError responses with a stable code and message.

Common create-session errors:

HTTP Status	Error Code	What it means
400	VALIDATION_ERROR	One or more request fields are invalid or missing.
400	IDEMPOTENCY_KEY_INVALID	Idempotency-Key is invalid (for example, too long).
400	EXPECTED_CONTRIBUTORS_INVALID	expectedContributors is invalid for equal split rules.
400	CONVENIENCE_FEE_INVALID	Convenience fee configuration or value is invalid.
401	UNAUTHORIZED	Request is not authenticated (missing/invalid API key).
403	FORBIDDEN	Merchant is authenticated but not allowed to perform this action.
403	LIVE_ACCESS_DISABLED	Live mode is blocked until a payment method is on file.
409	IDEMPOTENCY_KEY_REUSED	The same idempotency key was already used with a different request payload.
409	PSP_CONNECTION_MISSING	No active payment gateway connection exists for the merchant environment.
409	BUSINESS_RULE_VIOLATION	Request violates a business rule for the current state.
500	INTERNAL_ERROR	Unexpected server error. Retry later or contact support if persistent.

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.

Check Split Session Availability

GET https://api.fairsharepay.com/api/v1/split-sessions/availability

Use this before rendering a split-payments button on your website or checkout.

Set Expected Contributors (Equal Split)

POST https://api.fairsharepay.com/api/v1/split-sessions/{id}/expected-contributors

Use this to set expectedContributors for EQUAL_COUNT sessions before contributions begin.

Recommended Flow

• Call GET /api/v1/split-sessions/availability before rendering the FairShare split-payments entry point to make sure your merchant account can currently create split sessions.
• Create the split session through your backend after availability is confirmed.
• 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.
• Call the availability endpoint before showing a split payment option in your UI.
• Use ITEM_CLAIM for Pick Items.
• Use PROPORTIONAL_POOL for Flexible Amount.
• Use EQUAL_COUNT for Split Evenly.