Connect Your App - Formance Documentation

This guide shows you how to send transactions programmatically using the Formance SDK. By the end, you’ll have a working script that creates a transaction via the API.

Prerequisite: Complete the Platform Quick Start first. You need a running sandbox.

Generate API Credentials

Create OAuth client credentials to authenticate your application.First, get your stack ID:

fctl stack show --name=playground

Look for the ID field in the output:

# Information
ID               | ecwj       |   ← This is your stack ID
Name             | playground |
Region           | eu-sandbox |
Status           | ACTIVE     |

Create the client using your stack ID:

fctl auth clients create my-app --stack <STACK_ID>

You’ll see output like:

ID   | 6a936dfe-xxxx-yyyy-zzzz-9019a1e9b9e3
Name | my-app

Copy the ID — this is your Client ID.Now create a secret for this client:

fctl auth clients secrets create <CLIENT_ID> app-secret --stack <STACK_ID>

Replace <CLIENT_ID> with the ID from above. You’ll see:

ID    | 3bddd5f6-xxxx-yyyy-zzzz-e8cd839c9d79
Name  | app-secret
Clear | 20bd58c4-xxxx-yyyy-zzzz-dc05258bc959

Copy the Clear value immediately — this is your Client Secret and it’s only shown once!

Finally, get your API endpoint:

fctl stack show --name=playground

Look for the URL pattern: https://xxxxxxxxxx-xxxx.sandbox.formance.cloudYou now have everything you need:

Client ID — from the first command
Client Secret — the “Clear” value from the second command
API URL — from fctl stack show

Install the SDK & Send a Transaction

Create a new project:

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

Open package.json and add "type": "module" after the "name" line:

{
  "name": "formance-demo",
  "type": "module",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "@formance/formance-sdk": "...",
    "@types/node": "...",
    "tsx": "...",
    "typescript": "..."
  }
}

Create index.ts:

import { SDK as Formance } from "@formance/formance-sdk";

// Replace with your actual values from Step 1
const formance = new Formance({
  serverURL: "https://xxxxxxxxxx-xxxx.sandbox.formance.cloud", // Your stack URL
  security: {
    clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",     // From: fctl auth client create
    clientSecret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // From: fctl auth client secrets create
  },
});

async function main() {
  // Create a transaction: send $1.00 from 'world' to 'alice'
  const result = await formance.ledger.v2.createTransaction({
    ledger: "quickstart",
    v2PostTransaction: {
      postings: [
        {
          amount: BigInt(100), // 100 = $1.00 (USD/2 has 2 decimal places)
          asset: "USD/2",
          source: "world",
          destination: "alice",
        },
      ],
      metadata: {
        order_id: "ORD-12345",
        description: "First SDK transaction",
      },
    },
  });

  console.log("✅ Transaction created!");
  console.log("Transaction ID:", result.v2CreateTransactionResponse?.data.id);
}

main().catch(console.error);

Run it:

npx tsx index.ts

Getting an authentication error? Check these common issues:

Make sure your serverURL has no trailing slash
Verify you created the client with the correct --stack flag
Confirm your sandbox is still active with fctl stack show --name=playground

Create a new project:

mkdir formance-demo && cd formance-demo
go mod init formance-demo
go get github.com/formancehq/formance-sdk-go/v3

Create main.go:

package main

import (
	"context"
	"fmt"
	"log"
	"math/big"

	formancesdkgo "github.com/formancehq/formance-sdk-go/v3"
	"github.com/formancehq/formance-sdk-go/v3/pkg/models/operations"
	"github.com/formancehq/formance-sdk-go/v3/pkg/models/shared"
)

func main() {
	// Replace with your credentials from Step 1
	client := formancesdkgo.New(
		formancesdkgo.WithServerURL("https://xxxxxxxxxx-xxxx.sandbox.formance.cloud"),
		formancesdkgo.WithSecurity(shared.Security{
			ClientID:     formancesdkgo.String("your-client-id"),
			ClientSecret: formancesdkgo.String("your-client-secret"),
		}),
	)

	ctx := context.Background()

	// Create a transaction: send $1.00 from 'world' to 'alice'
	res, err := client.Ledger.V2.CreateTransaction(ctx, operations.V2CreateTransactionRequest{
		Ledger: "quickstart",
		V2PostTransaction: shared.V2PostTransaction{
			Postings: []shared.V2Posting{
				{
					Amount:      big.NewInt(100), // 100 = $1.00 (USD/2 has 2 decimal places)
					Asset:       "USD/2",
					Source:      "world",
					Destination: "alice",
				},
			},
			Metadata: map[string]string{
				"order_id":    "ORD-12345",
				"description": "First SDK transaction",
			},
		},
	})

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("✅ Transaction created!")
	fmt.Println("Transaction ID:", res.V2CreateTransactionResponse.Data.ID)
}

Run it:

go run main.go

Install the SDK:

pip3 install formance-sdk-python

Create a new directory and file:

mkdir formance-demo && cd formance-demo

Create main.py:

from formance_sdk_python import SDK
from formance_sdk_python.models import shared, operations

