Fees and fee quotes

Ikawaari calculates fees with fee rules managed by operations. A fee quote is the public, developer-facing representation of that calculation. It lets you show fees before a customer confirms a payment or before a merchant executes a payout.

Developer or checkout asks for fees

Standalone quote Estimate

PaymentIntent fee_quote Locked

Withdrawal preview Locked

Show subtotal, fees, total

Confirm with fee_quote_id

Snapshot applied Ledger source of truth

React Flow

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Quote types

Use a standalone quote when you do not have an operation yet:

POST /api/v1/fees/quote

Standalone quotes return guarantee=estimate. They are useful for calculators and UI previews, but they are not attached to a future confirmation.

Use an attached quote when an operation already exists:

POST /api/v1/payment-intents/{id}/fee_quote
POST /api/v1/checkout/sessions/{id}/fee_quote
POST /api/v1/merchant/withdrawals/preview

Attached quotes return guarantee=locked_until_expiry. Pass the fee_quote_id back when confirming the PaymentIntent or executing the withdrawal.

Fee modes

merchant_pays keeps the customer amount unchanged. The merchant pays the fee from the collected balance or payout balance.

customer_pays adds the fee to the amount charged to the customer. Checkout surfaces should display subtotal, fee, and total due.

FeeQuote object

{
  "id": "feeq_123",
  "object": "fee_quote",
  "scope": "payment_intent",
  "service": "collect",
  "operation_id": "pi_123",
  "amount": 10000,
  "currency": "XOF",
  "fee_amount": 250,
  "fee_currency": "XOF",
  "fee_mode": "merchant_pays",
  "amount_charged": 10000,
  "merchant_net_amount": 9750,
  "merchant_debit_amount": 0,
  "guarantee": "locked_until_expiry",
  "expires_at": "2026-06-07T23:59:00Z",
  "status": "quoted"
}

After confirmation, Ikawaari stores the applied quote as a snapshot on the PaymentIntent or Payout. Settlement and ledger posting use that snapshot rather than recalculating fees later.

Errors

If a quote is expired or no longer matches the operation context, the API returns a conflict with reason fee_quote_expired or fee_quote_mismatch. Create a new quote and ask the user to confirm again.

Rules may also produce zero-fee quotes when no active fee rule matches the service, country, and currency.