Split payments

You sell products or services that combine offerings from multiple vendors: Maybe you sell items and need to charge for shipping, or you have a 2-sided marketplace where customers can buy items from multiple sellers. You need to split a payment across multiple vendors, and you likely need to charge shipping on a per-vendor basis as well. Formance Ledger lets you use templates to describe transactions, making it easier to construct frequently-used transaction models.

Let's suppose you are a marketplace, bringing together buyers and sellers. Buyers can place items from multiple sellers in their basket, to be paid for together in a single transaction. Of course, you also need to collect payment for shipping as well. You need to track these transactions accurately, to ensure each party receives the amount they expect.

Imagine you have a buyer who has a few items in their cart, all from different vendors. Those vendors, in addition, charge for shipping. The buyer expects a smooth, unified purchasing experience, by paying for all their purchases in one go, as though they were buying directly from you. It's up to you to distribute the payment correctly across every recipient. Formance Ledger lets you structure these kinds of transactions using Numscript.

Your buyer has purchased items from several vendors, each of which charges shipping. Let's suppose the payment from the buyer has cleared, and you need to distribute the funds to the merchants. You could write a new Numscript transaction to represent each individual disbursement. Or you could use Numscript's templating feature to write one transaction:

vars {
  monetary $amount
  monetary $shipping_amount
  account $buyer
  account $seller
  account $seller_shipping
}
 
send $amount (
  source = $buyer
  destination = $seller
)
 
send $shipping_amount (
  source = $buyer
  destination = $seller_shipping
)

Let's break this Numscript transaction down. This is a template: By itself, this Numscript can't be run. At the very top, we see five variables declared:

• $amount represents the purchase amount for an item

• $shipping_amount represents the cost of shipping to be paid by the buyer

• $buyer is the account of the buyer (or more likely a temporary account holding the funds to track the larger transaction involving multiple sellers)

• $seller is the seller's account for collecting sales

• $seller_shipping is the seller's account for collecting shipping fees

Then, after the variable declaration, there are two postings that will be executed sequentially: One moves the money for the purchased item into the seller's sales account, and the second moves the money for the shipping into the seller's shipping account.

You can then take this template and run it for each seller that the customer is buying from, filling in the variables with each run. This saves you having to construct the Numscript transaction at runtime, allowing you to retrieve it as a static asset. You need only fill in the variables.