Formance

https://docs.formance.com/
Admin
Formance is an open-source, cloud-native financial infrastructure platform designed to help...
Tokens:219,195
Snippets:3,255
Trust Score:8.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### View Connector Installation Output

Source: https://docs.formance.com/modules/payments/connectors/generic/getting-started

Example of the successful installation confirmation message returned by the CLI.

```text
You are about to install connector 'generic'.
Do you want to continue [Y/n]y
 SUCCESS  generic: connector 'eyJQcm92aWRlciI6IkdFTkVSSUMiLCJSZWZlcmVuY2UiOiI2NzI5YjI5NS00MGZmLTQzOWQtOTU1NS1mNTYwN2M2MzAzODUifQ' installed!
```

--------------------------------

### Install the Formance CLI

Source: https://docs.formance.com/getting-started/quickstart?deployment=cloud&license=ee

Install the fctl command-line tool using Homebrew.

```bash
brew install formancehq/tap/fctl
```

--------------------------------

### Install Qonto Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/qonto?deployment=cloud&license=ee

Commands to install the Qonto connector using different tools.

```bash
fctl payments connectors install qonto config.json
```

```http
POST/api/payments/v3/connectors/install/qonto
```

--------------------------------

### Install Wise Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/wise

Install the Wise connector using the fctl CLI tool.

```bash
fctl payments connectors install wise config.json
```

--------------------------------

### Install the Generic Connector

Source: https://docs.formance.com/modules/payments/connectors/generic/getting-started

Use the fctl CLI to install the connector using the previously created configuration file.

```bash
fctl payments connectors install generic generic-connector.json
```

--------------------------------

### Install Routable Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/psp/routable

Use the fctl CLI to install the Routable connector using a configuration file.

```bash
fctl payments connectors install routable config.json
```

--------------------------------

### Install Currencycloud Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/currencycloud

Use the fctl CLI to install the Currencycloud connector with a configuration file.

```bash
fctl payments connectors install currencycloud config.json
```

--------------------------------

### Comprehensive Metadata Example

Source: https://docs.formance.com/modules/numscript/reference/metadata

A complete example showing variable initialization, metadata reading, and metadata writing.

```numscript
#![feature("experimental-mid-script-function-call")]
vars {
  account $order
  account $merchant = meta($order, "merchant")
  monetary $fee
  portion $commission
  string $ref
}

send $fee (
  source = @orders:1234
  destination = @platform:fees
)

send [USD/2 *] (
  source = @orders:1234
  destination = {
    $commission to @platform:fees
    remaining to $merchant
  }
)

set_account_meta($order, "reference", $ref)
set_tx_meta("order_fee", $fee)
set_tx_meta("tax", 20/100)
set_tx_meta("commission", $commission)
```

```json
{
  "script": {
    "vars": {
      "order": "orders:186HH78UH",
      "fee": {
        "amount": 1000,
        "asset": "USD/2"
      },
      "commission": "15.5%",
      "reference": "108IUYGI"
    }
  }
}
```

--------------------------------

### Install Mangopay Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/mangopay

Use the fctl CLI to install the Mangopay connector using a configuration file.

```bash
fctl payments connectors install mangopay config.json
```

--------------------------------

### Wizard Bootstrap Configuration

Source: https://docs.formance.com/deploy/self-hosted/installation/control-plane

Defines initial users, organizations, regions, and stacks in the values file to automate setup on first install.

```yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        staticPasswords:
          - email: "admin@example.com"
            hash: "$2a$10$..."  # bcrypt hash of password
            username: "admin"
            userID: "unique-uuid"
            role: ADMIN
    config:
      wizard:
        setup: |
          users:
            - id: "unique-uuid"
              email: "admin@example.com"
              role: "ADMIN"
          organizations:
            - id: "my-org"
              ownerId: "unique-uuid"
              name: "My Organization"
          regions:
            - id: "region-1"
              name: "production"
              organizationId: "my-org"
              baseUrl: "https://formance.example.com"
          stacks:
            - id: "main"
              name: "main"
              organizationId: "my-org"
              regionId: "region-1"
              version: "v3.1"
```

