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:

bash

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:

bash

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:

bash

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:

bash

fctl stack show --name=playground

Look for the URL pattern: https://xxxxxxxxxx-xxxx.sandbox.formance.cloud

You 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:

bash

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:

json

{
  "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:

typescript


// 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:

bash

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

Expected output:

✅ Transaction created!
Transaction ID: 2

Verify Your Transaction#

Check that the transaction was recorded using the CLI:

bash

fctl ledger transactions list --ledger=quickstart

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

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.

{ "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": "..." } }

// 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);

Verify Your Transaction#

Check that the transaction was recorded using the CLI:

bash

fctl ledger transactions list --ledger=quickstart

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