Sub-merchant payouts and automatic fund collection: running the money of a network

In a sub-merchant network, sub-merchant payouts and automatic fund collection form a single circuit: a payment credits the designated sub-merchant's wallet, automatic collection feeds your collection account daily or weekly, and every payout requires a distinct requester and approver. Each wallet can be given a balance cap, with an alert as it approaches; bulk refund campaigns handle large-scale cancellations, and a monthly statement is produced for every sub-merchant. This guide walks through each step of the circuit, the decisions that are yours to make, and how to reconcile the whole.

How money moves through a network

ChariPay is a Moroccan payment platform, a PSP operated by Chari Money, a payment institution licensed by Bank Al-Maghrib. Its distribution space is for aggregators, franchises and agent networks. Whatever the network, money follows the same path:

1. 1A sub-merchant's customer pays. The published mechanism for naming the wallet to credit is the config.settlement parameter of a checkout session; for other collection tools, such as links, the question is handled at setup.
2. 2The amount credits the sub-merchant's wallet. Collections follow the allocation defined when the partnership is set up; nothing is pooled into a common pot.
3. 3Automatic collection feeds your collection account, daily or weekly.
4. 4Payouts go out under dual approval: the requester and the approver are always distinct.
5. 5A monthly statement is produced for each sub-merchant, and you reconcile the whole using the references carried by every movement.

Around this circuit sit two management tools: balance caps, set wallet by wallet and flagged by an alert as they are approached, and bulk refund campaigns, for cancellations that affect many customers at once. The full offer is described on the distribution and sub-merchants page; for how a store network in particular is organized, see franchises and store networks.

Before any setup work, you can see what a payment account, its movements and its CSV export look like: Start in test mode. Three fields — name, work email, company — an activation link received by email to choose your password, then the portal, where you create your own test key. There you make payments with the test card and export the movements, with no real money involved. It is free, with no time limit and no approval to wait for: your business verification (KYB) only gates the move to production. The distribution space itself is prepared with the integration team.

Automatic fund collection: daily or weekly

Automatic collection goes to your collection account, on a daily or weekly schedule. We publish no other parameter for it; what matters is that you have no daily task to centralize the network's money.

The frequency is chosen at setup, with the integration team. It depends on two things: how your stores collect over time and your cash needs at the center.

Daily collection keeps wallets light and your central position current; weekly collection leaves funds at sub-merchant level for longer. There is no universal right answer: there is the one that fits your caps and the way you run your cash.

Balance caps and the submerchant.near_cap alert

A balance cap is set wallet by wallet. Between two collections, money builds up in each sub-merchant's wallet: the cap serves as a marker for tracking that build-up, store by store. We publish neither cap amounts, nor the rule that triggers the alert, nor what happens once a cap is reached; the cap is defined at setup.

When a sub-merchant approaches its cap, your system receives the submerchant.near_cap event through a signed webhook. What it makes sense to do with it:

• warn the manager of the store concerned, so they know where they stand;
• look at that sub-merchant's activity: a one-off peak — a promotion, a season — or an underlying trend;
• if the alert keeps coming back, revisit the cap and collection frequency together with the integration team: it is a sign they no longer match actual activity.

To receive this event, your webhook endpoint must be subscribed to it; an explicit list of events is recommended, since an empty list subscribes to every event. Declaring the endpoint, routing on the Chari-Event-Type header and deduplicating on Chari-Event-Id are covered in sub-merchants through the API.

Sub-merchant payouts: one requester, one approver

Every payout requires dual approval: the requester and the approver are always distinct. Whoever requests never approves. This is the same rule as for every sensitive action on the platform — payouts, adjustments, account freezes — and it rests on the rest of the setup: the audit log is cryptographically chained, so history cannot be rewritten; portal access is protected by two-factor authentication (TOTP), re-authentication before every sensitive action and secured sessions.

What is yours to handle is the human organization:

1. 1Name the people who prepare payouts and the people who approve them, in two different functions — network management on one side, finance on the other, for example.
2. 2Plan a backup for each approver, so that one absence does not block the circuit.
3. 3Remove a departing team member's access without delay.

The outcome of each payout reaches you through a signed webhook: payout.completed when it is executed, payout.failed when it fails. Wire the latter to an alert for the finance team, and investigate the failure before requesting anything again. How a payout is calculated is not described here: it follows the allocation defined when the partnership is set up. The access controls themselves — two-factor authentication, approvers, audit log — are covered in securing portal access.

