Fees & settlement

Every collection and payout carries an explicit fee breakdown (fees.platform_fee, fees.provider_fee, fees.total_fee and the bearer) on the object itself, in decimal strings of its own currency. The standard rates per country, the same as on our pricing page:

A collection fee is a percentage of the collected amount: by default your business pays it and your balance is credited net, or you pass it to the customer (see Who pays the fee). A payout fee is debited on top of the payout amount (total_debit = amount + fee). Fees are rounded up to the currency's smallest unit.

These are account-level defaults, not a permanent price list: fee schedules are configured per environment, provider, method, currency and (where agreed) per merchant, so your account may carry negotiated rates. A failed transaction costs nothing: a failed collection credits nothing, and a failed payout releases its full reserve, fee included.

Never hardcode a rate: GET /v1/pricing quotes the exact fee for a prospective payment through the same fee engine the money path uses, so the quote and the charge cannot disagree.

curl "https://api.capayglobal.com/v1/pricing?direction=collection&country=CM&currency=XAF&method=mobile_money&amount=10000" \
  -H "Authorization: Bearer sk_live_XXXXXXXXXXXX"

{
  "status": "success",
  "data": {
    "direction": "collection",
    "country": "CM",
    "currency": "XAF",
    "method": "mobile_money",
    "amount": "10000",
    "fees": {
      "provider_fee": "0",
      "platform_fee": "199",
      "total_fee": "199",
      "bearer": "merchant"
    }
  },
  "request_id": "5c7d9e10-2b34-4a56-9f78-e01a2b3c4d5e"
}

Each business chooses who pays the collection fee, in the portal under Settings, "Who pays the payment fee". My business pays (the default): the payer is charged the amount and your balance is credited the amount minus the fee. My customer pays: the payer is charged your order plus the fee, and your balance is credited exactly your order.

You can also choose per payment with fee_bearer ("merchant" or "customer") on POST /v1/collections; it overrides the business setting for that payment. On a customer-pays collection, amount is what the payer was charged, order_amount is your order, fees.bearer is "customer" and net_amount equals order_amount. The fee is computed on the total so it covers itself, rounded to the currency's smallest unit.

Your balance per currency has three buckets, all visible on GET /v1/balances and in the portal. A completed collection credits its net amount (face amount minus merchant-borne fees) to PENDING. Settlement then releases pending funds to AVAILABLE once the settlement hold has passed. Payouts and refunds spend AVAILABLE: the full debit is reserved (LOCKED) before any provider is called and leaves the balance only when the provider outcome is confirmed.

collection completes  ->  PENDING balance   (net of fees)
settlement releases   ->  AVAILABLE balance  (within a minute, from your first payment)
payout / refund       ->  LOCKED, then leaves on settle
settlement payout     ->  AVAILABLE debited, cash sent to your account

Nothing ever moves twice and nothing moves silently: every transition is one ledger journal, and GET /v1/balance_transactions is the line-by-line history behind the numbers.

Every completed payment, from your very first one, is released to your available balance within about a minute of completing: the settlement engine runs every minute, live and in the sandbox. Each settlement (stl_...) carries its gross, fee and net totals plus the statement lines naming every collection inside it; you can read them in the portal under Settlements, and the portal shows when pending money becomes available.

The timing can be changed on your account: a longer automatic hold (T+2, 48h), a minimum batch amount, fully manual release, or terms agreed in your contract. Capay Global may also hold an individual payment for review when it looks unusual, and can release money early on request. Withdrawals have no platform hold: they leave from your available balance straight away. Talk to your account manager to change your timing.

Every completed batch emits a settlement.completed webhook, so your systems can reconcile the release without polling.

A settlement payout is how collected funds physically leave the platform to an account you own. You register settlement accounts in the portal (bank, mobile money, or a crypto wallet with its network and address); payouts against them are recorded by our operations team, debit your available balance the moment they are recorded, and appear in the portal Settlements page with their full detail. Timing and destination are arranged with your account manager.

Crypto settlement payouts record the asset, network, destination address, crypto amount and the fiat exchange rate applied, and once sent they carry the on-chain transaction hash, shown in the portal with a link to the block explorer, so every settlement is independently verifiable.

A settlement payout moves pending -> sent -> confirmed. A payout that fails or is cancelled reverses in full: the debit comes straight back to your available balance. History is append-only; a recorded payout is never edited away.

How you get paid: destinations, cadence and the FX line

When a settlement payout is paid in a different currency or asset than the one you collected in (a USDT settlement of an XAF balance, for example), the exchange rate is approved by Capay Global treasury: one admin proposes it, another approves it, and the applied rate appears on the settlement payout row you see in the portal. GET /v1/fx/rates lists every approved pair in your environment, each with its mid and the spread applied against you.

If you want the rate fixed before you ask for settlement, POST /v1/fx/quotes locks it into a quote for the quote TTL (15 minutes by default; quote_ttl_seconds on the rate says what applies). The quote applies only if the settlement payout is created before it expires: share the quote id with your account manager when you request settlement, and the payout will name the quote it consumed and settle at exactly its terms.

A quote informs and locks; it does not convert money. No balance is converted automatically, no journal is posted by a quote, and cross-currency payouts are not offered on POST /v1/payouts. Every rate and quote object carries conversion: "manual_settlement_only".

FX rates and quotes reference

Where payout corridors are open (see Coverage), you can also move available balance yourself with POST /v1/payouts to any mobile money recipient: same-currency, real-time, with the reserve-then-settle guarantees of the Payouts API. Many merchants use payouts for their own disbursement product and settlement payouts for treasury. Coverage