Introduction

Welcome to the Formance Platform API reference documentation. This comprehensive guide provides detailed information about all available endpoints, request/response formats, and examples to help you integrate with the Formance Platform.

Before You Begin

The API reference includes an interactive playground that allows you to test endpoints directly from the documentation. There are two ways to use the playground:

Local proxy with fctl - Use the fctl command-line tool to create a local proxy
Direct API calls - Authenticate directly with the Formance Cloud API

Choose the method that best fits your workflow. The fctl proxy method is often easier for development and testing as it eliminates the need for bearer token management.

Using the API Playground

fctl Proxy (Recommended)
Direct API Authentication

Using fctl Stack Proxy

The easiest way to use the API playground is through the fctl stack proxy command, which creates a local proxy server and handles authentication automatically.

Install fctl

If you haven’t already, install the Formance CLI (fctl) and either log into or create your Formance Cloud account.

Get Organization and Stack Information

You’ll need your organization ID and stack ID to start the proxy server. This information is accessible through the Formance portal at portal.formance.cloud.You can also use the fctl command-line tool to list your organizations, stacks, and regions:

# List all organizations
fctl cloud organizations list

# List stacks for a specific organization
fctl stack list --organization organizationId

Start the proxy server

Run the following command with your organization and stack IDs:

fctl stack proxy --organization=YOUR_ORG_ID --stack=YOUR_STACK_ID --allowed-origins="https://docs.formance.com"

For example:

fctl stack proxy --organization=jdxmvkvwlyib --stack=ycyb --allowed-origins="https://docs.formance.com"

The proxy server will start and you’ll see confirmation that it’s running on localhost.

Test endpoints

With the proxy running, you can now test endpoints from your browser, or from the playground.

https://localhost/api/ledger/_info

No bearer token is required when using the fctl proxy method.

Direct API Authentication

For direct API calls without the proxy, you’ll need proper authentication.

Install fctl

If you haven’t already, install the Formance CLI (fctl) and either log into or create your Formance Cloud account.

Get Organization and Stack Information

You’ll need your organization ID and stack ID to construct proper API URLs. This information is accessible through the Formance portal at portal.formance.cloud.You can also use the fctl command-line tool to list your organizations, stacks, and regions:

# List all organizations
fctl cloud organizations list

# List stacks for a specific organization
fctl stack list --organization organizationId

# List all regions available for an organization
fctl cloud regions list --organization organizationId

API endpoints follow this pattern:

https://{organization}-{stack}.{environment}.formance.cloud/api/{service}/{endpoint}

The {environment} corresponds to your region (e.g., eu-west-1).For example, with organization ID jdxmvkvwlyic, stack ID ycyb, and region eu-west-1:

https://jdxmvkvwlyic-ycyb.eu-west-1.formance.cloud/api/ledger/_info

Authentication Token

You must generate a valid bearer token to authenticate your API requests. The Formance Platform supports multiple authentication methods including OAuth 2.0 client credentials flow and personal tokens.

Authentication Guide

Learn how to create OAuth clients, generate secrets, and obtain bearer tokens for API authentication.

Overview

Ledger

Payments

Wallets

Auth

Flows

Reconciliation

Webhooks

Before You Begin

Using the API Playground

Using fctl Stack Proxy

Direct API Authentication

Authentication Guide

Overview

Ledger

Payments

Wallets

Auth

Flows

Reconciliation

Webhooks

​Before You Begin

​Using the API Playground

​Using fctl Stack Proxy

​Direct API Authentication

Authentication Guide

Before You Begin

Using the API Playground

Using fctl Stack Proxy

Direct API Authentication