--------------------------------

### Verify CLI Installation

Source: https://docs.formance.com/getting-started/quickstart?deployment=cloud&license=ee

Check the installed version of the Formance CLI.

```bash
fctl version
```

--------------------------------

### Install Qonto Connector via fctl

Source: https://docs.formance.com/modules/payments/connectors/psp/qonto

Use the fctl CLI tool to install the Qonto connector using a configuration file.

```bash
fctl payments connectors install qonto config.json
```

--------------------------------

### Install Wise Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/wise?deployment=cloud&license=ee

Commands to install the Wise connector using different CLI tools.

```fctl
fctl payments connectors install wise config.json
```

```curl
POST/api/payments/v3/connectors/install/wise
```

--------------------------------

### Install Fireblocks Connector

Source: https://docs.formance.com/modules/payments/connectors/exchange/fireblocks

Use the fctl CLI to install the Fireblocks connector using a configuration file.

```bash
fctl payments connectors install fireblocks config.json
```

--------------------------------

### Account Address Pattern Examples

Source: https://docs.formance.com/modules/ledger/core-concepts/accounts

Examples demonstrating the hierarchical structure of account addresses.

```text
users — a single segment
users:001:main — a multi-level address with : as separator
```

--------------------------------

### Install Increase Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/psp/increase?deployment=cloud&license=ee

Commands to install the Increase connector using different CLI tools.

```fctl
fctl payments connectors install increase config.json
```

```curl
POST/api/payments/v3/connectors/install/increase
```

--------------------------------

### Install Routable Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/psp/routable?deployment=cloud&license=ee

Commands to install the Routable connector using various CLI tools.

```bash
fctl payments connectors install routable config.json
```

```http
POST/api/payments/v3/connectors/install/routable
```

--------------------------------

### Install Kraken Pro Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/exchange/krakenpro

Commands to install the Kraken Pro connector using the CLI or HTTP API.

```bash
fctl payments connectors install krakenpro config.json
```

```http
POST/api/payments/v3/connectors/install/krakenpro
```

--------------------------------

### Install Powens Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/open-banking/powens

Commands to install the Powens connector using the Formance CLI, cURL, or HTTPie.

```bash
fctl payments connectors install powens config.json
```

```http
POST/api/payments/v3/connectors/install/powens
```

--------------------------------

### Install Column Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/column?deployment=cloud&license=ee

Commands to install the Column connector using different CLI tools.

```fctl
fctl payments connectors install column config.json
```

```curl
POST/api/payments/v3/connectors/install/column
```

--------------------------------

### Install Modulr Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/modulr

Use the fctl CLI to install the Modulr connector using a configuration file.

```bash
fctl payments connectors install modulr config.json
```

--------------------------------

### Install Tink Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/open-banking/tink?deployment=cloud&license=ee

Commands to install the Tink connector using different CLI tools.

```fctl
fctl payments connectors install tink config.json
```

```curl
POST/api/payments/v3/connectors/install/tink
```

--------------------------------

### Install Moneycorp Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/moneycorp

Use the fctl CLI to install the Moneycorp connector using a configuration file.

```bash
fctl payments connectors install moneycorp config.json
```

--------------------------------

### Install Plaid connector via fctl

Source: https://docs.formance.com/v3.2/modules/payments/connectors/open-banking/plaid?deployment=cloud&license=ee

Use the Formance CLI to install the Plaid connector using a configuration file.

```bash
fctl payments connectors install plaid config.json
```

--------------------------------

### Install Coinbase Prime Connector

Source: https://docs.formance.com/modules/payments/connectors/exchange/coinbaseprime?deployment=cloud&license=ee

Use the fctl CLI to install the Coinbase Prime connector using a configuration file.

```bash
fctl payments connectors install coinbaseprime config.json
```

--------------------------------

### Install Banking Circle Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/bankingcircle

