> ## Documentation Index
> Fetch the complete documentation index at: https://staging-docs.crosspoint.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction splits

> Share each sale with a partner, co-founder or vendor: a percentage or a flat amount, paid to their own bank account or mobile money wallet.

A split shares your sales with other people. Each person (a **recipient**) takes a **percentage** or a **flat amount** of every sale it applies to, and you keep the rest.

## Splits are on request

Our team turns splits on for each store. Go to **Finance > Splits** and click **Request access**. You can tell us who you'll split sales with. We email the organization owner as soon as we've looked at it. If we can't turn splits on, the email says why, and you can ask again.

Until splits are on, adding a recipient or a split, in the dashboard or through the API, fails with a `403` error.

## How it works

* **Recipients are bank accounts or mobile money wallets.** They're paid in their local currency, and they don't need a Crosspoint account. Before their first payout, our team checks the account. Their shares are set aside from the first sale, so nothing is lost while we check.
* **You choose who pays the fees**, per split:
  * `seller` (the default): recipients get their full share of the sale and you pay the fees.
  * `shared`: fees come off the sale first, then it's divided.
* **Shares are worked out on the sale before tax.** A percentage of a $100 sale is a percentage of $100.
* **Recipients never get more than you earned.** If the shares add up to more than the sale minus fees, each is reduced in proportion.
* **Refunds and chargebacks are shared too.** Refund half a sale and each recipient gives back half of their share from that sale.

## Which split applies

Most specific first:

1. **The checkout's split**, if you named one when creating the checkout (see [below](#use-a-split-for-one-checkout)).
2. **The product's split**, if the product is in a split's `product_ids`.
3. **Your default split**, the one with `is_default: true`.

If none applies, the sale isn't split. Subscription renewals use the product's split or your default.

## Access

You need an organization access token (**Settings > Developers**) with the **payouts** scopes: `payouts:read` to read splits and recipients, `payouts:write` to change them. Only owners and admins can manage splits from a personal account.

## Add a recipient

```ts TypeScript theme={null}
import { createCrosspoint } from "@crossdev/sdk";

const crosspoint = createCrosspoint();

const partner = await crosspoint.splitRecipients.create({
  method: "bank_account",
  name: "Co-founder",
  email: "ada@example.com",
  country: "NG",
  account_name: "Ada Obi",
  bank_name: "GTBank",
  account_number: "0123456789",
});
// partner.status === "pending" until we've checked the account
```

```python Python theme={null}
from crosspoint import Crosspoint

crosspoint = Crosspoint()

partner = crosspoint.split_recipients.create(
    method="bank_account",
    name="Co-founder",
    email="ada@example.com",
    country="NG",
    account_name="Ada Obi",
    bank_name="GTBank",
    account_number="0123456789",
)
# partner.status == "pending" until we've checked the account
```

```bash cURL theme={null}
curl -X POST https://api.crosspoint.finance/v1/split-recipients/ \
  -H "Authorization: Bearer $CROSSPOINT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "bank_account",
    "name": "Co-founder",
    "country": "NG",
    "account_name": "Ada Obi",
    "bank_name": "GTBank",
    "account_number": "0123456789"
  }'
```

For mobile money, use `"method": "mobile_money"` with `provider` (for example `M-Pesa`) and `phone_number` in international format (`+254712345678`) instead of the bank fields. The account must be in an African country.

| Status | What it means |
| - | - |
| `pending` | We're checking the account. Their shares are set aside. (In the [sandbox](https://staging-docs.crosspoint.finance/africa/sandbox.md), recipients are approved straight away.) |
| `approved` | Checked. We pay them what they're owed. |
| `rejected` | The details didn't check out (see `rejection_reason`). They stop taking shares, and what was set aside for them goes back to your balance. Add the recipient again with the right details. |

### Getting paid

We check each account (for Nigerian banks, we ask the bank whose account it is) and then pay approved recipients what they're owed, to the account you added. Payouts to recipients come out of the shares set aside for them, not out of your balance.

If a sale is refunded after a recipient was paid for it, their `owed` goes negative; their next shares make up for it before they're paid again.

You can change a recipient's `name` and `email`. To change account details, add a new recipient and remove the old one: new details are checked again. Removing a recipient stops new shares; what they're already owed is still theirs.

## Create a split

```ts TypeScript theme={null}
const split = await crosspoint.splits.create({
  name: "Partners",
  fee_bearer: "seller",
  is_default: true,
  shares: [
    { recipient_id: partner.id, type: "percent", percent: 20 },
    { recipient_id: designer.id, type: "flat", amount: 500 }, // $5.00 per sale
  ],
  product_ids: [], // or the products that always use this split
});
```

```python Python theme={null}
split = crosspoint.splits.create(
    name="Partners",
    fee_bearer="seller",
    is_default=True,
    shares=[
        {"recipient_id": partner.id, "type": "percent", "percent": 20},
        {"recipient_id": designer.id, "type": "flat", "amount": 500},
    ],
)
```

| Field | |
| - | - |
| `shares` | One per recipient. `percent` (up to 2 decimals; all percentages together at most 100) or `flat` with `amount` in USD cents. |
| `fee_bearer` | `seller` or `shared`, see [How it works](#how-it-works). |
| `is_default` | Use for every sale without a checkout or product split. Setting it takes it off your previous default. |
| `product_ids` | Every sale of these products uses this split. A product has one split: adding it here takes it off any other. |

Changes apply to sales from then on: earlier sales keep the shares they had. Deleting a split sends its products back to your default split.

## Use a split for one checkout

Put the split's ID in the checkout's metadata under `crosspoint_split`:

```ts TypeScript theme={null}
import { SPLIT_METADATA_KEY } from "@crossdev/sdk";

const checkout = await crosspoint.checkouts.create({
  products: ["<product_id>"],
  metadata: { [SPLIT_METADATA_KEY]: split.id },
});
```

```python Python theme={null}
from crosspoint import SPLIT_METADATA_KEY

checkout = crosspoint.checkouts.create(
    products=["<product_id>"],
    metadata={SPLIT_METADATA_KEY: split.id},
)
```

This is how marketplaces send each sale to the right vendor. An unknown split ID is rejected with a `422`. The same metadata works on a **checkout link**, so every checkout opened from that link uses the split. Customers can't choose a split: the key is only read from metadata you set (a link's URL parameters are ignored).

## Endpoints

| | |
| - | - |
| `GET /v1/split-recipients/` | List recipients. Filters: `organization_id`, `status`, `page`, `limit`. |
| `POST /v1/split-recipients/` | Add a recipient. |
| `GET /v1/split-recipients/{id}` | Get a recipient, with `owed`: what they're owed and not yet paid, in USD cents. |
| `PATCH /v1/split-recipients/{id}` | Change `name` or `email`. |
| `DELETE /v1/split-recipients/{id}` | Remove a recipient. |
| `GET /v1/splits/` | List splits. Filters: `organization_id`, `page`, `limit`. |
| `POST /v1/splits/` | Create a split. |
| `GET /v1/splits/{id}` | Get a split. |
| `PATCH /v1/splits/{id}` | Change any field; `shares` and `product_ids` replace the old ones. |
| `DELETE /v1/splits/{id}` | Delete a split. |

With a personal access token, pass `organization_id` when creating. An organization token already names the store.

## Related

* [Payout accounts](https://staging-docs.crosspoint.finance/africa/payout-accounts.md)
* [Payouts](https://staging-docs.crosspoint.finance/africa/payouts.md)
* [Checkout sessions](https://staging-docs.crosspoint.finance/features/checkout/session.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.