Fees

Quote fee, tax and total before submitting an operation

POST/api/v1/tenant/fees/quote

Scope wallets:read

Read-only: nothing is charged and no operation is created. The quoteId is valid for five minutes; pass it as feeQuoteId on POST /tenant/payouts to pin the charges.

Request body

Field	Type	Required	Description
operationType	enum	yes	The operation you are about to submit. Only wallet_credit, wallet_debit, payout_b2c and topup_c2b can be quoted. One of wallet_credit, wallet_debit, payout_b2c, topup_c2b, hold, safeguarding_fund, client_funding_deposit, settlement_sweep, wallet_closure, closed_balance_refund, ledger_adjustment, wallet_transfer.
walletUid	string	yes	The wallet the operation will move money on, as returned by POST /tenant/customers.
amount	string	yes	A positive amount with at most two decimal places; the operation amount before charges.
currency	string	yes	ISO-4217; must equal the wallet's currency.
railCode	string | null	no	The payment provider's code the operation will use, when it has one (payout, top-up). At most 64 characters.

Example (placeholder values)

{
  "operationType": "wallet_credit",
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "amount": "2500.00",
  "currency": "ETB"
}

Response · 200

Field	Type	Description
quoteId	string	Pass as feeQuoteId on POST /tenant/payouts to pin these charges while the quote is valid.
operationType	enum	One of wallet_credit, wallet_debit, payout_b2c, topup_c2b, hold, safeguarding_fund, client_funding_deposit, settlement_sweep, wallet_closure, closed_balance_refund, ledger_adjustment, wallet_transfer.
walletUid	string
currency	string
amount	string	The amount quoted, as sent.
fee	string	The flat / percentage components.
tax	string	The vat components.
total	string	amount + fee + tax, what the wallet is debited.
breakdown	object[]
breakdown[].label	string	The component's label in the fee rule.
breakdown[].type	enum	One of flat, percentage, vat.
breakdown[].amount	string	A decimal amount with two decimal places; a zero component is listed at 0.00.
breakdown[].refundable	boolean	Whether a failed payout refunds this component.
breakdown[].appliesToLabel	string | null	For vat, the label of the component it applies to.
ruleVersion	object | null	The fee rule version the quote was priced under; null for a zero-fee operation.
ruleVersion.uid	string
ruleVersion.ruleCode	string
ruleVersion.versionNo	number
railCode	string | null	The payment provider's code, as sent; null when none was sent.
validUntil	string	Instant the quote stops being honoured — five minutes from issue.

Example (placeholder values)

{
  "quoteId": "string",
  "operationType": "wallet_credit",
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "currency": "ETB",
  "amount": "2500.00",
  "fee": "12.50",
  "tax": "1.88",
  "total": "2514.38",
  "breakdown": [
    {
      "label": "string",
      "type": "flat",
      "amount": "12.50",
      "refundable": true,
      "appliesToLabel": "string"
    }
  ],
  "ruleVersion": {
    "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
    "ruleCode": "string",
    "versionNo": 0
  },
  "railCode": "string",
  "validUntil": "string"
}

Errors

400 401 403 404 429 500 503 — one body shape for all of them, see Errors.