PayElect Developer
Docs / Guides / Split Payments

Split Payments

Split payments let a marketplace or platform distribute a single customer payment across multiple recipients (subaccounts) in real time, without a manual payout step. Each split is processed atomically — either all parties receive their share or the payment fails and nobody is charged.

Subaccounts

A subaccount represents a seller, service provider, or sub-merchant on your platform. Create subaccounts via the Subaccounts API before referencing them in a payment.

POST /pay/api/v1/subaccounts 
{
  "name": "Bakary Diallo's Shop",
  "email": "bakary@example.com",
  "country": "GN",
  "currency": "GNF",
  "metadata": { "seller_id": "SLR-001" }
}

Response includes a uid — store this against your seller record in your database.

Including splits in a payment

Pass a splits array when creating the payment. Splits can be PERCENTAGE (of the gross amount after PayElect's platform fee) or FIXED amounts in the payment currency.

Split validation rules
  • PERCENTAGE splits must sum to exactly 100 (after deducting the platform fee share).
  • FIXED splits must not exceed the net amount after platform fee.
  • Up to 20 splits per payment.
  • All subaccount UIDs must belong to your merchant account.

Example: 3-way marketplace split

A customer pays 300,000 GNF. Your platform takes 10%, seller A takes 60%, seller B takes 30%:

curl -X POST https://api.payelecthq.com/pay/api/v1/payment/create \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "300000",
    "currency": "GNF",
    "country": "GN",
    "return_url": "https://marketplace.example.com/orders/99/confirm",
    "cancel_url": "https://marketplace.example.com/orders/99/cancel",
    "idempotency_key": "order-99-v1",
    "splits": [
      {
        "subaccount_uid": "sub_platform_01HXYZ",
        "type": "PERCENTAGE",
        "value": 10
      },
      {
        "subaccount_uid": "sub_seller_a_01HABC",
        "type": "PERCENTAGE",
        "value": 60
      },
      {
        "subaccount_uid": "sub_seller_b_01HDEF",
        "type": "PERCENTAGE",
        "value": 30
      }
    ]
  }'

When the payment succeeds, PayElect:

  1. Deducts its platform fee from the gross amount.
  2. Calculates each split against the resulting net amount.
  3. Credits each subaccount wallet in a single atomic DB transaction.
  4. Fires a split.settled webhook with per-recipient breakdowns.

split.settled webhook payload

{
  "eventId": "evt_01J4SPLITABC123",
  "eventType": "split.settled",
  "apiVersion": "2026-07-12",
  "createdAt": "2026-07-12T10:01:22Z",
  "environment": "production",
  "data": {
    "trxId": "TRX0000099900001",
    "grossAmount": "300000.00000000",
    "currency": "GNF",
    "platformFee": "6000.00000000",
    "netAmount": "294000.00000000",
    "splits": [
      { "subaccountUid": "sub_platform_01HXYZ",  "amount": "29400.00000000",  "type": "PERCENTAGE", "value": 10 },
      { "subaccountUid": "sub_seller_a_01HABC",  "amount": "176400.00000000", "type": "PERCENTAGE", "value": 60 },
      { "subaccountUid": "sub_seller_b_01HDEF",  "amount": "88200.00000000",  "type": "PERCENTAGE", "value": 30 }
    ]
  }
}