# Fees This section introduces you to the concepts that apply to RippleNet fees. Before you direct payments across RippleNet, familiarize yourself with: - [Fees on RippleNet](#fees-on-ripplenet) - [Fee components](#fee-components) **[Advanced fees](#advanced-fees)** - [Partner fees](#partner-fees) - [Account fees](#account-fees) - [Payout method fees](#payout-method-fees) **[Fee tutorials](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees)** If you want to configure fees for your server, complete the steps in the following tutorials depending on your goals: - [Sending fee](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees#sending-fee) - [Receiving fee](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees#receiving-fee) - [Partner fee](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees#partner-fee) - [Account fee](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees#account-fee) - [Payout method fee](/products/payments-odl/api-docs/ripplenet/tutorials/configure-fees#payout-method-fee) ## Fees on RippleNet Institutions that use RippleNet can collect fees with their accounts. Accounts collect fees from processing transfers across RippleNet during a payment. You can configure fees for each of your institution's RippleNet instances. There are many configurable possibilities for how you can collect fees, including the following typical high-level strategies: - Sending institutions collect fees from their originating customer - Receiving institutions collect various fees: - From sending institutions that hold a nostro account on its ledger - From specific partners - For payments using specific payout methods Tip Fees on RippleNet are a currency amount that a RippleNet account collects for servicing a transfer during a payment, instead of an amount that it applies or charges. ### API references For more information, see the API reference documentation for [Fees](/products/payments-odl/api-docs/ripplenet/reference/openapi/fees). The following API operations are available: - `Get fees` - `Create fee` - `Get fee by ID` - `Update fee` - `Delete fee` Note The API reference describes each fee component field for the fee-related operations, but this document serves as a foundational introduction to fees on RippleNet. ### Fee matching For each payment that your institution's instance services, a configured fee applies only if each of the fee's components match those characteristics for the payment. Read about each fee component to understand what constitutes a match. #### Fee matching example You may need to create multiple fees to handle the business cases for your institution. For example, if you want your institution's instance to collect a uniform fee for all regular payments, you must create a fee with `payment_type: regular` values. ### Applying multiple fees You can set multiple fees for your RippleNet instance to cover many business use cases. More than one fee may apply to each payment your institution services. ## Fee components Understanding the components of a RippleNet fee will help you to properly plan out the correct fees for your institution's goals. This section details each fee component. Several configurable components act as a condition for whether or not the instance collects a fee for a payment. ### Fee conditionals All conditional fee components must be met before a fee can apply to a payment. ### Role type (conditional) Role type specifies the role that the account plays in the transfer on the instance. It is set by the fee's `role_type` value. For any transfer between accounts on an instance (node), there is exactly one sender and one receiver account. Possible values include the following: - `sending` - `receiving` - `institution_sending` - `institution_receiving` The `institution_sending` and `institution_receiving` values apply only to payments with `type` set to `sender_institution_amount` and `receiver_institution_amount`, respectively. For more information, see "Create quote collection" in the API reference. Note The `role_type` value acts as a condition for a fee to apply. Tips - Because there is no transfer between correspondent accounts, no fee can be collected by correspondent (nostro and vostro) accounts. - Accounts that make exchange transfers (FX conversion) do not collect fees. #### Role type example For a fee with `role_type` set to `sender`, only the account on the instance that sends a payment to another account on that RippleNet instance can collect the configured fee. #### Role type impact on RippleNet Payment Object Fees appear in the RippleNet Payment Object (RPO) as sending and receiving fees in each quote element. This section explains how sending and receiving fees affect sending and receiving amounts in the RPO. ##### Sending fees The sending account in a transfer collects any fees set with `"role_type": "sending"` from the transfer amount **before** RippleNet calculates the `sending_amount` and `receiving_amount` values. A quote element's `sending_amount` is the remainder amount after the account collects a fee. This means that adding the `sending_amount` value to the `sending_fee` value produces the total incoming transfer amount to the account from the previous hop (or origination) of the payment. ##### Receiving fees The receiving account in a transfer collects any fees set with `"role_type": "receiving"` from the transfer amount **after** RippleNet calculates the `sending_amount` and `receiving_amount` values. A quote element's `receiving_amount` is the amount produced by any foreign exchange conversion from the `sending_amount`, before the account collects the receiving fee. This means that subtracting the `receiving_fee` value from the `receiving_amount` value produces the total outgoing transfer amount to the account in the next hop (or the payout) for the payment. ### Node type (conditional) A fee's node type indicates how the RippleNet instance (node) participates in the payment's movement across RippleNet. The `node_type` field sets the value for what is the behavior of the node in the payment. If the `node_type` value matches the fee to apply to payments in which the instance (node) acts as either the initial, intermediate, or terminal node in the payment across RippleNet. Possible values include the following: - `INITIAL`: The instance (node) acts as the sender for the payment. - `INTERMEDIATE`: The instance (node) services the payment as an intermediary. - `TERMINAL`: The instance (node) acts as the receiver for the payment. Note The `node_type` value acts as a condition for a fee to apply. #### Node type example Each payment across RippleNet moves between at least two RippleNet instances (nodes). There can be only one node that initiates a payment and one that receives it. There may be any number of intermediary nodes in the payment path, including none. If you configure a fee with `node_type` set to `sending`, the instance must act as the sender for the account to collect the fee. Other fees may be applied based on their configuration. ### Currency (conditional) Fees are configured with one currency, set by its `currency` value. This must match the currency denominated for the account. Note The `currency` value acts as a condition for a fee to apply. ### Payment type (conditional) A fee can be configured to apply to either regular payments or return payments, set by the `payment_type` field. Note The `payment_type` value acts as a condition for a fee to apply. ### Fee type A fee can be configured as a flat fee or a percentage fee, set by its `fee_type` value. Flat fees are specified with an amount in the fee's currency. Percentage fees are calculated as a percent of the payment amount when the instance services it. ### Fee category You can distinguish fees by assigning a `fee_category` and applying a free-form text `fee_description`. The quote and payment contract responses show the fee category code and description, as well as the total fee value per node and currency. The table below summarizes the possible fee category codes: Caution All existing fees are automatically assigned to `NONE` to ensure forward compatibility in future API versions. | Category code | Category description | | --- | --- | | `OVERSEAS_DELIVERY_CHARGE` | Fee for a payment sent or received overseas | | `BENEFICIARY_BANK_CHARGE` | Fee to the receiving bank where the beneficiary account is located | | `PROCESSING_HANDLING_CHARGE` | Fee to institution (such as an intermediary) helping to process a payment | | `LOCAL_GOVERNMENT_CHARGE` | Fee to the local government authority (and deducted from payment) | | `OTHER` | Miscellaneous fee | | `NONE` | Default value | ### Value Amount of fee set by the value of the `value` field. ## Advanced fees Fees can be configured with granular control that allows you to set premiums for specific partners, accounts, or payout methods. With advanced fees and fees that do not specify this level of control, you can create the appropriate fee structures for your institution's business goals. Note **Slab Fee Precedence:** If your institution uses slab fees, slab fees take precedence over non-slab fees for two otherwise similar fees. For example, if you configure two account-level fees, one with slab pricing and the other without it, the slab fee applies to the transfers for that account. ## Account fees You can configure fees that apply only to transfers to or from a specified account. ### Account fee precedence An account fee takes highest precedence over other fees, including partner fees. If an account fee and another fee could both apply to a transfer, the account fee applies and the other fee does not. ## Partner fees You can configure fees that apply only to transfers to or from a specified partner. ### Partner fee precedence A partner fee takes precedence over fees that are not set for a specific partner or account. Only a fee that additionally specifies an account takes precedence over a partner fee. If a partner fee and another fee could apply to a transfer, the partner fee applies and other fee does not (unless the other fee is an account fee). ## Payout method fees You can set fees that apply only to transfers that use a specified payout method for the payment. * Receivers can configure one or more payout methods (free form text) using the *Payout method* API operations. They can also set one payout method as the [default](#default-payout-method) by enabling the `is_default` flag. * Senders can request a quote collection for each of the receiver's configured payout methods by enabling `enable_quote_per_payout_method` flag in the request. They can also request a single quote by defining `payment_method` as one of the receiver's configured payout methods. Or, by not setting anything in the request, they can receive a single quote based on the receiver's default payout method. The following table lists the API responses based on the receiver's payout method configuration and the sender's Create quote collection request. | Ver | Receiver payout method | Receiver default flag | Sender payout method | Sender enable flag | RippleNet Server Create quote collection response | | --- | --- | --- | --- | --- | --- | | 4.6 | 1 or more configured | false | Valid method | true or false | Returns quote with fees based on payout method specified by sender and configured by receiver | | 4.6 | 1 or more configured | false | - | true | Returns multiple quotes with fees based on payout methods configured by receiver | | 4.6 | 0 or more configured | false | - | false | Returns regular quote with fees that are not calculated using a payout method | | 4.6 | - | false | - | false | Returns regular quote with fees that are not calculated using a payout method | | 4.7 | 1 or more configured | true | - | false | Returns quote with fees based on default payout method configured by receiver | | 4.7 | 1 or more configured | false | Invalid method | true or false | Return no quotes/Throws an error | ### Default payout method If you want to specify a default payout method fee for all quote requests you can do so when you configure the payout method by passing the `is_default` key with the `true` value. ### Payout method fee precedence A fee that specifies a payout method takes precedence over fees that do not have a payout method. You can set partner-level and account-level fees that include payout methods.