Use the fctl CLI to install the Banking Circle connector using a configuration file.

```bash
fctl payments connectors install bankingcircle config.json
```

--------------------------------

### Install Numscript CLI

Source: https://docs.formance.com/modules/numscript/cli

Installation methods for the Numscript CLI using curl or the Go toolchain.

```bash
curl -sSf https://raw.githubusercontent.com/formancehq/numscript/main/install.sh | bash
```

```bash
go install github.com/formancehq/numscript/cmd/numscript@latest
```

--------------------------------

### Install Qonto Connector via HTTP API

Source: https://docs.formance.com/modules/payments/connectors/psp/qonto

Install the Qonto connector by sending a POST request to the Formance Payments API.

```http
POST/api/payments/v3/connectors/install/qonto
```

--------------------------------

### Install Adyen Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/adyen

Use the fctl CLI or the HTTP API to install the Adyen connector with a configuration file.

```bash
fctl payments connectors install adyen config.json
```

```http
POST/api/payments/v3/connectors/install/adyen
```

--------------------------------

### Install Banking Bridge Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/psp/bankingbridge

Commands to install the Banking Bridge connector using the Formance CLI or HTTP API.

```bash
fctl payments connectors install bankingbridge config.json
```

```http
POST/api/payments/v3/connectors/install/bankingbridge
```

--------------------------------

### Install Column Connector via fctl

Source: https://docs.formance.com/modules/payments/connectors/psp/column

Use the fctl CLI tool to install the Column connector using a configuration file.

```bash
fctl payments connectors install column config.json
```

--------------------------------

### Install Formance with Bundled CRDs

Source: https://docs.formance.com/deploy/self-hosted/installation/operator-setup

Install the unified Formance chart while enabling the bundled CRD subchart via Helm flags.

```bash
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set regions.operator.operator-crds.create=true
```

--------------------------------

### Install Atlar connector via fctl

Source: https://docs.formance.com/modules/payments/connectors/psp/atlar

Use the fctl CLI tool to install the Atlar connector using a configuration file.

```bash
fctl payments connectors install atlar config.json
```

--------------------------------

### Initialize Project Dependencies

Source: https://docs.formance.com/getting-started/connect-app

Set up a new Node.js project and install the required Formance SDK and development tools.

```bash
mkdir formance-demo && cd formance-demo
npm init -y
npm install @formance/formance-sdk typescript tsx @types/node --save
```

--------------------------------

### Create a wallet using CLI tools

Source: https://docs.formance.com/modules/wallets/creating

Use the fctl command to initialize a new wallet in your system.

```bash
fctl wallets create my-wallet
```

--------------------------------

### GET v3/api/payments/v3/tasks/{taskID}

Source: https://docs.formance.com/stack-api-reference

Get details of a specific task.

```APIDOC
## GET v3/api/payments/v3/tasks/{taskID}

### Description
Get details of a specific task.

### Method
GET

### Endpoint
v3/api/payments/v3/tasks/{taskID}

### Parameters
#### Path Parameters
- **taskID** (string) - Required - The unique identifier of the task.
```

--------------------------------

### GET /api/membership/organizations/{organizationId}/regions/{regionID}

Source: https://docs.formance.com/membership-api

Get region.

```APIDOC
## GET /api/membership/organizations/{organizationId}/regions/{regionID}

### Description
Get region.

### Method
GET

### Endpoint
/api/membership/organizations/{organizationId}/regions/{regionID}
```

--------------------------------

### GET /api/membership/organizations/{organizationId}/regions/{regionID}/versions

Source: https://docs.formance.com/membership-api

Get region versions.

```APIDOC
## GET /api/membership/organizations/{organizationId}/regions/{regionID}/versions

### Description
Get region versions.

### Method
GET

### Endpoint
/api/membership/organizations/{organizationId}/regions/{regionID}/versions
```

--------------------------------

### Configure MCP client

Source: https://docs.formance.com/v3.2/mcp

Example configuration for an MCP client to launch the Formance MCP server.

