This section introduces you to the concepts that apply to RippleNet fees. Before you direct payments across RippleNet, familiarize yourself with:

Advanced fees

Fee tutorials

If you want to configure fees for your server, complete the steps in the following tutorials depending on your goals:

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

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. The following API operations are available:

  • Get fees
  • Create fee
  • Get fee by ID
  • Update fee
  • Delete fee

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.


The role_type value acts as a condition for a fee to apply.

  • 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.

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.


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.


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:


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


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.


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 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.