Multi-party payment flows with automatic fee splitting and settlement scheduling.

Marketplace & Split Payments

Marketplaces involve complex multi-party flows where a single customer payment must be divided between sellers and the platform, often with delayed settlement.

Beetles handles this natively with split transfers — a single API call that creates individually-tracked transfer legs for each destination, giving you full auditability of every cent.

Entity Structure

Account	Purpose
`@world`	External payment processor / bank
`Seller A`	Seller's available balance
`Platform Fees`	Platform commission tracking

Visual Flow

A $200 purchase with 10% commission, settled on D+30:

Each split leg becomes its own tracked transfer with a unique ID. The split either succeeds atomically for all legs or fails for all — no partial payments.

Implementation

Create the Split Transfer

A single POST /transfers with a split array. Every leg inherits the settlement_date and code automatically.

POST /v1/transfers

{
  "ledger_id": "...",
  "debit_account_id": "world_account_id",
  "amount": 20000,
  "code": 100,
  "settlement_date": "2026-03-20T00:00:00Z",
  "split": [
    { "account_id": "seller_a_id", "amount": 18000 },
    { "account_id": "platform_fees_id", "amount": 2000 }
  ],
  "metadata": {
    "order_id": "ord_abc",
    "seller_id": "sel_789"
  }
}

The response returns one transfer ID per leg:

Response (201 Created)

{
  "transfers": [
    { "id": "019a...", "credit_account_id": "seller_a_id", "amount": 18000, "status": "pending" },
    { "id": "019a...", "credit_account_id": "platform_fees_id", "amount": 2000, "status": "pending" }
  ]
}

Automatic Settlement on D+30

When the settlement date arrives, the workflow engine confirms each leg independently:

Each leg moves from pending to success with a full audit trail.

Query Individual Legs

Since each split leg has its own transfer ID, you can query, filter, and report on them individually:

Get all transfers for the platform fees account

curl /v1/transfers?account_id=platform_fees_id

This gives you exact per-order fee tracking without any manual calculation.

Key Benefits

Per-leg tracking: Each destination gets its own transfer — no need to reverse-engineer split values from a single lump sum.
Atomic execution: All legs succeed or all fail. No partial seller payouts.
Scheduled settlement: settlement_date ensures funds only move when your marketplace terms allow.
Full audit trail: Every order has a clear chain of custody from World → Seller + Fees.

Marketplace & Split Payments

On this page