Transaction splits

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:

The checkout’s split, if you named one when creating the checkout (see below).
The product’s split, if the product is in a split’s product_ids.
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

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

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

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, 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

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
});

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.
`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:

import { SPLIT_METADATA_KEY } from "@crossdev/sdk";

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

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.

Get started

Features

Integrate

Merchant of Record (MoR)

Splits are on request

How it works

Which split applies

Access

Add a recipient

Getting paid

Create a split

Use a split for one checkout

Endpoints

​Splits are on request

​How it works

​Which split applies

​Access

​Add a recipient

​Getting paid

​Create a split

​Use a split for one checkout

​Endpoints

​Related

Splits are on request

How it works

Which split applies

Access

Add a recipient

Getting paid

Create a split

Use a split for one checkout

Endpoints

Related