Use Case

Refund to wallet

Refund your users by crediting their wallet to keep funds on your platform


Sometimes you need to refund money to customers: Maybe they returned a purchase, or canceled a transaction. In-app wallets are an opportunity to keep that money on your platform when issuing a refund. By refunding to a wallet, you avoid the expense of initiating the refund with your payment processor. Plus the customer gets their refund instantly, instead of waiting for the refund to post to their credit card. Formance Ledger makes not only creating and refunding to wallets instantaneous, and makes it straightforward to charge new purchases to the wallet.

Using this pattern

Let's suppose you want to offer your customers a way to receive refunds via an in-app wallet, instead of transferring the money back to their credit card. Wallets significantly reduce the friction of processing a refund: You don't need to worry about the expense of sending the request to your payment processor, and your customer can get their refund instantly.

So, you have a customer who placed an order, but the item was defective, and they returned it. When they checked out, you moved funds from their credit card into a special account for tracking the order. To process the refund, we move the funds back from the order tracking account into a wallet account assigned to the user.

But because you like to keep your sellers happy by paying them promptly, it might be that there are not enough funds in the order account—you may have already paid the seller. To keep the relationship with your seller happy, perhaps you are willing to eat the loss and bear some or all of the costs of the refund yourself.

Formance Ledger lets you structure a refund that combines funds from the order account and credits from yourself using a multi-source transaction. Suppose customer with ID U1234 is requesting a refund from transaction T3456 for an item costing £18.35. We can describe the transaction using Numscript as such:

send [GBP/2 1835] (
  source = {
  destination = @user:U1234:wallet

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:transaction:T3456 is the order account, representing the funds that you set aside from the order with ID T3456. The @world account is a special account that represents money coming in from the outside world—in this case, representing a credit you provide them. The account @user:U1234:wallet is the customer's wallet—it will be created if it doesn't exist. Finally, the transaction indicates that you are requesting payment first from the order account, and if there are insufficient funds remaining, to draw the remaining amount from @world—you are essentially creating money for the customer's future use.

Splitting the source like this means you don't need to first inquire to the balance in the order account to see if there is enough, and if not, make the necessary calculations to determine how much credit to create. Instead, of relying on standard floating point math, which is too imprecise for financial calculations, let Formance Ledger handle these calculations with its sophisticated integer math algorithms without remainder or error.

Formance Ledger also lets you attach metadata to the refund transaction, for context and your own record keeping. For example, you can add a refund reason such as "breakage", or even return shipping details to keep all the related data close to each other.

Use Cases

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

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

Retain your best merchants with instant payouts

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