Every collection and payout carries fees. Kyshi returns them itemised on the transaction and on the webhook, so you can reconcile to the cent rather than inferring a total.

Who Pays

feeBearer decides whether the fee comes out of your revenue or is added to what the customer pays.

feeBearer can be set per payment link, per virtual account, and per external link. If you do not set it, your business default applies.

When feeBearer is CUSTOMER, the amount the customer actually owes is larger than the amount you sent. For virtual accounts, the customer-facing figures are returned explicitly:

Show payableAmount to the customer, never requestedAmount. Displaying the wrong one is the most common cause of PARTIAL collections.

The Fee Breakdown

feeBreakDown appears on transactions and inside meta.feeBreakdown on webhooks.

{
  "processorFee": 50,
  "stampDuty": 0,
  "vat": 10,
  "fee": 200,
  "allInclusiveKyshiFee": 200,
  "others": {},
  "totalFees": 260
}

Reconcile against totalFees. Do not sum the individual components yourself — allInclusiveKyshiFee overlaps with fee and vat, so adding every field together will overstate the total.

Amounts in the breakdown are in the transaction's local currency, in major units.

Net Amount

netAmount is what the transaction contributes to your balance after fees:

netAmount = amount - totalFees        (feeBearer = MERCHANT)
netAmount = amount                    (feeBearer = CUSTOMER)

Use netAmount for revenue recognition. Use amount for what the customer was charged. They are different numbers and conflating them will break your books.

Tax Treatment

taxChargeable describes how tax relates to the fee.

This is returned on the transaction and in meta.taxChargeable. It is set by your pricing configuration rather than per request.

How Fees Are Structured

Your pricing may be a flat amount, a percentage, a combination, or tiered by amount. Percentage pricing is commonly capped, so that large transactions do not attract an unbounded fee — the cap applies once the transaction crosses a trigger threshold.

The exact figures for your account are part of your commercial agreement and are visible on your dashboard. They are not something your integration should hardcode; read feeBreakDown from the response instead, so that a pricing change does not silently break your reconciliation.

Pricing can differ by payment channel — card, bank transfer, and mobile money are priced separately — and by whether the money is coming in or going out.

Checking Fees Before You Charge

To show a customer what they will pay before creating a transaction, or to model your own margin, read your current rate and fee configuration:

GET {{host}}/v1/config/rates

This returns the rate and fee that would apply, along with the relevant business settings. See FX And Rates.

Payout Fees

Payouts carry fees too, and they are charged against your available balance alongside the payout amount. Kyshi checks that your balance covers both before sending. If it does not, the payout is rejected with an insufficient funds error.

When you are sizing a payout against your balance, subtract the fee as well as the amount. See Balances.

Next

• FX And Rates — how conversion is priced
• Settlements — how net proceeds reach your bank
• Balances — where funds sit in between