Skip to main content

​
Overview

Marketplaces deal with a payment challenge that a standard e-commerce checkout doesn’t, funds collected from a single buyer often need to be distributed to multiple parties i.e, the vendor, the platform, a logistics partner, or all three. Novac’s Split Payment feature handles this automatically. You define the split rules once (flat or percentage-based), and every incoming payment is settled to each configured account without manual transfers.

​
How It Works

​
Prerequisites

See details

​
Configure Sub-settlement Accounts

Before a split can happen, define the accounts that should receive a portion of each payment. You can use flat (fixed amount) or percent (percentage of total) split types.
Request
curl -X POST \
  'https://api.novacpayment.com/api/v1/split-payment' \
  -H 'Authorization: Bearer <your-secret-key>' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "split_name": "vendor_a",
      "bank_code": "000013",
      "account_number": "0004498921",
      "split_type": "flat",
      "split_value": 2000
    },
    {
      "split_name": "logistics_fee",
      "bank_code": "000013",
      "account_number": "0004498938",
      "split_type": "percent",
      "split_value": 10
    }
  ]'
Response
{
  "status": true,
  "message": "Split Settings saved successfully",
  "data": [
    {
      "split_name": "vendor_a",
      "split_payment_reference": "31VENDOR_ASPLIT0000130004498921",
      "split_type": "flat",
      "split_value": 2000
    },
    {
      "split_name": "logistics_fee",
      "split_payment_reference": "31LOGISTICS_FEESPLIT0000130004498938",
      "split_type": "percent",
      "split_value": 10
    }
  ]
}
Store each split_payment_reference securely. You will need it to update split rules in the future.
Use the Retrieve Payout Banks endpoint to get valid bank_code values before creating sub-settlement accounts.
Split type comparison:
TypeBehaviourExample
flatA fixed amount per transactionVendor always receives ₦2,000 regardless of order total
percentA percentage of the total transaction amountLogistics partner receives 10% of every order
[Full guide → Manage Sub-settlement Accounts](/docs/accept-payment/ split-payment/manage-sub-settlement-accounts)

​
Create a Checkout with Split Payment

When initiating a checkout, attach the split configuration so Novac knows how to distribute funds upon settlement.
Request
curl --request POST \
  --url https://api.novacpayment.com/api/v1/checkout \
  --header 'Authorization: Bearer <your-public-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 20000,
    "currency": "NGN",
    "email": "buyer@example.com",
    "reference": "MKT-ORDER-00456",
    "callbackUrl": "https://yourmarketplace.com/payment/callback",
    "splitPayment": true
  }'
Full guide → Create Checkout with Split Payment

​
Verify and Fulfil the Order

After the buyer completes payment, Novac redirects them to your callbackURL. Verify the transaction server-side before marking the order as paid.
Request
curl --request GET \
  --url https://api.novacpayment.com/api/v1/checkout/MKT-ORDER-00456/verify \
  --header 'Authorization: Bearer <your-secret-key>'
Only release goods or notify vendors when data.status is "successful". Full guide → Verify a Transaction

​
Updating Split Rules

Vendor commissions, platform fees, or bank account details can change. Update any existing sub-settlement account without disrupting live payments.
Request
curl -X PUT \
  'https://api.novacpayment.com/api/v1/split-payment' \
  -H 'Authorization: Bearer <your-secret-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "split_reference_code": "31VENDOR_ASPLIT0000130004498921",
    "bank_code": "000013",
    "account_number": "0004498921",
    "split_type": "flat",
    "split_value": 2500
  }'

​
Listen for Webhooks

Configure a webhook endpoint to receive settlement and payment events in real time — especially important when orders have multiple fulfilment stages across vendors.
Webhook Payload (example)
{
  "notify": "transaction",
  "notifyType": "successful",
  "data": {
    "transactionReference": "MKT-ORDER-00456",
    "amount": 20000,
    "chargedAmount": 20000,
    "currency": "NGN",
    "status": "successful"
  }
}
Full guide → Webhooks

​
What’s Next?

  • Setup Primary Settlement Account - Configure where your platform’s share of payments gets settled.
  • Manage Sub-settlement Accounts - Create, retrieve, and update vendor payout configurations.
  • Refund a Transaction - Handle buyer refund requests, including split transactions.