```json
{
  "mcpServers": {
    "formance": {
      "command": "fctl",
      "args": [
        "--organization=YOUR_ORGANIZATION_ID",
        "--stack=YOUR_STACK_ID",
        "stack",
        "mcp",
        "serve",
        "--transport=stdio"
      ]
    }
  }
}
```

--------------------------------

### Install Bitstamp Connector

Source: https://docs.formance.com/v3.2/modules/payments/connectors/exchange/bitstamp?deployment=cloud&license=ee

Commands to install the Bitstamp connector using various tools.

```fctl
fctl payments connectors install bitstamp config.json
```

```curl
POST/api/payments/v3/connectors/install/bitstamp
```

--------------------------------

### Create ledger with default settings

Source: https://docs.formance.com/v3.2/modules/ledger/working-with/data-isolation-buckets?deployment=cloud&license=ee

Initialize a ledger using default feature configurations.

```curl
curl -X POST $FORMANCE_API_URL/api/ledger/v2/my-ledger
```

--------------------------------

### Install Formance with Minimal Profile

Source: https://docs.formance.com/deploy/self-hosted/demo/quick-start

Deploys the Formance Helm chart using the minimal configuration profile.

```bash
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  -f https://raw.githubusercontent.com/formancehq/helm/formance-1.10.0/charts/formance/profiles/ce-minimal.yaml
```

--------------------------------

### Account Address Examples

Source: https://docs.formance.com/modules/ledger/core-concepts/accounts?deployment=cloud&license=ee

Examples of well-structured and poorly-structured account addresses for ledger organization.

```text
users:usr-123:wallet
payments:stripe:ch_abc456
merchants:acme-corp:earnings
```

```text
users:john@example.com         ← email could change
orders:pending:ord-789         ← "pending" is mutable state
merchants:Acme Corp:main       ← spaces aren't allowed, name could change
```

--------------------------------

### Filter Syntax Example

Source: https://docs.formance.com/modules/flows/triggers

Example of an expr-lang expression used to filter payment events.

```text
event.type == "PAY-IN" && event.provider == "PROVIDERID" && hasPrefix(event.rawData.merchantReference, "test") == true
```

--------------------------------

### Create a wallet with metadata

Source: https://docs.formance.com/modules/wallets/creating

Attach custom key-value pairs to a wallet during creation to link it to external system resources.

```bash
fctl wallets create user-wallet --metadata user_id=1234
```

--------------------------------

### Implement FetchNextAccounts in Plugin

Source: https://docs.formance.com/modules/payments/connectors/build-connector

Initial entry point for fetching accounts, checking for client installation before delegating to the internal fetcher.

```go
func (p *Plugin) FetchNextAccounts(ctx context.Context, req models.FetchNextAccountsRequest) (models.FetchNextAccountsResponse, error) {
    if p.client == nil {
        return models.FetchNextAccountsResponse{}, plugins.ErrNotYetInstalled
    }
    return p.fetchNextAccounts(ctx, req)
}
```

--------------------------------

### Implement Plugin Entry Point and Registration

Source: https://docs.formance.com/modules/payments/connectors/build-connector

The plugin entry point uses init() to register with the system and defines the Plugin struct and constructor.

```go
const ProviderName = "stripe"

func init() {
    registry.RegisterPlugin(
        ProviderName,
        models.PluginTypePSP,
        func(_ models.ConnectorID, name string, logger logging.Logger, rm json.RawMessage) (models.Plugin, error) {
            return New(name, logger, rm, nil)
        },
        capabilities,
        Config{},
        PAGE_SIZE,
    )
}

type Plugin struct {
    models.Plugin                // embed the base for the zero-impl methods
    name   string
    logger logging.Logger
    client client.Client
    config Config
}

func New(name string, logger logging.Logger, rawConfig json.RawMessage, backend stripe.Backend) (*Plugin, error) {
    config, err := unmarshalAndValidateConfig(rawConfig)
    if err != nil { return nil, err }

    c, err := client.New(ProviderName, logger, backend, config.APIKey)
    if err != nil { return nil, err }

    return &Plugin{
        Plugin: plugins.NewBasePlugin(),
        name:   name, logger: logger, client: c, config: config,
    }, nil
}

func (p *Plugin) Name() string { return p.name }
func (p *Plugin) Config() models.PluginInternalConfig { return p.config }

func (p *Plugin) Install(_ context.Context, _ models.InstallRequest) (models.InstallResponse, error) {
    return models.InstallResponse{Workflow: workflow()}, nil
}
```

