> ## Documentation Index
> Fetch the complete documentation index at: https://developer.novacpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplaces

> Learn how to collect payments from buyers and automatically distribute funds to multiple vendor accounts using Novac's Split Payment feature.

# 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

```mermaid theme={null}
sequenceDiagram
  participant B as Buyer
  participant S as Marketplace Server
  participant N as Novac

  B->>S: Places order (multiple vendors)
  S->>N: POST /checkout (with split config)
  N-->>S: Returns checkoutUrl + transactionRef
  S-->>B: Redirects buyer to checkout
  B->>N: Completes payment
  N-->>S: Webhook: notifyType = "successful"
  N->>N: Automatically splits and settles funds
  Note over N: Vendor A gets flat ₦2,000<br/>Vendor B gets 30%<br/>Platform keeps remainder
```

***

### Prerequisites

<Accordion title="See details" defaultOpen={true}>
  * [Create a account](/docs/getting-started/create-merchant-account) with completed KYC
  * [Obtain your Secret API keys](/docs/getting-started/obtain-api-keys) — required for all split payment configuration
  * [Set up your primary settlement account](/docs/accept-payment/split-payment/setup-primary-settlement-account) before creating sub-accounts
</Accordion>

***

### 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.

```bash Request theme={null}
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
    }
  ]'
```

```json Response theme={null}
{
  "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
    }
  ]
}
```

<Warning>
  Store each `split_payment_reference` securely. You will need it to update split rules in the future.
</Warning>

<Note>
  Use the [Retrieve Payout Banks](/api-reference/payouts/retrieve-payout-banks) endpoint to get valid `bank_code` values before creating sub-settlement accounts.
</Note>

**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](/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.

```bash Request theme={null}
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](/docs/accept-payment/checkout/create-checkout-with-transaction-reference#create-checkout-payment-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.

```bash Request theme={null}
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](/docs/accept-payment/manage-payment/verify-transaction)

***

### Updating Split Rules

Vendor commissions, platform fees, or bank account details can change. Update any existing sub-settlement account without disrupting live payments.

```bash Request theme={null}
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.

```json Webhook Payload (example) theme={null}
{
  "notify": "transaction",
  "notifyType": "successful",
  "data": {
    "transactionReference": "MKT-ORDER-00456",
    "amount": 20000,
    "chargedAmount": 20000,
    "currency": "NGN",
    "status": "successful"
  }
}
```

[Full guide → Webhooks](/docs/api-basics/webhooks)

***

## What's Next?

* **Setup Primary Settlement Account** - [Configure](/docs/accept-payment/split-payment/setup-primary-settlement-account) where your platform's share of payments gets settled.
* **Manage Sub-settlement Accounts** - [Create, retrieve](/docs/accept-payment/split-payment/manage-sub-settlement-accounts), and update vendor payout configurations.
* **Refund a Transaction** - Handle buyer [refund requests](/docs/accept-payment/manage-payment/refund-transaction), including split transactions.