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
• Fee components

Advanced fees

• Partner fees
• Account fees
• Payout method fees

Fee tutorials

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

• Sending fee
• Receiving fee
• Partner fee
• Account fee
• 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

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

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.

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.

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.

Payment type (conditional)

A fee can be configured to apply to either regular payments or return payments, set by the payment_type field.

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:

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.

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.

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.