​
Overview

A money movement map is a group of transaction flows that describe how money moves through your system when an action is triggered in your application. A money movement map gives teams a summary overview of the different sources and destinations that make up all transaction flows, helping you define how to architect your ledger for efficient tracking and recording.

The structure of a system’s money movement map depends primarily on your application’s use case and your approach to solving the problem. As a result, it is possible for two similar financial products to have different results when developing their movement maps.

In this guide, you’ll learn how to develop your money movement map and use it to build your ledger.

​
Creating your money movement map

To create your map, it is important to do this with your team — everyone involved with the financial operations of your application.

1

Make a list of all transaction activities

A transaction activity refers to any action that initiates a transaction in your application. For instance, in an e-commerce app, there can be at least 3 distinct transaction activities:

  1. Wallet funding
  2. Wallet withdrawal
  3. Paying with wallet on the app

These are the three specific transaction activities a user will perform in an e-commerce app. To define this for your application, figure how many transaction activities are possible within your application and list them out.

2

Draw a transaction flow for each activity

To draw a flow, you need three things — the start state, the end state, and the transaction journey. This must be drawn for each transaction activity listed in step 01.

A transaction flow for wallet funding looks like this:

This funding flow explains that the e-commerce charges a funding fee when the user attempts to fund their wallet via transfer or card payment. This flow also explains that the fee is deducted and delivered to a @Fees balance, while the remaining amount is delivered to the user’s balance.

Another way to do this is to deliver the entire amount to the user’s balance, and then debit the fees from the user. The flow would then look like this:

3

Collate your transaction flows together

The sum of all transaction flows form your money movement map. Following the example from above, this is the money movement app for our sample e-commerce app:

  1. Wallet funding (payin):
  1. Wallet withdrawal (pay-out):
  1. Pay with wallet on app:
4

Use your map to define how you build

Use your defined money movement map to set up your ledger architecture and your code. For instance, the sample map in step 3 shows that:

  1. Three internal balances are needed in the general ledger — @World, @Fees, @Revenue
  2. A new ledger should be created to group all user balances. This ensures total funds being held by all users in the e-commerce application can easily be traced and computed.
  3. Use the multiple destinations feature to process all interactions in wallet funding / withdrawal in one API request.
  4. Pay-in transactions should have overdraft enabled to process transactions from @World even when its balance is 0.
  5. Settlement and reconciliation of all income received from wallet payments can be traced on the @Revenue account.

​
Best practices

  1. Keep your money movement map as simple as possible. Too many nodes in a single transaction flow can make it hard to correctly trace funds in your system.
  2. Your money movement map should only list nodes that are directly controlled/managed by your application. Do not include (and in the process, duplicate) payment processors in your map.
  3. Review your map periodically to find out ways to improve how money is moved and traced in your application.

​
See also

Ledger architecture

Learn how to design your ledgers

Record a transaction

Learn how to post a transaction

Multiple destinations

Send money to multiple destinations

Setting up internal balances

Learn how to set up internal balances

​
Need help?

Need help with developing your organization’s money movement map? Do you have a question that isn’t answered in this doc? Have you run into a problem you can’t solve? Want to file a bug report?

Join our Discord server and share your questions/thoughts with other developers building financial applications like you.

Was this page helpful?