Frais et devis de frais

Ikawaari calcule les frais à partir des règles tarifaires gérées par les équipes opérations. Un devis de frais, ou FeeQuote, est la représentation publique de ce calcul pour les développeurs. Il permet d'afficher les frais avant qu'un client confirme un paiement ou avant qu'un marchand exécute un payout.

Le développeur ou le checkout demande les frais

Devis standalone Estimation

PaymentIntent fee_quote Verrouillé

Aperçu de retrait Verrouillé

Afficher sous-total, frais et total

Confirmer avec fee_quote_id

Snapshot appliqué Source de vérité ledger

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.

Types de devis

Utilisez un devis standalone quand aucune opération métier n'existe encore:

POST /api/v1/fees/quote

Les devis standalone retournent guarantee=estimate. Ils sont utiles pour les simulateurs, les calculateurs et les aperçus UI, mais ils ne sont pas rattachés à une future confirmation.

Utilisez un devis attaché quand une opération existe déjà:

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

Les devis attachés retournent guarantee=locked_until_expiry. Renvoyez ensuite le fee_quote_id au moment de confirmer le PaymentIntent ou d'exécuter le retrait.

Modes de frais

merchant_pays conserve le montant client inchangé. Le marchand paie les frais depuis le solde collecté ou depuis le solde utilisé pour le payout.

customer_pays ajoute les frais au montant facturé au client. Les interfaces checkout doivent afficher le sous-total, les frais et le total à payer.

Objet FeeQuote

{
  "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"
}

Après confirmation, Ikawaari enregistre le devis appliqué comme snapshot sur le PaymentIntent ou le Payout. Le settlement et les écritures ledger utilisent ce snapshot plutôt qu'un recalcul tardif.

Erreurs

Si un devis a expiré ou ne correspond plus au contexte de l'opération, l'API retourne un conflit avec la raison fee_quote_expired ou fee_quote_mismatch. Créez un nouveau devis et demandez à l'utilisateur de confirmer à nouveau.

Les règles peuvent aussi produire des devis à frais nuls quand aucune règle active ne correspond au service, au pays et à la devise.