Use Case

Collecting fees

Use multi-destination to collect fees on your ledger transactions


You facilitate transactions: Maybe you offer an n-sided marketplace, brokerage services, or international wire transfers. But of course, you collect a fee or commission for the services you offer. You want to be able to capture those fees in real time, as close as possible to the transaction that triggered it. And of course, you also need to pay sales tax or VAT on that fee, essentially a fee-within-a-fee. Formance Ledger can help you accurately track and gain insight into your fee collection in real time.

Using this pattern

Let's suppose you are a marketplace, bringing together buyers and sellers. You collect payments from the buyers, and deliver them to the sellers—and of course you also collect a fee for facilitating the transaction. Further, one or more government entities will be collecting sales tax or VAT on your fee, and you need to set that money aside to pay your tax bill. You need to track your fee and tax collection to ensure accuracy and auditability, and you want real-time monitoring to assess the health of your business minute-to-minute.

Imagine you have a buyer who has some credit with you, because they redeemed a gift card. The purchase flow could look like this: The buyer sends a payment from their gift card balance to the seller via your platform. At that moment, you take (let us suppose) a 5% fee, passing the remaining 95% to the seller's account. Additionally, since you will owe VAT on this fee, you need to set aside (again, supposing) 21% of your fee into your VAT account.

Formance Ledger lets you structure these kinds of transactions using Numscript. The buyer with ID U2342 is sending €23.54 from their credit to seller with ID U8743 to purchase an item. You could describe the transaction, including your fee, and the VAT you owe on your fee, as such:

send [EUR/2 2354] (
  source = @user:U2342:main
  destination = {
    5% to {
        21% to @platform:vat
        remaining to @platform:fees
    remaining to @user:U8743:main

Let's break this Numscript transaction down. This Numscript snippet takes advantage of namespaces to name the accounts in a readable, hierarchical way. The account @user:U2342:main represents the primary account held by the buyer, ID U2342. Same for @user:U8743:main and seller, ID U8743. And, as you might have guessed, the accounts labeled @platform:vat and @platform:fees are where you, the marketplace, collect your fees and set aside money for future VAT payments.

What this transaction does it a little bit complicated, but only a little bit. It says to take €23.54 from the buyer's account, and then divide it up. 5% of the transaction goes to you, but you need to set aside 21% of that fee to pay your taxes. The remainder goes into the account that keeps the fees you collected. Then, the remaining 95% gets sent to the seller.

Numscript lets you nest multiple destinations in a way that prevents you from having to do error-prone math to determine how much money should end up at each destination, and does so in a way that avoids fractional cents and without rounding errors.

This flexibility also means that you can subdivide transactions into an arbitrary number of destinations, for example if you collect different kinds of fees, or want to keep track of sales tax or shipping costs on behalf of the seller. Or perhaps your buyer wants to purchase from a number of different sellers in one transaction.

By capturing your fees using nested destinations, you can get information in real-time about the performance of your marketplace, and your revenue from transactions.

Use Cases

Split a customer payment to multiple parties with templates

Keep track precisely on how much you earned on a given timeframe

Model funds in flight on your ledger to enable deferred payouts and fund pending processing

900+ payments innovators building on Formance and sharing best practices.