Bulk refund campaigns

The distribution space includes bulk refund campaigns. They are for when one cause affects many customers across the network at once: a product recalled from every store, a canceled event, a pricing error in a promotion. Rather than handling each customer by hand, store by store, the campaign groups them together.

Each refund in the campaign follows the rules of any ChariPay refund: it is free; its amount is deducted from an available balance, and if that balance is not enough, the operation is blocked rather than creating an overdraft; a refund is not instantaneous on the bank side. Three precautions before you launch a campaign:

• draw up the exact list of payments concerned, with their references;
• make sure the balances cover the amounts to refund, to avoid blocked operations;
• let customers know the refund will take as long as their bank takes.

For a single refund — one customer, one order — the procedure is described in refunding a customer.

The monthly statement per sub-merchant

The distribution space provides a monthly statement per sub-merchant, covering only its own activity. This document changes the relationship between the network head and its members.

For the sub-merchant, it is a record about itself alone: once shared with it, it can be passed to its accountant and compared with its own sales, and it gives the store solid ground for its questions. For the network head, it is a shared basis: when a store disputes an amount, the discussion starts from that same document, not from two different spreadsheets.

If a gap appears between a sub-merchant's statement and your own totals, look first for a period issue — a month-end payment timestamped in UTC — or an attachment issue: the references let you settle it.

Reconciling the network's flows

Every account movement carries the reference of the sale, refund or payout that explains it; the portal separates amount paid, fees and net, and the CSV export keeps those references — from the portal or with GET /v1/transactions/export.csv (up to 10,000 rows; beyond that, break it down by period with from/to). Timestamps are in UTC; Morocco is UTC+1: your reconciliation tool must convert.

One design rule makes everything else easy: put the sub-merchant reference in the metadata of every session, so that each payment event says straight away whose sale it is. Watch refunds too: a refund can reduce the next payout without a separate line on the bank statement; the export is what explains it. The full method is in reconciling your collections.

Frequently asked questions

How often does automatic fund collection run?

Daily or weekly: automatic collection goes to your collection account on one of these two schedules, set at setup with the integration team. The choice depends on how your stores collect over time, your balance caps and your cash needs at the center. You have no daily task to perform.

Can a payout go out without approval?

No. Every payout requested by your team requires dual approval: the requester and the approver are always distinct. This rule applies to every sensitive action — payouts, adjustments, account freezes — and the audit log is cryptographically chained: history cannot be rewritten. Plan a backup for each approver, so that one absence does not block the circuit.

What happens when a sub-merchant approaches its cap?

Your system receives the submerchant.near_cap event through a signed webhook. Warn the store manager, check whether it is a one-off peak or a trend, and if the alert keeps coming back, revisit the cap and collection frequency with the integration team. We publish neither cap amounts nor the rule that triggers the alert.

How do I know a payout has failed?

Through the payout.failed event, sent by signed webhook; an executed payout sends payout.completed. Subscribe your endpoint to both events, route on the Chari-Event-Type header and deduplicate on Chari-Event-Id. Wire the failure to an alert for the finance team, and investigate its cause before requesting a new payout. Do not retry automatically: any new request goes through dual approval again.

Can customers be refunded in bulk across a network?

Yes: the distribution space includes bulk refund campaigns, useful for a product recall or a cancellation that affects many customers. Each refund is free; its amount is deducted from an available balance, and the operation is blocked if that balance is not enough. A refund is not instantaneous on the bank side, so let your customers know.

Does each sub-merchant receive a statement?

The distribution space provides a monthly statement per sub-merchant, covering only its own activity: it never shows the others'. Once shared with the store, it can be passed to its accountant and compared with its sales; the network head, for its part, has a shared basis for discussing the month's figures. If there is a gap with your own totals, the movement references let you settle it.

How do I reconcile collections across a whole network?

Through references: every movement carries the reference of the sale, refund or payout that explains it; the portal separates amount paid, fees and net, and the CSV export keeps those references. Put the sub-merchant reference in your metadata, which is echoed verbatim in the payment event, and convert UTC timestamps to Moroccan time.

Next step

First, watch a payment account at work: Start in test mode, make a few payments with the test card and export the movements. Then prepare your network setup — caps, collection frequency, approvers — with the integration team, starting from the distribution and sub-merchants page.