Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Reconciliation documentation #66

Closed
wants to merge 6 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/reconciliation.mdx
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions docs/reconciliation/explanation/_category_.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
position: 3
label: "Explanations"
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
32 changes: 32 additions & 0 deletions docs/reconciliation/explanation/what_is_reconciliation.mdx
Original file line number Diff line number Diff line change
@@ -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.
:::
2 changes: 2 additions & 0 deletions docs/reconciliation/how-to/_category_.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
position: 2
label: "How to"
6 changes: 6 additions & 0 deletions docs/reconciliation/how-to/reconciliation-across-psps.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
sidebar_label: "How to perform reconciliation across multiple PSPs?"
sidebar_position: 1
---

# How to perform reconciliation across multiple PSPs?
2 changes: 2 additions & 0 deletions docs/reconciliation/reference/_category_.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
position: 4
label: "Reference"
6 changes: 6 additions & 0 deletions docs/reconciliation/reference/policies.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
sidebar_label: Policies
sidebar_position: 1
---

This page describes the reconciliation policies that are used to reconcile transactions.
8 changes: 8 additions & 0 deletions docs/reconciliation/reference/reports.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
sidebar_label: "Reports"
sidebar_position: 2
---

# Reports

The page describes the reconciliation reports obtained from applying reconciliation policies.
2 changes: 2 additions & 0 deletions docs/reconciliation/tutorials/_category_.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
position: 1
label: "Tutorials"
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
label: Getting Started with account based reconciliation
position: 1
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
sidebar_label: "Create Cash Pool"
sidebar_position: 3
---

# Create Cash Pool
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
sidebar_label: "Create Reconciliation Policy"
sidebar_position: 4
---

# Create Reconciliation Policy
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
sidebar_label: "Generate Reconciliation Report"
sidebar_position: 5
pagination_next: null
---

# Generate Reconciliation Report
Original file line number Diff line number Diff line change
@@ -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).
:::
Original file line number Diff line number Diff line change
@@ -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": "<apiKey>",
"endpoint": "<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**
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
sidebar_label: "Setup Ledger"
sidebar_position: 1
---

# Fill the Ledger with some transactions
15 changes: 15 additions & 0 deletions docs/reconciliation/tutorials/index.mdx
Original file line number Diff line number Diff line change
@@ -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).

<DocCardList items={useCurrentSidebarCategory().items}/>
12 changes: 11 additions & 1 deletion sidebars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -444,7 +444,17 @@ const sidebars = {
],
}
],
},
}, {
label: 'Reconciliation',
type: 'category',
collapsible: true,
collapsed: true,
link: { type: 'doc', id: 'reconciliation' },
items: [{
type: 'autogenerated',
dirName: 'reconciliation',
}]
}
],
},
{
Expand Down