diff --git a/docs/reconciliation.mdx b/docs/reconciliation.mdx new file mode 100644 index 0000000..b8e664f --- /dev/null +++ b/docs/reconciliation.mdx @@ -0,0 +1,24 @@ +--- +title: Reconciliation +pagination_next: null +pagination_prev: null +--- + +# Reconciliation + +Reconciliation is a managed service that provides a way to reconcile transactions between external Payment Service Providers (PSPs) and the Formance Ledger. It is a tool that helps you keep track of the transactions that are happening in your system and ensures that the balances in your system are in sync with the balances in the PSPs. + +## Use-cases + +Reconciliation can be a great fit if you are building: +- A marketplace where you need to keep track of the transactions happening in your system +- A system that needs to keep track of the transactions happening in multiple PSPs +- A system with complex money flows spanning acorss multiple accounts, providers or countries. + +## Documentation organization + +The documentation is organized as follows: +- tutorials that guide you through the setup and usage of the Reconciliation service +- how-to guides that provide step-by-step instructions on how to solve specific problems +- reference documentation that provides detailed information about the Reconciliation service +- explanations and clarification on the concepts and terms used in the Reconciliation service, as well as design decision discussions. \ No newline at end of file diff --git a/docs/reconciliation/explanation/_category_.yml b/docs/reconciliation/explanation/_category_.yml new file mode 100644 index 0000000..f9b9e0b --- /dev/null +++ b/docs/reconciliation/explanation/_category_.yml @@ -0,0 +1,2 @@ +position: 3 +label: "Explanations" \ No newline at end of file diff --git a/docs/reconciliation/explanation/account-based-reconciliation.png b/docs/reconciliation/explanation/account-based-reconciliation.png new file mode 100644 index 0000000..a5615b3 Binary files /dev/null and b/docs/reconciliation/explanation/account-based-reconciliation.png differ diff --git a/docs/reconciliation/explanation/what_is_reconciliation.mdx b/docs/reconciliation/explanation/what_is_reconciliation.mdx new file mode 100644 index 0000000..daeefb5 --- /dev/null +++ b/docs/reconciliation/explanation/what_is_reconciliation.mdx @@ -0,0 +1,32 @@ +--- +sidebar_label: "What is Reconciliation?" +sidebar_position: 1 +--- + +# What is Reconciliation? + +When you're working on payment systems, most of the time, you're not managing the money yourself. You depend on an external financial institution to manage the money for you. The reason for this is that managing money is a complex, highly regulated, and risky business. Most companies prefer to outsource this to a financial institution who are sepcialized in managing money. + +In the meantime, you need to keep track of the money that you're managing within your IT systems. You need to know how much money you have, how much money you owe, and how much money you're owed. This parts depends on your business model. In the Formance ecosystem, you model your money flows using the [Formance Ledger](../../ledger/index.mdx) or the [Formance Wallets](../../wallets/getting-started/index.mdx). + +Reconciliation is the process of putting side by side the money managed by the Formance platform and the money managed by the external financial institution and **making sure that they match**. + +In Formance Reconciation, we provide two types of reconciliation: +- account based reconciliation +- transaction based reconciliation (**coming soon**) + +Regardless of the reconcilation type, the produced artifact is a [reconciliation report](../reference/reports.mdx) that shows the differences between the Formance Ledger and the external financial institution, if any. This report is then used by CFOs and finance teams to identify and fix the discrepancies. + +## Account based reconciliation + +Account based reconciliation is the process of comparing the balances of a set of account in the Formance Ledger with the balances of the another set of accounts in an external financial institution and making sure that they match. + +![Account based reconciliation example](./account-based-reconciliation.png) + +For the account based reconciliation to be successful, the sum of the balances of the reconciled account set in the Formance Ledger must match the sum of the balances of the reconciled accounts set in the external financial institution. + +## Transaction based reconciliation + +:::warning +Transaction based reconciliation is not yet available. We are working on it and it will be available soon. +::: \ No newline at end of file diff --git a/docs/reconciliation/how-to/_category_.yml b/docs/reconciliation/how-to/_category_.yml new file mode 100644 index 0000000..6bafc4a --- /dev/null +++ b/docs/reconciliation/how-to/_category_.yml @@ -0,0 +1,2 @@ +position: 2 +label: "How to" \ No newline at end of file diff --git a/docs/reconciliation/how-to/reconciliation-across-psps.mdx b/docs/reconciliation/how-to/reconciliation-across-psps.mdx new file mode 100644 index 0000000..0b9a0ba --- /dev/null +++ b/docs/reconciliation/how-to/reconciliation-across-psps.mdx @@ -0,0 +1,6 @@ +--- +sidebar_label: "How to perform reconciliation across multiple PSPs?" +sidebar_position: 1 +--- + +# How to perform reconciliation across multiple PSPs? \ No newline at end of file diff --git a/docs/reconciliation/reference/_category_.yml b/docs/reconciliation/reference/_category_.yml new file mode 100644 index 0000000..a6ee594 --- /dev/null +++ b/docs/reconciliation/reference/_category_.yml @@ -0,0 +1,2 @@ +position: 4 +label: "Reference" \ No newline at end of file diff --git a/docs/reconciliation/reference/policies.mdx b/docs/reconciliation/reference/policies.mdx new file mode 100644 index 0000000..0761767 --- /dev/null +++ b/docs/reconciliation/reference/policies.mdx @@ -0,0 +1,6 @@ +--- +sidebar_label: Policies +sidebar_position: 1 +--- + +This page describes the reconciliation policies that are used to reconcile transactions. diff --git a/docs/reconciliation/reference/reports.mdx b/docs/reconciliation/reference/reports.mdx new file mode 100644 index 0000000..5002450 --- /dev/null +++ b/docs/reconciliation/reference/reports.mdx @@ -0,0 +1,8 @@ +--- +sidebar_label: "Reports" +sidebar_position: 2 +--- + +# Reports + +The page describes the reconciliation reports obtained from applying reconciliation policies. \ No newline at end of file diff --git a/docs/reconciliation/tutorials/_category_.yml b/docs/reconciliation/tutorials/_category_.yml new file mode 100644 index 0000000..aa48cc4 --- /dev/null +++ b/docs/reconciliation/tutorials/_category_.yml @@ -0,0 +1,2 @@ +position: 1 +label: "Tutorials" \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/_category_.yml b/docs/reconciliation/tutorials/account-based-getting-started/_category_.yml new file mode 100644 index 0000000..6a0d740 --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/_category_.yml @@ -0,0 +1,2 @@ +label: Getting Started with account based reconciliation +position: 1 \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/create_cashpool.mdx b/docs/reconciliation/tutorials/account-based-getting-started/create_cashpool.mdx new file mode 100644 index 0000000..45082ab --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/create_cashpool.mdx @@ -0,0 +1,6 @@ +--- +sidebar_label: "Create Cash Pool" +sidebar_position: 3 +--- + +# Create Cash Pool \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/create_policy.mdx b/docs/reconciliation/tutorials/account-based-getting-started/create_policy.mdx new file mode 100644 index 0000000..00f7385 --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/create_policy.mdx @@ -0,0 +1,6 @@ +--- +sidebar_label: "Create Reconciliation Policy" +sidebar_position: 4 +--- + +# Create Reconciliation Policy \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/generate_report.mdx b/docs/reconciliation/tutorials/account-based-getting-started/generate_report.mdx new file mode 100644 index 0000000..fc92e89 --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/generate_report.mdx @@ -0,0 +1,7 @@ +--- +sidebar_label: "Generate Reconciliation Report" +sidebar_position: 5 +pagination_next: null +--- + +# Generate Reconciliation Report \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/index.mdx b/docs/reconciliation/tutorials/account-based-getting-started/index.mdx new file mode 100644 index 0000000..a3fdfca --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/index.mdx @@ -0,0 +1,20 @@ +--- +pagination_prev: null +--- + +# Getting started with account-based reconciliation + +Throughout this tutorial, we will guide you through the process of setting up an account-based reconciliation configuration and generating a reconciliation report. + +To do so, we will use +1. [Formance Payments](../../../payments/index.mdx) to simulate transactions within a payment service provider (PSP) +2. [Formance Ledger](../../../ledger/index.mdx) to model the money flows within your system +3. [Formance Reconciliation](../../../reconciliation.mdx) to reconcile the transactions between the PSP and the Ledger and generate a reconciliation report. + +The reconciliation process is about comparing the balances of a set of accounts in the Formance Ledger with the balances of another set of accounts in an external financial institution and making sure that they match. External financial institutions are integrated with Formance using Formance Payments which removes the need for you to manage the integration yourself. + +The first step is to feed Formance Payments with dummy data. We will do so in the next section. + +:::warning +Before getting started, make sure you have a Formance stack with the Reconciliation service enabled. If you don't have one, please [contact the Formance team](https://www.formance.com/contact). +::: \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/setup_generic_connector.mdx b/docs/reconciliation/tutorials/account-based-getting-started/setup_generic_connector.mdx new file mode 100644 index 0000000..47a5e2f --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/setup_generic_connector.mdx @@ -0,0 +1,70 @@ +--- +sidebar_label: "Setup the Generic Connector" +sidebar_position: 1 +--- + +# Setup the Formance Payments Generic Connector + +Formance Payments is a service that allows you to connect to multiple payment service providers (PSPs), ingest their data and expose this data in a unified format, so that you can effectively use it within the platform. + +To integrate heterogeneous PSPs, Formance Payments relies on a set of connectors. These connectors are responsible for fetching data from the PSPs, normalizing it and exposing it in a unified format. + +In this tutorial, we will guide you through the process of setting up the Generic Connector, which is a connector that allows you to ingest data from any PSP that is not supported natively. We will use it to ingest dummy fixed data that we will use in the reconciliation process. + +:::note +Before getting started, make sure you have a Formance stack with the Reconciliation service enabled. If you don't have one, please [contact the Formance team](https://www.formance.com/contact). +::: + +### Login to your Formance stack + +Run the following command to login to your Formance stack: + +```bash +fctl login +``` + +You should see something similar to: + +```bash +Link : https://app.staging.formance.cloud/api/device?user_code=****-**** + SUCCESS Logged! +``` + +### Create the generic connector configuration file + +Create a file called `generic_connector_config.json` and paste the following content. + +```json +{ + "name": "generic", + "apiKey": "", + "endpoint": "", + "pollingPeriod": "2m" +} +``` + +### Install the generic connector + +Run the following command to install the Generic Connector: + +```bash +fctl payments connectors install generic generic_connector_config.json +``` + +You should see something similar to: + +```bash +[TODO] +``` + +### Check that Formance payments has been successfully fed with dummy data + +Open the Formance console by running the following command: + +```bash +fctl ui +``` + +Navigate to the `Apps` located in the sidebar. You should see the Generic Connector we just installed is active. + +**Insert screenshot here** \ No newline at end of file diff --git a/docs/reconciliation/tutorials/account-based-getting-started/setup_ledger.mdx b/docs/reconciliation/tutorials/account-based-getting-started/setup_ledger.mdx new file mode 100644 index 0000000..b6c447c --- /dev/null +++ b/docs/reconciliation/tutorials/account-based-getting-started/setup_ledger.mdx @@ -0,0 +1,6 @@ +--- +sidebar_label: "Setup Ledger" +sidebar_position: 1 +--- + +# Fill the Ledger with some transactions \ No newline at end of file diff --git a/docs/reconciliation/tutorials/index.mdx b/docs/reconciliation/tutorials/index.mdx new file mode 100644 index 0000000..a6095fd --- /dev/null +++ b/docs/reconciliation/tutorials/index.mdx @@ -0,0 +1,15 @@ +--- +pagination_prev: null +pagination_next: null +--- + +import {DocCardList} from '@site/src/components/DocCard'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +# Getting started with reconciliation + +This section provides step-by-step guides to help you get started with reconciliation. Pick a tutorial below to get started. + +If you need more details about **account-based reconciliation** vs **transaction-based reconciliation**, check out the [reconciliation explanation page](../explanation/what_is_reconciliation.mdx). + + \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index df5cb6b..0d50a03 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -444,7 +444,17 @@ const sidebars = { ], } ], - }, + }, { + label: 'Reconciliation', + type: 'category', + collapsible: true, + collapsed: true, + link: { type: 'doc', id: 'reconciliation' }, + items: [{ + type: 'autogenerated', + dirName: 'reconciliation', + }] + } ], }, {