Fees and how amounts are calculated
A transfer can carry three fees: Nodu's service fee, your developer fee and a network fee. Nodu deducts them from the amount that funds the transfer.
The three fees
| Fee | Who sets it | Currency | When it applies |
|---|---|---|---|
serviceFee | Nodu, as your agreement with Nodu defines it. | The source currency. | When your agreement sets one. |
developerFee | You. You send it in the quote or in the transfer, as a fixed amount and not as a percentage. It is your fee for the transfer. | The source currency. | When you send it, or when the transfer uses a quote containing it. Without either, the fee is 0. |
networkFee | Nodu, for the blockchain network's cost of the payout. | The destination currency. | On a payout to a crypto wallet. A payout to a bank account or to a Nodu wallet has no network fee. |
From the amount paid to the amount received
These are the steps of the breakdown of a quote. The amounts are decimal strings.
initialAmountis the amount that funds the transfer.- Nodu adds
developerFeeandserviceFee, and rounds the sum up to the decimal places of the source currency. subtotalAmountisinitialAmountminus the fees, rounded down to the decimal places of the source currency.exchangedAmountissubtotalAmountmultiplied byexchangeRate, rounded down to the decimal places of the destination currency. When no conversion is needed,exchangeRate=1.finalAmountisexchangedAmountminusnetworkFee, rounded down to the decimal places of the destination currency. Without a network fee,finalAmountequalsexchangedAmount. The recipient receivesfinalAmount.
A fiat currency has the decimal places of its ISO 4217 definition, for example 2 for eur. A stablecoin has the decimal places of its token, for example 6 for usdc.
A worked example
The customer pays 1000.00 EUR by SEPA. Nodu pays USDC to a crypto wallet. The fees and the rate are an illustration, not Nodu's prices.
| Step | Field | Calculation | Result |
|---|---|---|---|
| 1 | initialAmount | The amount that funds the transfer. | 1000.00 EUR |
| 2 | developerFee | The fee you set. | 5.00 EUR |
| 2 | serviceFee | Nodu's fee. | 3.50 EUR |
| 3 | subtotalAmount | 1000.00 − 5.00 − 3.50 | 991.50 EUR |
| 4 | exchangeRate | The rate of the quote. | 1.0835 |
| 4 | exchangedAmount | 991.50 × 1.0835 | 1074.29025 USDC |
| 5 | networkFee | The fee for the payout on the blockchain network. | 0.05 USDC |
| 5 | finalAmount | 1074.29025 − 0.05 | 1074.24025 USDC |
The quote returns the same example in its breakdown:
"breakdown": {
"initialAmount": "1000.00",
"developerFee": "5.00",
"serviceFee": "3.50",
"subtotalAmount": "991.50",
"exchangeRate": "1.0835",
"exchangedAmount": "1074.29025",
"networkFee": "0.05",
"finalAmount": "1074.24025"
}
After the payout, the transfer's receipt carries the same amounts. It has no exchangedAmount. For a payout to a crypto wallet, it adds the transaction hash of the payout in destinationTxHash:
"receipt": {
"initialAmount": "1000.00",
"developerFee": "5.00",
"serviceFee": "3.50",
"subtotalAmount": "991.50",
"exchangeRate": "1.0835",
"networkFee": "0.05",
"finalAmount": "1074.24025",
"destinationTxHash": "0x0e2ada4c313e01de57cde340f15f77dd6ddc4cbd5a3ae84bfaaf719a07409685"
}
For incoming crypto, sourceTxHash identifies the funding transaction. Use both hashes for reconciliation; Retrieve a transfer returns the latest receipt.
Rounding shows in an off-ramp to a bank account. For example, an exchangedAmount of 457.626825 EUR becomes 457.62 EUR, because eur has two decimal places.
When the customer chooses the amount received
When you create a quote with destination.amount, Nodu calculates the steps in reverse. It adds networkFee to finalAmount, divides by exchangeRate, then adds the fees. Nodu rounds up at each of these steps. The result is the quote's source.amount, which is the amount of the transfer. See Quotes and exchange rates.
The fees in a quote and in a transfer
- A quote returns all the fields of the calculation in
breakdown. Show them to the customer before the customer confirms. Do not calculate the fees yourself: the quote returns them. - A transfer with a quote takes the fees, the exchange rate and the network fee from the quote. The fees stay as quoted. Nodu holds the exchange rate and the network fee for 15 minutes: see How long a transfer keeps the quoted rate.
- A transfer without a quote calculates
serviceFeewhen you create it. The exchange rate and the network fee are known only after Nodu converts the funds and sends the payout.
The transfer's receipt shows the amounts that apply to the transfer: initialAmount, developerFee, serviceFee, subtotalAmount, exchangeRate, networkFee and finalAmount. A field that is not known yet is absent.
If the amount does not cover the fees, Nodu refuses the quote or the transfer with a business rule violation. The error has rule=insufficient_transfer_amount. The detail field of the error states the amounts.
Next steps
- Quotes and exchange rates: create a quote and use it in a transfer.
- How transfers work: the parts of a transfer and a full request.
- Track and cancel a transfer: read the
receiptafter the payout.