Settlements and fees#
Every payment you collect is split at source: the Yusr fee is deducted and the net amount is settled to your verified bank account on your settlement schedule. You never send an invoice for fees, and you never reconcile fees by hand.
How money flows#
Your customer pays#
The payer transfers to the transaction's one-time account number. Yusr records the payment, works out the fee and credits the net amount to your pending balance.
The payment is batched#
On your settlement schedule, every eligible payment received in the settlement period is grouped into one settlement batch. The batch's net amount moves from pending to available.
The batch is paid out#
The batch is paid to your settlement bank account. When it completes, the amount moves to settled and you
receive a settlement.completed webhook.
| Balance | Meaning |
|---|---|
pending | Collected, net of fees, not yet in a settlement batch. |
available | In a settlement batch that is being paid out. |
settled | Total paid out to your bank account to date. |
All three values are integers in kobo, per mode: test-mode payments only ever reach your test balance.
Settlement schedule#
Your schedule is agreed during onboarding and shown in the dashboard under Settings → Settlement account. Settlement periods follow West Africa Time (WAT).
| Schedule | Settlement period | Paid |
|---|---|---|
| T+1 | Payments received during the previous calendar day (00:00 to 24:00 WAT) | In the first settlement run after midnight WAT |
| T+0 | Payments received on the same day before 15:00 WAT | Same day, in the first settlement run after 15:00 WAT |
Settlement runs take place every 15 minutes, so a batch is created within about a quarter of an hour of its period closing. The payout itself then depends on the receiving bank.
On T+0, payments that arrive after 15:00 WAT are picked up by the next settlement run, so nothing is ever skipped.
Minimum settlement amount#
Your account can have a minimum settlement amount. When the net total for a period is below it, no batch is created and the payments carry over to the next period until the total reaches the minimum.
What is held back#
- Underpayments awaiting a decision. An
underpaidtransaction is settled once it is resolved, either topped up topaidor accepted or refunded according to your payment behaviour settings. - Payments with a refund in progress. They are settled when the refund completes, net of the refunded amount.
- Held settlements. Yusr may put settlements on hold, for example during a risk or compliance review or
while a reconciliation difference on your account is being investigated. A held batch has the status
on_holdand is released once the review is complete.
Settlement account#
Settlements are paid only to the bank account registered in your dashboard. When you add or change it, the
account name is checked against the bank's records (name enquiry) before it can receive funds. Changing the
settlement account requires the settlement_account.manage permission (Owner and Admin roles).
Settlement statuses#
| Status | Meaning |
|---|---|
pending | The batch was created and is waiting to be paid out. |
processing | The payout is in progress. |
completed | The money has been paid to your bank account. A settlement.completed event is sent. |
failed | The payout did not go through. It is retried automatically; contact support if it stays failed. |
on_hold | The batch is held for review and will not be paid out until it is released. |
Fees#
Fee plans#
Each account has one fee plan. Yusr supports three kinds:
| Plan type | Fee per successful transfer |
|---|---|
| Percentage | A percentage of the amount received |
| Flat | A fixed amount per transaction |
| Percentage with cap | A percentage of the amount received, never more than the cap |
The standard plan is 1.5% per successful transfer, capped at ₦2,000. See the
pricing page for current pricing and a fee calculator. Your own plan is shown in the dashboard. Fees are charged only on money that actually arrives: a transaction that expires or is cancelled without a payment costs nothing.
Worked examples#
With the standard plan (1.5%, capped at ₦2,000), and you bearing the fee:
| Customer transfers | Fee | You receive |
|---|---|---|
₦5,000.00 (500000 kobo) | ₦75.00 (7500) | ₦4,925.00 (492500) |
₦25,000.00 (2500000 kobo) | ₦375.00 (37500) | ₦24,625.00 (2462500) |
₦200,000.00 (20000000 kobo) | ₦2,000.00 (200000, capped) | ₦198,000.00 (19800000) |
₦1,000,000.00 (100000000 kobo) | ₦2,000.00 (200000, capped) | ₦998,000.00 (99800000) |
The cap is reached at about ₦133,333. Percentage fees are rounded to the nearest kobo.
Fees are charged on what was received#
The fee is calculated on the amount actually received, not the amount requested. If a customer underpays a
₦25,000 transaction by sending ₦12,500, the fee is ₦187.50 (18750 kobo), not ₦375. Overpayments are charged on
the full amount received, still subject to the cap.
Who pays the fee#
Your fee plan also sets who bears the fee. Every transaction shows it in fee_bearer.
fee_bearer | What the customer transfers (payment.amount) | What you receive (net_amount) |
|---|---|---|
merchant (default) | Your amount | amount − fee |
customer | amount + fee | Your full amount |
Always show the customer payment.amount, never your own amount: when the customer bears the fee they are
different. When the customer bears the fee and underpays, the fee is the plan's fee on what was received, never more
than the fee quoted at creation.
Check your balance#
List settlements#
Settlements are returned newest first. Page through them with limit (1 to 100, default 20) and starting_after
set to the previous page's next_cursor.
Retrieve a settlement#
Retrieving a single settlement also returns the transactions it includes, so you can reconcile each payout against your orders.
| Field | Description |
|---|---|
period_start, period_end | The settlement period (ISO 8601, UTC). Midnight WAT is 23:00Z the day before. |
gross | Total received in the period, in kobo, less any refunds. |
fees | Total Yusr fees, in kobo. |
net | gross − fees: the amount paid to your bank account. |
transaction_count | Number of transactions included. |
bank_account | The account the batch is paid to; the account number is masked. |
completed_at | When the payout completed, or null. |
transactions | Only on retrieve: each transaction's received amount, fee and net amount, in kobo. |
The list endpoint returns the same object without transactions.
The settlement.completed event#
When a batch is paid out, Yusr sends a settlement.completed event to the webhook endpoints subscribed to
it. The payload carries the settlement in data.settlement:
The settlement object in the event is shortened here. See Webhooks for signature verification and delivery rules.