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 "Authorization: Bearer <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​