Sometimes you have a transfer that requires processing, but you want to move only a portion of the specified amount. For example:
You want to break a transaction up into multiple smaller transactions.
You want to charge a penalty fee when a vendor needs to refund a customer. You want that fee to be a percentage of the refund amount, but you don't want to take that fee from the refund itself.
Make sure that you're set up properly: Read through the prerequisites first!. Otherwise the examples below won't work.
Holding back part of a transaction
kept keyword allows you to specify a transaction that only moves a portion of the transaction amount. As a very basic example of the functionality, imagine that we need to send 15% of a 100 coin transaction from the
leslieknope. We could hard-code the 15% fee into our Numscript like this:
But doing so is error-prone; better to let Formance Ledger do the math for us! Here's how to use the
kept keyword to achieve the same thing in a less error-prone way:
leslieknope will receive 15 coins in total, and the rest is held back in the
centralbank account, while letting Formance Ledger handle the math.
Implementing Refund Penalty Fees
The game land of Cones of Dunshire has a no-take-backsies policy: While players can sell their interest in a cone to another player, we want to disincentivize refunds by charging the seller a 15% fee. Of course, the buyer should always receive the full refund for a returned cone! So, when refunds happen, 115% of the original sale price needs to be taken from the seller's account: 100% to the refunded buyer, and 15% to the central bank.
So, imageine that
leslieknope has sold an interest in a cone to
annperkins for 85 coin.
annperkins is, for whatever reason, dissatisfied with her cone—she wants to return it for a refund.
leslieknope reluctantly agrees, knowing she will pay a 15% penalty for the refund.
We can structure the refund with penalty fee as a Numscript template like this:
Numscript templates are a powerful tool for creating re-usable transactions.
This Numscript template takes an amount as an argument, and creates two transactions around that amount. The first transaction represents the refund penalty, and takes 15% of the amount from the seller,
leslieknope, sending it to
centralbank. The second transaction refunds
annperkins the full amount of the original transaction from
You cannot use the command line to execute Numscript templates.
At least, not at this time. That feature is coming though! In the meantime you can execute Numscript templates using Formance Ledger's built-in API server. If you've never done that before, take a moment to read up on how to use the API server to execute Numscript.