Skip to content
YusrDocs

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.

BalanceMeaning
pendingCollected, net of fees, not yet in a settlement batch.
availableIn a settlement batch that is being paid out.
settledTotal 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).

ScheduleSettlement periodPaid
T+1Payments received during the previous calendar day (00:00 to 24:00 WAT)In the first settlement run after midnight WAT
T+0Payments received on the same day before 15:00 WATSame 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 underpaid transaction is settled once it is resolved, either topped up to paid or 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_hold and 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#

StatusMeaning
pendingThe batch was created and is waiting to be paid out.
processingThe payout is in progress.
completedThe money has been paid to your bank account. A settlement.completed event is sent.
failedThe payout did not go through. It is retried automatically; contact support if it stays failed.
on_holdThe 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 typeFee per successful transfer
PercentageA percentage of the amount received
FlatA fixed amount per transaction
Percentage with capA 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 transfersFeeYou 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_bearerWhat the customer transfers (payment.amount)What you receive (net_amount)
merchant (default)Your amountamount − fee
customeramount + feeYour 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#

curl https://api.yusr.ng/v1/balance \
  -H "Authorization: Bearer sk_test_..."
JSON
{
  "object": "balance",
  "mode": "test",
  "currency": "NGN",
  "pending": 4925000,
  "available": 0,
  "settled": 0
}

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.

curl "https://api.yusr.ng/v1/settlements?limit=10" \
  -H "Authorization: Bearer sk_test_..."

Retrieve a settlement#

Retrieving a single settlement also returns the transactions it includes, so you can reconcile each payout against your orders.

curl https://api.yusr.ng/v1/settlements/stl_01M47G2ZQ8KX4T6N1B3D5F7H9J \
  -H "Authorization: Bearer sk_test_..."
JSON
{
  "id": "stl_01M47G2ZQ8KX4T6N1B3D5F7H9J",
  "object": "settlement",
  "mode": "test",
  "status": "completed",
  "currency": "NGN",
  "period_start": "2026-10-04T23:00:00.000Z",
  "period_end": "2026-10-05T23:00:00.000Z",
  "gross": 3500000,
  "fees": 52500,
  "net": 3447500,
  "transaction_count": 2,
  "bank_account": {
    "bank_name": "Partner Bank",
    "account_number": "******0000",
    "account_name": "ACME STORES"
  },
  "created_at": "2026-10-05T23:05:12.000Z",
  "completed_at": "2026-10-05T23:05:14.000Z",
  "transactions": [
    {
      "id": "txn_01M47EG1XHH9S3MTQD3FJ156FT",
      "reference": "order-1042",
      "amount_received": 2500000,
      "fee": 37500,
      "net_amount": 2462500
    },
    {
      "id": "txn_01M47EK1ATXWVR680RDPEJNB9X",
      "reference": "order-1043",
      "amount_received": 1000000,
      "fee": 15000,
      "net_amount": 985000
    }
  ]
}
FieldDescription
period_start, period_endThe settlement period (ISO 8601, UTC). Midnight WAT is 23:00Z the day before.
grossTotal received in the period, in kobo, less any refunds.
feesTotal Yusr fees, in kobo.
netgross − fees: the amount paid to your bank account.
transaction_countNumber of transactions included.
bank_accountThe account the batch is paid to; the account number is masked.
completed_atWhen the payout completed, or null.
transactionsOnly 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:

JSON
{
  "id": "evt_01M47G30A1B2C3D4E5F6G7H8J9",
  "type": "settlement.completed",
  "created_at": "2026-10-05T23:05:14.000Z",
  "mode": "test",
  "data": {
    "settlement": {
      "id": "stl_01M47G2ZQ8KX4T6N1B3D5F7H9J",
      "object": "settlement",
      "status": "completed",
      "net": 3447500
    }
  }
}

The settlement object in the event is shortened here. See Webhooks for signature verification and delivery rules.