Platforms & marketplaces
Collect once. Settle to everyone.
Onboard sub-merchants with BVN, NIN and CAC checks, collect on every rail (cards coming), split at settlement, take your fee and pay out on your schedule.
Read the platforms API (opens docs site)Three ways to take a payment for someone else.
Pick the one that matches how your business works. You can use more than one.
Direct
Your seller has their own PediWave key and charges their customers directly. You add an application fee to each payment and it is paid to you at settlement.
Merchant of record: the seller
Destination
You charge with your key, on behalf of the seller, using on_behalf_of. The seller settles the payment and your application fee comes off first.
Merchant of record: the seller
Separate charges and transfers
You collect the payment yourself, then transfer to one or more sellers when you choose: after delivery, at the end of the week, or as each job is done.
Merchant of record: you
Or attach splits to the payment itself, and each share is applied at settlement, whichever model you use.
Hosted onboarding
Sellers verify themselves. You switch them on.
Create a seller with your key and send them a link. They complete a hosted flow on their phone: BVN, a selfie, an ID
document and the bank account they want to be paid into, which is checked by name enquiry. You see each seller's
requirements and deadlines, and you get merchant.capability_updated as transfers and payouts turn on
(card payments are coming). Identity data goes straight to the identity service and is not stored by PediWave.
Verify your buyers too, by BVN or bank account. Coming soon
Read about onboarding (opens docs site)Split profiles
Define the split once. Change it without rewriting history.
A split profile sets each party's share by percentage or fixed amount, who bears the fees, where any remainder goes, and who carries refunds. Apply it by code to payments, payment links, invoices and subscriptions, and override a share on a single payment when you need to. Each change creates a new version, and every payment records the version it used. If a seller is suspended or would go over their verification limit, their share goes to the remainder and the payment is flagged.
Seller payouts
Every seller paid on their own schedule.
Each seller settles to their own verified bank account: next business day by default, or instantly on request. Your application fees are taken before the seller's share settles, so there is nothing to invoice later. Use separate transfers when you want to decide the moment a seller is paid. Every seller's settlements have their own report.
POST /v1/refunds
Authorization: Bearer sk_test_… # your platform key
PediWave-Merchant: mer_01J9ZT5MPK # Mama Put Kitchen
Idempotency-Key: 9c4e1b7a-6f20-4d8e-a3b5-2e7d1f0c9a64
{
"payment_intent": "pi_01J9ZV2R8N",
"amount": 500000,
"reason": "requested_by_customer"
}
# 201 Created
{ "id": "re_01J9ZV6W3H", "object": "refund", "status": "pending" }Act on behalf
One key. Every seller. Only yours.
Send your platform key with the seller's id in a header and the call runs as that seller: refunds, balances, settlements, everything they could do themselves. PediWave checks on every request that the seller is one you created, so no key can reach another platform's sellers. Where you want tighter control, create a restricted key scoped to one seller.
Refunds and disputes
Who pays back is decided before it happens.
When a split payment is refunded, each party's share is pulled back in proportion, or you carry the whole refund as the platform. You choose on the split profile, so there is no argument later. When a buyer disputes a payment, the disputed amount is held as soon as the dispute opens; you submit receipts and delivery proof from the dashboard or the API, and the hold is released if you win.
Escrow for marketplaces
Selling goods that have to arrive? Coming soon
Take the buyer's payment into escrow and release it to the seller when the order is delivered, on any rail. The money is held, not in the seller's balance, until the buyer approves, an independent attestor confirms, or the agreed waiting time passes.
For developers
Three calls to your first paid seller.
- Create the seller with your platform key.
- Send them the hosted onboarding link and wait for
merchant.capability_updated. - Charge on their behalf with your fee and any splits.
Every call that moves money takes an Idempotency-Key, so a retry never charges twice.
POST /v1/merchants
Authorization: Bearer sk_test_… # platform key
Idempotency-Key: 3a7f9d20-1c4b-4e6a-8f2d-5b0e7c9a1d38
{
"type": "sub_merchant",
"name": "Mama Put Kitchen",
"country": "NG",
"representative": { "name": "Chiamaka Eze" }
}
# 201 Created
{ "id": "mer_01J9ZT5MPK", "status": "pending",
"kyb": { "requirements": { "currently_due":
["bvn", "id_document", "settlement_account"] } } }POST /v1/merchants/mer_01J9ZT5MPK/onboarding/link
Authorization: Bearer sk_test_…
{ "return_url": "https://lagosride.example/sellers/done" }
# 200 OK
{ "url": "https://…/pub/onboarding/mer_01J9ZT5MPK?token=…" }
# Later, to your webhook endpoint
# merchant.capability_updated (card payments: coming)
{ "card_payments": "pending", "payouts": "active" }POST /v1/payment/intents
Authorization: Bearer sk_test_…
Idempotency-Key: 8e2b5c71-0d9f-4a36-b1e4-7c3a6f5d2e90
{
"amount": 3000000,
"currency": "NGN",
"on_behalf_of": "mer_01J9ZT5MPK",
"application_fee_amount": 150000,
"splits": [
{ "destination": "mer_01J9ZT8RDR", "amount": 450000 }
],
"reference": "ORD-8812"
}Questions from platforms
Who is the merchant of record?
It depends on the charge model. With direct charges, the seller uses their own key and is the merchant of record. With destination charges, you charge on the seller's behalf and the seller is still the merchant of record. With separate charges and transfers, you collect the payment yourself, so you are the merchant of record and you pay sellers by transfer. Talk to us about which model fits your licences and contracts.
Can sellers be paid instantly?
Yes. Each seller has its own settlement setting: next business day by default, or an instant payout on request. Your application fees are taken before the seller's share settles. Instant payout fees are on the pricing page.
How are sellers verified?
Through a hosted onboarding flow you send them as a link. Sellers provide their BVN, a selfie, an ID document and the bank account to be paid into, which is checked by name enquiry; registered businesses can be asked for their CAC certificate. You see each seller's outstanding requirements and deadlines. The identity data goes straight to the identity service and is not stored by PediWave, and BVN data stays in Nigeria. Each seller's verification tier sets what it can receive and withdraw.
Can a seller have their own account number?
Every seller settles to their own bank account, which they add and verify during onboarding. Dedicated virtual account numbers at a partner bank, where every credit is split automatically, are coming.
Can a buyer's money be held until the order arrives?
Today you can collect with separate charges and transfer to the seller after delivery. Escrow, coming soon, holds the buyer's payment outside the seller's balance and releases it when the order is delivered. See escrow.
Related products
Build the platform your sellers deserve.
Tell us how your sellers get paid today. We will map it to PediWave with you.