# Replace with your credentials from Step 1
sdk = SDK(
    server_url="https://xxxxxxxxxx-xxxx.sandbox.formance.cloud",
    security=shared.Security(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

# Create a transaction: send $1.00 from 'world' to 'alice'
result = sdk.ledger.v2.create_transaction(
    request=operations.V2CreateTransactionRequest(
        ledger="quickstart",
        v2_post_transaction=shared.V2PostTransaction(
            postings=[
                shared.V2Posting(
                    amount=100,  # 100 = $1.00 (USD/2 has 2 decimal places)
                    asset="USD/2",
                    source="world",
                    destination="alice",
                )
            ],
            metadata={
                "order_id": "ORD-12345",
                "description": "First SDK transaction",
            },
        ),
    )
)

print("✅ Transaction created!")
print(f"Transaction ID: {result.v2_create_transaction_response.data.id}")

Run it:

python main.py

Create a new project with Gradle:

mkdir formance-demo && cd formance-demo
gradle init --type java-application

Add the dependency to build.gradle:

dependencies {
    implementation 'com.formance:formance-sdk:+'
}

Create src/main/java/App.java:

package formance.demo;

import com.formance.formance_sdk.SDK;
import com.formance.formance_sdk.models.operations.V2CreateTransactionRequest;
import com.formance.formance_sdk.models.shared.*;
import java.math.BigInteger;
import java.util.List;
import java.util.Map;

public class App {
    public static void main(String[] args) throws Exception {
        // Replace with your credentials from Step 1
        SDK sdk = SDK.builder()
            .serverURL("https://xxxxxxxxxx-xxxx.sandbox.formance.cloud")
            .security(Security.builder()
                .clientID("your-client-id")
                .clientSecret("your-client-secret")
                .build())
            .build();

        // Create a transaction: send $1.00 from 'world' to 'alice'
        var response = sdk.ledger().v2().createTransaction()
            .request(V2CreateTransactionRequest.builder()
                .ledger("quickstart")
                .v2PostTransaction(V2PostTransaction.builder()
                    .postings(List.of(
                        V2Posting.builder()
                            .amount(BigInteger.valueOf(100)) // 100 = $1.00
                            .asset("USD/2")
                            .source("world")
                            .destination("alice")
                            .build()
                    ))
                    .metadata(Map.of(
                        "order_id", "ORD-12345",
                        "description", "First SDK transaction"
                    ))
                    .build())
                .build())
            .call();

        System.out.println("✅ Transaction created!");
        System.out.println("Transaction ID: " + response.v2CreateTransactionResponse().get().data().id());
    }
}

Run it:

gradle run

Create a new project:

mkdir formance-demo && cd formance-demo
dotnet new console
dotnet add package FormanceSDK

Replace Program.cs:

using System;
using System.Numerics;
using System.Threading.Tasks;
using System.Collections.Generic;
using FormanceSDK;
using FormanceSDK.Models.Components;
using FormanceSDK.Models.Requests;

class Program
{
    static async Task Main(string[] args)
    {
        // Replace with your credentials from Step 1
        var sdk = new Formance(
            serverUrl: "https://xxxxxxxxxx-xxxx.sandbox.formance.cloud",
            security: new Security()
            {
                ClientID = "your-client-id",
                ClientSecret = "your-client-secret"
            }
        );

        // Create a transaction: send $1.00 from 'world' to 'alice'
        var response = await sdk.Ledger.V2.CreateTransactionAsync(
            new V2CreateTransactionRequest()
            {
                Ledger = "quickstart",
                V2PostTransaction = new V2PostTransaction()
                {
                    Postings = new List<V2Posting>
                    {
                        new V2Posting()
                        {
                            Amount = new BigInteger(100), // 100 = $1.00
                            Asset = "USD/2",
                            Source = "world",
                            Destination = "alice"
                        }
                    },
                    Metadata = new Dictionary<string, string>
                    {
                        { "order_id", "ORD-12345" },
                        { "description", "First SDK transaction" }
                    }
                }
            }
        );

        Console.WriteLine("✅ Transaction created!");
        Console.WriteLine($"Transaction ID: {response.V2CreateTransactionResponse?.Data.Id}");
    }
}

Run it:

dotnet run

Create a new project:

mkdir formance-demo && cd formance-demo
composer init --no-interaction
composer require formance/formance-sdk

Create index.php:

<?php

require_once 'vendor/autoload.php';

use Formance\SDK;
use Formance\Models\Shared;
use Formance\Models\Operations;

// Replace with your credentials from Step 1
$sdk = SDK::builder()
    ->setServerURL('https://xxxxxxxxxx-xxxx.sandbox.formance.cloud')
    ->setSecurity(new Shared\Security(
        clientID: 'your-client-id',
        clientSecret: 'your-client-secret',
    ))
    ->build();

// Create a transaction: send $1.00 from 'world' to 'alice'
$response = $sdk->ledger->v2->createTransaction(
    new Operations\V2CreateTransactionRequest(
        ledger: 'quickstart',
        v2PostTransaction: new Shared\V2PostTransaction(
            postings: [
                new Shared\V2Posting(
                    amount: 100, // 100 = $1.00 (USD/2 has 2 decimal places)
                    asset: 'USD/2',
                    source: 'world',
                    destination: 'alice',
                ),
            ],
            metadata: [
                'order_id' => 'ORD-12345',
                'description' => 'First SDK transaction',
            ],
        ),
    )
);

echo "✅ Transaction created!\n";
echo "Transaction ID: " . $response->v2CreateTransactionResponse->data->id . "\n";

Run it:

php index.php

Expected output:

✅ Transaction created!
Transaction ID: 2

Verify Your Transaction

Check that the transaction was recorded using the CLI:

fctl ledger transactions list --ledger=quickstart

You should see both your CLI transaction from the Quick Start and your new SDK transaction.

What’s Next?

Numscript

Write complex, multi-party transactions with Formance’s scripting language.

Ledger Concepts

Understand accounts, balances, and double-entry bookkeeping.

Payments Module

Connect to payment providers like Stripe, Wise, and more.

API Reference

Explore the full Formance API.

Security Note: The client_credentials grant shown here is for server-to-server communication. Never expose these credentials in client-side code. For web/mobile apps, use the authorization code flow.

Getting Started

​Verify Your Transaction

​What’s Next?

Numscript

Ledger Concepts

Payments Module

API Reference

Verify Your Transaction

What’s Next?