--------------------------------

### Install Modulr Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/modulr?deployment=cloud&license=ee

Commands to install the Modulr connector using different CLI tools.

```fctl
fctl payments connectors install modulr config.json
```

```curl
POST/api/payments/v3/connectors/install/modulr
```

--------------------------------

### Open Formance Console

Source: https://docs.formance.com/modules/payments/connectors/generic/getting-started

Launch the Formance UI to inspect synchronized payment data.

```bash
fctl ui
```

--------------------------------

### View authentication provider help

Source: https://docs.formance.com/manage/identity/sso

Access the help documentation for the authentication provider configuration command.

```bash
fctl cloud organizations authentication-provider configure -h
```

--------------------------------

### Install Minimal Enterprise Edition

Source: https://docs.formance.com/deploy/self-hosted/installation/operator-setup

Deploys the Formance platform with a minimal configuration profile using a remote values file.

```bash
helm upgrade --install formance oci://ghcr.io/formancehq/helm/formance \
  --version 1.10.0 \
  --namespace formance-system \
  --create-namespace \
  --set tags.EntrepriseEdition=true \
  --set global.licence.clusterID=$CLUSTER_ID \
  --set global.licence.token=$LICENCE_TOKEN \
  -f https://raw.githubusercontent.com/formancehq/helm/main/charts/formance/profiles/ee-minimal.yaml
```

--------------------------------

### Account Address Examples

Source: https://docs.formance.com/modules/ledger/core-concepts/accounts

Examples of well-structured account addresses using colon-separated segments for hierarchy.

```text
users:usr-123:wallet
payments:stripe:ch_abc456
merchants:acme-corp:earnings
```

--------------------------------

### POST /api/payments/v3/connectors/install/qonto

Source: https://docs.formance.com/modules/payments/connectors/psp/qonto

Installs and configures a new Qonto connector instance to begin syncing data from a Qonto organization.

```APIDOC
## POST /api/payments/v3/connectors/install/qonto

### Description
Installs a Qonto connector to sync read-only business accounts, balances, beneficiaries, and transactions from a Qonto organization.

### Method
POST

### Endpoint
/api/payments/v3/connectors/install/qonto

### Parameters
#### Request Body
- **apiKey** (string) - Required - The Qonto API key.
- **clientID** (string) - Required - The Qonto client ID.
- **endpoint** (string) - Required - The Qonto API endpoint (e.g., https://thirdparty.qonto.com).
- **pageSize** (integer) - Optional - Number of items per page (default: 25).
- **pollingPeriod** (string) - Optional - Frequency of polling (default: 30m).
- **stagingToken** (string) - Optional - Token required for staging environments.
```

--------------------------------

### Create a Ledger

Source: https://docs.formance.com/modules/ledger/quick-start?deployment=cloud&license=ee

Initializes a new ledger instance named 'main'.

```bash
fctl ledger create main
```

--------------------------------

### Verify Installation

Source: https://docs.formance.com/deploy/self-hosted/demo/quick-start

Commands to check the status of pods and stacks in the cluster.

```bash
kubectl get pods -n formance-system
```

```bash
kubectl get stacks
```

```bash
kubectl get pods --all-namespaces -l formance.com/stack
```

--------------------------------

### Dynamic pool query examples

Source: https://docs.formance.com/v3.2/modules/payments/cash-pools

Examples of JSON query structures for defining dynamic pool membership.

