Skip to main content

Split Payments

Split payments let a marketplace platform automatically divide an incoming payment between a seller and the platform itself, in a single atomic operation.

Fee: 2.0% of amount, capped at ₦1,000 (100000 kobo) — PayKore's platform processing fee, separate from your own platform fee.

What are split payments?​

Consider a typical marketplace scenario: a buyer pays ₦10,000 for a product. The seller should receive ₦8,500 after your marketplace's commission. Your platform keeps the remaining ₦1,500.

Without split payments, this requires two separate operations: receive ₦10,000 into your platform wallet, then manually transfer ₦8,500 to the seller. Two operations means two points of failure — if your payout step fails after the buyer has already paid, you have a reconciliation problem.

Split payments perform both movements — buyer to seller, and buyer to platform — within a single atomic transaction. There's no intermediate state where the buyer has paid but the seller hasn't been credited.

The split config object​

A split payment request includes a split_config object describing how to divide the funds:

{
  "split_config": {
    "merchant_account": "wlt_seller_123",
    "platform_fee_percent": 15.0,
    "platform_account": "wlt_your_platform"
  }
}
FieldDescription
merchant_accountThe wallet ID that receives the payment after your platform fee (and PayKore's fee) is deducted. Typically the seller's wallet.
platform_fee_percentYour marketplace's commission, as a percentage from 0 to 50. This is your cut, separate from PayKore's processing fee.
platform_accountYour own wallet ID that receives the platform_fee_percent cut.

Full example​

Walk through a ₦10,000 payment with a 15% platform fee:

ComponentCalculationAmount (kobo)Amount (₦)
Gross payment—1,000,00010,000.00
PayKore processing fee2% of 1,000,000, capped at 10000020,000200.00
Your platform fee15% of 1,000,000150,0001,500.00
PSP fee0.6% of 1,000,0006,00060.00
Merchant receives1,000,000 − 20,000 − 150,000 − 6,000824,0008,240.00

This breakdown is returned in full on the transaction response — you never need to compute it yourself.

Making a split payment request​

curl -X POST https://api.paykore.dev/v1/transfers/split \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE" \
  -H "Idempotency-Key: order_456_split" \
  -H "Content-Type: application/json" \
  -d '{
    "source_wallet_id": "wlt_buYeR789",
    "amount_kobo": 1000000,
    "reference": "order_456",
    "split_config": {
      "merchant_account": "wlt_seller_123",
      "platform_fee_percent": 15.0,
      "platform_account": "wlt_your_platform"
    }
  }'

Response:

{
  "id": "tx_6mNoP7qRsT",
  "type": "split_payment",
  "status": "completed",
  "reference": "order_456",
  "amount_kobo": 1000000,
  "amount_naira": "10000.00",
  "fee_breakdown": {
    "gross_kobo": 1000000,
    "paykore_fee_kobo": 20000,
    "platform_fee_kobo": 150000,
    "psp_fee_kobo": 6000,
    "merchant_net_kobo": 824000,
    "merchant_net_naira": "8240.00"
  },
  "splits": {
    "merchant_account": "wlt_seller_123",
    "platform_account": "wlt_your_platform"
  },
  "created_at": "2025-06-01T13:00:00Z",
  "meta": {
    "request_id": "req_3uVwX4yZaB"
  }
}

Atomicity guarantee​

The buyer debit, merchant credit, and platform fee credit all happen within a single database transaction on PayKore's ledger. If any part of the operation fails — for example, the merchant wallet is unexpectedly closed mid-request — the entire transaction rolls back. The buyer is never debited without the merchant being credited.

note

There is no scenario where a split payment partially succeeds. You will either receive a completed transaction with all three legs settled, or an error response with no ledger changes at all.

Settlement of split payments​

Your platform_account wallet receives its fee cut immediately upon transaction completion — the same as any other wallet credit. The balance accumulates in that wallet over time.

PayKore settles wallet balances to your registered bank account on a T+1 basis by default (the business day following the transaction). Partners on the Scale tier can request on-demand settlement instead of waiting for the daily batch. See Dashboard: Settlements for configuration.

Common errors​

Error codeHTTPCause
INVALID_SPLIT_CONFIG400One or more required fields in split_config are missing or malformed.
PLATFORM_ACCOUNT_NOT_FOUND404The platform_account wallet ID doesn't exist or doesn't belong to your partner account.
SPLIT_EXCEEDS_AMOUNT400platform_fee_percent combined with PayKore and PSP fees would leave the merchant with a negative or zero net amount.
MERCHANT_WALLET_FROZEN422The merchant_account wallet cannot currently receive funds.

Example — SPLIT_EXCEEDS_AMOUNT:

{
  "error": {
    "code": "SPLIT_EXCEEDS_AMOUNT",
    "message": "The configured platform_fee_percent combined with processing fees exceeds the payment amount.",
    "http_status": 400
  },
  "meta": {
    "request_id": "req_7yZaB8cDeF"
  }
}

Next steps​