This section introduces you to the concepts that apply to RippleNet fees. Before you direct payments across RippleNet, familiarize yourself with:
If you want to configure fees for your server, complete the steps in the following tutorials depending on your goals:
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.
For more information, see the API reference documentation for Fees. The following API operations are available:
Get fee by ID
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.
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.
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.
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.
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.
All conditional fee components must be met before a fee can apply to a payment.
Role type specifies the role that the account plays in the transfer on the instance. It is set by the fee's
For any transfer between accounts on an instance (node), there is exactly one sender and one receiver account.
Possible values include the following:
institution_receiving values apply only to payments with
type set to
receiver_institution_amount, respectively. For more information, see "Create quote collection" in the API reference.
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.
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.
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.
The sending account in a transfer collects any fees set with
"role_type": "sending" from the transfer amount before RippleNet calculates the
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.
The receiving account in a transfer collects any fees set with
"role_type": "receiving" from the transfer amount after RippleNet calculates the
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.
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 value acts as a condition for a fee to apply.
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.
Fees are configured with one currency, set by its
currency value. This must match the currency denominated for the account.
currency value acts as a condition for a fee to apply.
A fee can be configured to apply to either regular payments or return payments, set by the
payment_type value acts as a condition for a fee to apply.
A fee can be configured as a flat fee or a percentage fee, set by its
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.
You can distinguish fees by assigning a
fee_category and applying a free-form text
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|
||Fee for a payment sent or received overseas|
||Fee to the receiving bank where the beneficiary account is located|
||Fee to institution (such as an intermediary) helping to process a payment|
||Fee to the local government authority (and deducted from payment)|
Amount of fee set by the value of the
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.
You can configure fees that apply only to transfers to or from a specified account.
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.
You can configure fees that apply only to transfers to or from a specified partner.
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).
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
API operations. They can also set one payout method as the
by enabling the
Senders can request a quote collection for each of the receiver's configured payout methods by enabling
enable_quote_per_payout_methodflag in the request. They can also request a single quote by defining
payment_methodas 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|
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
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.