```json
{
  "name": "EUR Accounts",
  "query": "{\"$match\": {\"default_asset\": \"EUR\"}}"
}
```

```json
{
  "name": "Stripe Pool",
  "query": "{\"$match\": {\"connector_id\": \"stripe:connector-123\"}}"
}
```

```json
{
  "name": "Business Accounts",
  "query": "{\"$match\": {\"type\": \"INTERNAL\", \"metadata.category\": \"business\"}}"
}
```

--------------------------------

### Numscript Test Case Example

Source: https://docs.formance.com/modules/numscript/specs?deployment=cloud&license=ee

A JSON specification file testing the behavior of the provided Numscript example.

```json
{
  "$schema": "https://raw.githubusercontent.com/formancehq/numscript/refs/heads/main/v1.specs.schema.json",
  "variables": {
    "source": "alice",
    "destination": "bob"
  },
  "balances": [
    { "account": "alice", "asset": "EUR/2", "amount": 500 }
  ],
  "testCases": [
    {
      "it": "sends all the available balance when it doesn't exceed the cap and @alice has enough balance",
      "variables": {
        "cap": "EUR/2 9999"
      },
      "expect.postings": [
        {
          "source": "alice",
          "destination": "bob",
          "amount": 500,
          "asset": "EUR/2"
        }
      ]
    },
    {
      "it": "caps the sent amt to $cap when lower than available balance",
      "variables": {
        "cap": "EUR/2 10"
      },
      "expect.postings": [
        {
          "source": "alice",
          "destination": "bob",
          "amount": 10,
          "asset": "EUR/2"
        }
      ]
    }
  ]
}
```

--------------------------------

### Define wizard configuration

Source: https://docs.formance.com/deploy/self-hosted/installation/control-plane

Example YAML structure for idempotent resource provisioning during the bootstrap process.

```yaml
# wizard.yaml
wizard:
  users:
    - id: "admin-uuid"
      email: "admin@your-company.com"
      role: "ADMIN"
  organizations:
    - id: "my-org"
      ownerId: "admin-uuid"
      name: "My Company"
      # Built-in policy ID applied to users who join the org without an explicit
      # policy assignment. 10 = OrganizationAdminStackAdmin, 8 = OrganizationAdmin,
      # 4 = OrganizationGuest, etc. See "Built-in policies" in /manage/identity/rbac.
      defaultPolicyId: 10
  regions:
    - id: "region-1"
      name: "default"
      baseUrl: "https://formance.your-domain.com"
      organizationId: "my-org"
  stacks:
    - id: "production"
      name: "production"
      organizationId: "my-org"
      regionId: "region-1"
      version: "v3.1"
      modules: ["Auth", "Ledger", "Gateway"]
```

--------------------------------

### Expected Pod Output

Source: https://docs.formance.com/deploy/self-hosted/installation/operator-setup

Example output showing the expected running state of Formance components.

```text
NAME                                    READY   STATUS    RESTARTS   AGE
formance-operator-xxxxx-xxxxx           1/1     Running   0          2m
membership-xxxxx-xxxxx                  1/1     Running   0          2m
console-v3-xxxxx-xxxxx                  1/1     Running   0          2m
membership-dex-xxxxx-xxxxx              1/1     Running   0          2m
postgresql-0                            1/1     Running   0          2m
```

--------------------------------

### JSON Payment Response Example

Source: https://docs.formance.com/modules/numscript/monetary-notation?deployment=cloud&license=ee

An example of an ambiguous monetary representation often received from payment processors.

```json
{
  "amount": 100,
  "currency": "USD"
}
```

--------------------------------

### Install Stripe Connector

Source: https://docs.formance.com/modules/payments/connectors/psp/stripe?deployment=cloud&license=ee

Commands to install the Stripe connector using different CLI tools or API requests.

```bash
fctl payments connectors install stripe config.json
```

```http
POST/api/payments/v3/connectors/install/stripe
```
Tokens:
Raw