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

Create a account with completed KYC
Obtain your Secret API keys — required for all split payment configuration
Set up your primary settlement account before creating sub-accounts

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:

Type	Behaviour	Example
`flat`	A fixed amount per transaction	Vendor always receives ₦2,000 regardless of order total
`percent`	A percentage of the total transaction amount	Logistics partner receives 10% of every order

Full guide → 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.

​Overview

​How It Works

​Prerequisites

​Configure Sub-settlement Accounts

​Create a Checkout with Split Payment

​Verify and Fulfil the Order

​Updating Split Rules

​Listen for Webhooks

​What’s Next?

Overview

How It Works

Prerequisites

Configure Sub-settlement Accounts

Create a Checkout with Split Payment

Verify and Fulfil the Order

Updating Split Rules

Listen for Webhooks

What’s Next?