Pay with wallet

Your customers can hold credit with you: Maybe you offer gift cards, promotional credits, or purchase refunds in credit. Your customers will sometimes want to pay for purchases using a combination of credit and their own funding. Or sometimes you may make partial payment in their own funding that a condition, for example on promotional credits. Either way, Formance Ledger can help your customers understand complex payments with payment previews and the ability to structure transactions originating from multiple sources.

Let's suppose you want to offer your customers a promotional discount in the form of credit. You also want to place a ceiling on the amount of credit that can be used in a single transaction, so that part of the transaction is always paid via the customer's credit card. This is a fairly common promotional scheme that encourages repeated use of your platform, by preventing the credit from being used up in one go.

You offer a promotional campaign that awards €50 in credit, but limits how much credit can be applied to a single transaction €5. When a customer goes to checkout, you want to be able to accurately split their bill between their credit and their card. You want to know how much to charge their card, and they want to know how much they save.

Formance Ledger lets you structure a transaction using split payments. You need only specify how the promotional credit program is structured, using Numscript, and Formance Ledger will perform the calculations for you. Suppose that a customer with ID U1234 is making a purchase totaling €12.50, and they want to apply some of their promotional credit. You can describe the transaction using Numscript as such:

send [EUR/2 1250] (
  source = {
    max [EUR/2 500] from @user:U1234:promotional:P1234
    remaining from @world
  }
  destination = @plaform:sales
)

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:U1234:promotional:P1234 represents the credit held by the customer ID U2342, resulting from participating in promotion ID P1234. The @world account is a special account that represents money coming in from the outside world—from the customer's credit card. The account @platform:sales is your account for collecting revenue from sales on the platform. Finally, this transaction specifies that no more than €5.00 be applied to the purchase from the promotional credit, with the remainder to be charged to their card.

You could of course calculate these amounts on your own, but floating point math is too imprecise for finance. Numscript avoids this problem by only using integer math and a sophisticated rounding algorithm for dividing payments up without remainder or error.

When it's time to show the total price for the order, you can deliver this Numscript to Formance Ledger with the preview flag set. The preview flag tells Formance Ledger to execute the script, but not to record the results, generating a preview of what would happen (hence the name of the flag). Formance Ledger will respond by giving your backend the results of its calculations, namely that €5.00 will be drawn from credit and €7.50 will be charged to the credit card. Moreover, because the transaction was flagged as a preview, there's nothing to reverse in the ledger if the customer decides not to follow through with the purchase.

Supposing our customer does follow through, you can then re-submit the transaction without the preview flag, to commit the transaction and trigger a call to your payments processor to charge the customer's card.