A Introduction#

FRAGMENT is a toolkit for building products that move and track money. It includes an API and Dashboard for designing, implementing, and operating your Ledger.

Don't have a FRAGMENT workspace? Get access.

B Design your Ledger#

A Ledger uses a Schema to define functionality for a specific product and use case. A Schema may be shared across multiple Ledgers. Updating a Schema will trigger migrations to update each Ledger. Use the Ledger designer in the Dashboard to model and store your Schema.

Ledgers track money using:

  • Ledger Accounts, balances that represent the financial state of a business
  • Ledger Entries, financial events that update Ledger Accounts

a. Ledger Accounts

#

A Ledger Account has a balance. Changes to a Ledger Account's balance are called Ledger Lines.

There are four types of Ledger Accounts, split into two layers:

State

Assets: what you own
Liabilities: what you owe

Change

Income: what you've earned
Expense: what you've spent

State Ledger Accounts track your product's financial relationships with your bank, payment systems and users. Balance Sheets are a report of State Ledger Account balances.

Change Ledger Accounts track when and how your product makes a profit or loss. They produce Income Statements.

Within a Schema, the chartOfAccounts key contains a nested tree of Ledger Accounts, up to a maximum depth of 10:

Ledger Accounts that share a parent require a unique key, but the same key can be used in different parts of the tree.

For some Ledger Accounts, you must set additional properties:

  • linkedAccount enables reconciliation with an external system
  • template allows multiple instances to be created on demand
  • currencyMode configures the account's currency mode, single or multi
  • consistencyConfig configures the whether the Ledger Account's balances and Ledger Lines are strongly or eventually consistent

b. Ledger Entries

#

A Ledger Entry is a single update to a Ledger. Define a Ledger Entry type in your Schema for every financial event in your product and bank.

A Ledger Entry must be balanced, which means it follows the Accounting Equation:


Assets - Liabilities = Income - Expense

How you balance a Ledger Entry depends upon its net effect to the Ledger's balances.

When the net change to the State Ledger Accounts is zero, the financial event being recorded did not change the net worth of the business. In this example, an increase to an asset account is balanced by an increase in a liability account:

When the net change to the State Ledger Accounts is non-zero, the financial event being recorded made a profit or loss. In this example, a difference in asset and liability accounts is balanced by an increase in an income account.

C Deploy your Ledger#

Once you've designed your Ledger, you can deploy it using the dashboard, the API, or by embedding our CLI in your CI.

a. Dashboard

#

You can edit and store your Schema and create Ledgers directly from the FRAGMENT Dashboard. This is useful during development, but is not recommended for production workflows.

b. API

#

You can call the API to store your Schema and create Ledgers. This is useful if you want to automate your Ledger deployment or have multiple environments which you want to keep in-sync. If you are creating many Schemas and Ledgers, you can also call the storeSchema and createLedger APIs directly from your product.

Call storeSchema to store a Schema. Depending on your use case, you may share one Schema for all your users, or create a Schema per user.

storeSchema query
mutation QuickstartStoreSchema($schema: SchemaInput!) {
  storeSchema(schema: $schema) {
    ... on StoreSchemaResult {
      schema {
        key
        name
        version {
          version
          created
          json
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}
storeSchema variables
{
  "schema": {
    "key": "quickstart-schema",
    "name": "Quickstart Schema",
    "chartOfAccounts": {
      "defaultCurrency": {
        "code": "USD"
      },
      "defaultCurrencyMode": "single",
      "accounts": [
        {
          "key": "assets",
          "type": "asset",
          "children": [
            {
              "key": "banks",
              "children": [
                {
                  "key": "user-cash"
                }
              ]
            }
          ]
        },
        {
          "key": "liabilities",
          "type": "liability",
          "children": [
            {
              "key": "users",
              "template": true,
              "consistencyConfig": {
                "ownBalanceUpdates": "strong"
              },
              "children": [
                {
                  "key": "available"
                },
                {
                  "key": "pending"
                }
              ]
            }
          ]
        },
        {
          "key": "income",
          "type": "income"
        },
        {
          "key": "expense",
          "type": "expense",
          "children": []
        }
      ]
    },
    "ledgerEntries": {
      "types": [
        {
          "type": "user_funds_account",
          "description": "Funding {{user_id}} for {{funding_amount}}.",
          "lines": [
            {
              "account": { "path": "assets/banks/user-cash" },
              "key": "funds_arrive_in_bank",
              "amount": "{{funding_amount}}"
            },
            {
              "account": { "path": "liabilities/users:{{user_id}}/available" },
              "key": "increase_user_balance",
              "amount": "{{funding_amount}}"
            }
          ]
        },
        {
          "type": "p2p_transfer",
          "description": "P2P of {{transfer_amount}} from {{from_user_id}} to {{to_user_id}}.",
          "lines": [
            {
              "account": {
                "path": "liabilities/users:{{from_user_id}}/available"
              },
              "key": "decrease_from_user",
              "amount": "-{{transfer_amount}}"
            },
            {
              "account": { "path": "liabilities/users:{{to_user_id}}/available" },
              "key": "increase_to_user",
              "amount": "{{transfer_amount}}"
            }
          ],
          "conditions": [
            {
              "account": {
                "path": "liabilities/users:{{from_user_id}}/available"
              },
              "postcondition": {
                "ownBalance": {
                  "gte": "0"
                }
              }
            }
          ]
        }
      ]
    }
  }
}
 

Create a Ledger using the createLedger mutation.

createLedger
mutation QuickstartCreateLedger(
  $ik: SafeString!
  $ledger: CreateLedgerInput!
  $schema: SchemaMatchInput
) {
  createLedger(
    ik: $ik,
    ledger: $ledger,
    schema:$schema
  ) {
    ... on CreateLedgerResult {
      ledger {
        ik
        name
        created
        schema {
          key
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

The schema.key field is set to the key from the storeSchema API call.

createLedger variables
{
  "ik": "quickstart-ledger",
  "ledger": {
    "name": "Quickstart Ledger"
  },
  "schema": {
    "key": "quickstart-schema"
  }
}

c. CLI

#

The FRAGMENT CLI can be installed in your CI and used to store your Schema.

Here's an example of how you can use the CLI in a Github Action workflow:

Fragment CLI in Github Actions
- name: Set up Homebrew
  id: set-up-homebrew
  uses: Homebrew/actions/setup-homebrew@master
- name: Install Fragment CLI
  run: |
    brew tap fragment-dev/tap
    brew install fragment-dev/tap/fragment-cli
    echo "Fragment CLI installed"
- name: Authenticate with Fragment
  run: |
    fragment login \
      --client-id ${{ vars.FRAGMENT_CLIENT_ID }} \
      --client-secret ${{ vars.FRAGMENT_CLIENT_SECRET }} \
      --api-url ${{ vars.FRAGMENT_API_URL }} \
      --oauth-url ${{ vars.FRAGMENT_OAUTH_URL }} \
      --oauth-scope ${{ vars.FRAGMENT_OAUTH_SCOPE }}
- name: Store Schema
  run: |
    fragment store-schema --path my-schema.jsonc
 
D Integrate the API#

This section covers how to build a reliable and fault tolerant integration with FRAGMENT.

To integrate the API, you need to:

  1. Select the AWS region for your workspace.
  2. Generate an SDK based off your GraphQL queries and mutations.
  3. Authenticate your API client.
  4. Call the API with an idempotency key.
  5. Handle errors from the API.
  6. Decide whether to call the API synchronously or asynchronously.

a. Select region

#

FRAGMENT has a GraphQL API to read and write data from your Ledger. The API is available in the following AWS regions:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1

You can find the region for your workspace in the API URL in the settings tab of the dashboard. If you need to create a new workspace, you can do so through the top-left dropdown in the dashboard.

If you don't see your desired AWS region, contact us.

b. Generate an SDK

#

To ensure you always make valid queries, generate a typed SDK for your programming language. Do so using an SDK codegen tool and the current version of the FRAGMENT GraphQL schema.

FRAGMENT hosts the latest GraphQL schema at:

https://api.fragment.dev/schema.graphql

Use this URL as the SDK codegen input. All changes to the GraphQL API are backwards-compatible. You only need to generate a new version of the SDK to use new features.

Typescript#

graphql-codegen is a tool for generating Typescript SDKs:

  1. Add necessary dependencies to your package.json:
    • @graphql-codegen/typescript-graphql-request
    • @graphql-codegen/cli
    • graphql-request
    • graphql-tag
yarn add @graphql-codegen/typescript-graphql-request \
  @graphql-codegen/cli \
  graphql-request \
  graphql-tag
  1. Configure a codegen.yml file. A starter configuration is provided below.
  2. Define the GraphQL queries that your app uses in the queries folder.
  3. Generate the SDK by calling yarn graphql-codegen.

An example codegen.yml:

codegen.yml

schema: "https://api.fragment.dev/schema.graphql"
generates:
  fragment-sdk.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-graphql-request
      - add:
          content: "/* This file was auto-generated. Don't edit it directly. See 'codegen.yml' */"
    documents: './queries/**/*.ts'
    config:
      scalars:
        Int96: string

As an example, to generate a typed call to addLedgerEntry, define your query in ./queries/addLedgerEntry.ts as:

addLedgerEntry.ts

import gql from 'graphql-tag';

// eslint-disable-next-line @typescript-eslint/no-unused-vars
const QUERY = gql`
  mutation addLedgerEntry(
    $entry: LedgerEntryInput!,
    $ik: SafeString!
  ) {
    addLedgerEntry(ik: $ik, entry: $entry) {
      __typename
      ... on AddLedgerEntryResult {
        entry {
          id
          posted
          created
          date
          description
        }
        lines {
          id
          date
          posted
          created
          amount
          type
          ledgerId
          accountId
          ledgerEntryId
        }
        isIkReplay
      }
      ... on Error {
        code
        message
      }
    }
  }
`;

c. Authenticate

#

FRAGMENT uses OAuth2's client credentials flow to authenticate API clients. The call requesting an access token follows the OAuth2 spec. You can use any OAuth2 library that supports the client credentials grant to retrieve the token or make an HTTP request. The flow is:

  1. Create an API client in the FRAGMENT dashboard. All API Clients have full access to your workspace.
  2. Note the auth endpoint URL and OAuth scope for your API Client. This is specific to the AWS region of your workspace.
  3. Get a fresh access token from the token endpoint. The access token expires in 1 hour. We recommend retrieving a new token for each set of calls you make. You can generate and use multiple tokens at the same time.
  4. Use that token in an Authorization header with the value Bearer {{access_token}} when calling the GraphQL API.

Your token request payload should be in x-www-form-urlencoded format, with the keys grant_type, scope and client_id.

Token request body
grant_type=client_credentials&scope={{scope}}&client_id={{client_id}}

Your token request headers should contain the following, where client_credentials is the Base64-encoded version of: {{client_id}}:{client_secret}}.

Token request headers
{
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic {{client_credentials}}",
    "Accept": "*/*"
}

The response is a JSON object containing your access token.

Token response body
{
    "access_token": "<access token>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Putting it all together:

Javascript
import axios from "axios";

const btoa = (str) => Buffer.from(str).toString("base64");

// credentials from the dashboard
const clientId = "2h4t0cv7qv5c9r0qgs1o3erkuk";
const secret = "superSecretClientSecret";
const scope = "https://api.us-west-2.fragment.dev/*";
const authUrl = "https://auth.us-west-2.fragment.dev/oauth2/token";

const getToken = async () => {

  // encode the client id and secret
  const auth = btoa(`${clientId}:${secret}`);

  // create the request body
  const data = new URLSearchParams();
  data.append("grant_type", "client_credentials");
  data.append("scope", scope);
  data.append("client_id", clientId);

  // retrieve the token
  const response = await axios.request({
    method: "POST",
    url: authUrl,
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${auth}`,
      Accept: "*/*",
    },
    data,
  });

  if (!response.data.access_token) {
    throw new Error(
      "didn't get an access token from auth endpoint"
    );
  }
  return response.data.access_token;
};
 

d. Use idempotency

#

To ensure write operations are executed exactly once, all write mutations in FRAGMENT are idempotent. This lets you safely retry operations without risk of duplicate effects, so your application only needs to guarantee that it calls the API at least one time.

Mutations require you to provide a unique idempotency key (ik). For calls to reconcileTx, syncCustomAccounts and syncCustomTxs, FRAGMENT internally uses the transaction or account ID from the request as the idempotency key.

If you call the API more than once with the same ik and the same values, it executes only once. FRAGMENT ignores additional requests and returns the original response with isikReplay: true in the response.

Idempotency keys are scoped per-Ledger; if you send multiple requests with the same IK to different Ledgers, all mutations execute and return isIkReplay: false.

e. Error handling

#

According to the official GraphQL spec, all requests will return an object containing data and errors.

data: the result of your query or mutation. In the Fragment API, all successful mutations return a union type that represents an application error or a successful result. For example, the response type of the addLedgerEntry mutation is:

API Response Union Types
union AddLedgerEntryResponse =
    AddLedgerEntryResult | BadRequestError | InternalError

Queries can return null if an error was raised during the request. This is accompanied by a non-empty errors list.

errors: a list of errors raised during the request. This typically gets populated if you query for an entity with an invalid ID or don't provide a required argument.

When calling the API, your code should handle errors in this order:

  1. Handle retryable HTTP errors. These are 429 or 5XX.
  2. Handle non-retryable HTTP errors such as other 4XX status codes. This typically happens if your query does not conform to the GraphQL spec, like omitting a required variable or selecting a nonexistent field. This class of error can be avoided if you use a generated, typed SDK.
  3. Handle null responses from queries by checking the errors key. This typically happens if you query an item with an invalid ID.
  4. Query the __typename field. This contains BadRequestError, InternalError or your MutationResult type.
  5. Handle InternalError with retries and exponential backoff.
  6. Handle BadRequestError by failing the operation.
  7. Handle <Mutation>Result types such as AddLedgerEntryResult.

Here is an example of this written in Typescript:

Handling API Responses
import assert from 'assert';

type RequestParams = {
  query: string;
  variables: Record<string, unknown>;
};

const makeRequest = async ({ query, variables }: RequestParams): Promise<Response> => {
  const token = await getToken();
  return fetch('Fragment GraphQL URL', {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  });
};

const query = '''
  mutation addLedgerEntry($ik: SafeString, $entry: LedgerEntryInput!) {
    addLedgerEntry(ik: $ik, entry: $entry) {
      __typename
      ...
    }
  }
''';
const variables = { ik: 'sample-ik', entry: {...} };

const handleRequest = (req: Response) => {
  if (req.status === 429 || req.status >= 500) {
    // Rate-limited or intermittent http failures. Retry the request.
    return handleRequest(await makeRequest({ query, variables }));
  }
  if ((req.status >= 400 || req.status < 500) && req.status !== 429) {
    // Invalid GraphQL request provided to Fragment. Handle the error.
    throw new Error('Invalid GraphQL request');
  }

  // .json() checks that it was a 200
  const response = await req.json();
  if (response.data.addLedgerEntry.__typename === 'InternalError') {
    // Retry the request in case of internal errors, with backoff.
    return handleRequest(await makeRequest({ query, variables }));
  }
  if (response.data.addLedgerEntry.__typename === 'BadRequestError') {
    // Invalid request provided to Fragment. Handle the error.
    throw new Error('Invalid API request to Fragment');
  }
  return response;
};

const response = handleRequest(await makeRequest({ query, variables }));
// Entry successfully posted to Fragment. Handle the response.
assert(response.data.addLedgerEntry.__typename === 'AddLedgerEntryResult');
handlePostedEntry(response.data.addLedgerEntry);
 

To test how your application handles errors, you can force FRAGMENT to return erroneous responses using the X-Fragment-Return-Error request header.

Set the X-Fragment-Return-Error header to:

  • internalError to instruct the API to return an InternalError
  • badRequestError to instruct the API to return a BadRequestError

When requesting an erroneous response, FRAGMENT will skip processing your request and return the error immediately.

f. Sync or async

#

You can call FRAGMENT to update your Ledger with your product both synchronously and asynchronously.

To show users balances in real time, call the API synchronously. This ensures product flows block until the Ledger is updated; your users won't need to refresh to see updated balances. Sync updates can be both strongly or eventually consistent, depending on the use case. To make updates fault tolerant, implement your API calls with retries and exponential backoff.

For updates that don't need to be shown in real time, you can call the API asynchronously. This ensures your product flows don't block user activity while the balances are updated in your Ledger. Async updates are eventually consistent. A good easy pattern here is to have a table in your database that represents a call to FRAGMENT. Update this table transactionally from your product, then use an async queue that calls the API at least once for each transaction.

E Post Ledger Entries#

Posting a Ledger Entry to your Ledger is a two-step process:

  1. Define the structure of the Ledger Entry in your Schema.
  2. Post the Ledger Entry using the API.

a. Schema

#

Ledger Entries are defined in your Schema under the ledgerEntries.types key. Every Ledger Entry has a type that must be unique within the Schema.

Ledger Entry definition
{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account",
        "description": "Fund {{user_id}} for {{funding_amount}}",
        "lines": [
          {
            "account": { 
              "path": "assets/banks/user-cash"
            },
            "key": "funds_arrive_in_bank",
            "amount": "{{funding_amount}}"
          },
          {
            "account": { 
              "path": "liabilities/users:{{user_id}}/available"
            },
            "key": "increase_user_balance",
            "amount": "{{funding_amount}}"
          }
        ]
      }
    ]
  }
}

The amounts of a Ledger Line can be parameterized using {{handlebar}} syntax and can contain basic arithmetic (+ or -):

Ledger Entry definition
{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account_with_fee",
        "description": "Fund {{user_id}} for {{funding_amount}} with {{fee_amount}} fee",
        "lines": [
          {
            "account": { 
              "path": "assets/banks/user-cash"
            },
            "key": "funds_arrive_in_bank",
            "amount": "{{funding_amount}}"
          },
          {
            "account": { 
              "path": "liabilities/users:{{user_id}}/available"
            },
            "key": "increase_user_balance",
            "amount": "{{funding_amount}} - {{fee_amount}}"
          },
          {
            "account": { "path": "income/funding-fees" },
            "key": "take_fee",
            "amount": "{{fee_amount}}"
          }
        ]
      }
    ]
  }
}

Ledger Entries must be balanced by the Accounting Equation. If they are not, the Ledger designer throws an error.

b. Post to the API

#

Call the addLedgerEntry mutation to post a Ledger Entry:

addLedgerEntry mutation
mutation AddLedgerEntry(
  $ik: SafeString!
  $entry: LedgerEntryInput!
) {
  addLedgerEntry(
    ik: $ik,
    entry: $entry
  ) {
    __typename
    ... on AddLedgerEntryResult {
      entry {
        type
        created
        posted
      }
      lines {
        amount
        key
        description
        account {
          path
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}
 

Set the Ledger Entry's type and the required parameters.

addLedgerEntry variables
{
  "ik": "add-ledger-entry",
  "entry": {
    "ledger": {
      "ik": "ledger-ik"
    },
    "type": "user_funds_account",
    "posted": "1234-01-01T01:01:01",
    "parameters": {
      "user_id": "testing-user",
      "funding_amount": "200"
    }
  }
}
Minor Units#

All numbers in FRAGMENT are integers representing the smallest unit, encoded as strings. For example, USD $2.50 is provided as "250".

Tags#

You can specify tags on a Ledger Entry to store arbitrary key-value pairs. See Store metadata.

Idempotency#

To ensure a Ledger Entry is only posted once, provide an Idempotency Key ik to the addLedgerEntry mutation. This identifies the Ledger Entry and lets you safely retry the API call. See Integrate the API.

Timestamps#

Ledger Entries have two timestamps:

  • posted, the time the money movement event happened. You provide this to the addLedgerEntry API call.
  • created, the time at which the Ledger Entry was posted to the API. FRAGMENT auto-generates this value.

You can post entries with a posted timestamp in the past or future. Posting a Ledger Entry updates all balances from the posted time into the future.

c. Linked Accounts

#

Linked Ledger Accounts are used for reconciling your Ledger with your external financial systems.

To define a Ledger Entry to a Linked Ledger Account, you must specify the tx of the Ledger Line. This is the ID of the transaction at the external system.

Linked Ledger Account Entry
{
  "key": "linked-ledger-account-schema",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "reconciliation-type",
        "lines": [
          {
            "key": "reconciliation-line-key",
            "account": { "path": "bank" },
            "amount": "{{some_amount}}",
            "tx": {
              "externalId": "{{bank_transaction_id}}"
            }
          },
          {...other line}
        ]
      }
    ]
  }
}

To post Ledger Entries to a Linked Ledger Account, call reconcileTx instead of addLedgerEntry:

reconcileTx query
mutation ReconcileTx(
    $entry: LedgerEntryInput!
  ) {
    reconcileTx(entry: $entry) {
      __typename
      ... on ReconcileTxResult {
        entry {
          ik
          posted
          created
        }
        isIkReplay
        lines {
          amount
          currency {
            code
          }
        }
      }
      ... on Error {
        code
        message
      }
    }
  }
 

The query variables are the same as addLedgerEntry, except posted and ik are omitted. They are inferred from the external Tx.

reconcileTx variables
{
  "entry": {
    "type": "reconciliation-type",
    "ledger": {
      "ik": "ledger-ik"
    },
    "parameters": {
      "bank_transaction_id": "tx_1234"
    }
  }
}

Read more about creating and using Linked Ledger Accounts in Reconcile transactions.

d. Currencies

#

If a Ledger Account is in currencyMode: multi, you must specify the currency of the Ledger Lines posted to it.

Ledger Entry definition
{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account",
        "description": "Funding {{user_id}} for {{funding_amount}}",
        "lines": [
          {
            "account": { "path": "assets/banks/user-cash" },
            "key": "funds_arrive_in_bank",
            "amount": "{{funding_amount}}",
            "currency": {
              "code": "USD"
            }
          },
          {
            "account": { "path": "liabilities/users:{{user_id}}/available" },
            "key": "increase_user_balance",
            "amount": "{{funding_amount}}",
            "currency": {
              "code": "USD"
            }
          }
        ]
      }
    ]
  }
}

Read more about how to implement a product that handles multiple currencies in Handle currencies.

e. Using conditions

#

Ledger Entry conditions are rules defined in your Schema used to manage concurrency and enforce correctness within your Ledger. If a condition is not met, the Ledger Entry is not posted and the mutation throws a BadRequestError.

Conditions are defined in the Schema:

Ledger Entry Template with conditions
{
  "type": "user_withdraws_funds",
  "description": "{{user_id}} withdraws for {{withdraw_amount}}",
  "lines": [
    {
      "account": { "path": "assets/banks/user-cash" },
      "key": "funds_leave_bank",
      "amount": "-{{withdraw_amount}}"
    },
    {
      "account": { "path": "liabilities/users:{{user_id}}/available" },
      "key": "decrease_user_balance",
      "amount": "-{{withdraw_amount}}"
    }
  ],
  "conditions": [
    {
      "account": {
        "path": "liabilities/users:{{user_id}}/available"
      },
      "postcondition": {
        "ownBalance": {
          "gte": "0"
        }
      }
    }
  ]
}

Read more about using Ledger Entry Conditions in Configure consistency.

f. Using Groups

#

Ledger Entry Groups provide a way to tie together related Ledger Entries. You can configure them on a Ledger Entry Type in the Schema.

Ledger Entry Type with Groups
{
  "type": "user_initiates_withdrawal",
  "description": "{{user_id}} initiates withdrawal",
  "lines": [
    {
      "account": {
        "path": "liabilities/users:{{user_id}}/available"
      },
      "key": "decrease_user_balance",
      "amount": "-{{withdraw_amount}}"
    },
    {...other line}
  ],
  "groups": [
    {
      "key": "withdrawal",
      "value": "{{withdrawal_id}}"
    }
  ]
}

Read more about using Ledger Entry Groups in Group Ledger Entries.

g. Runtime Entries

#

You can define a Ledger Entry whose Ledger Lines are defined at runtime.

This can be useful if you're building a product where your end user, not you, defines the Ledger Entry structure. This is common for FRAGMENT users offering accounting services to their users.

To support runtime-defined Ledger Entries, omit the lines field in the Schema.

Runtime-defined Ledger Entry

{
  "type": "runtime_entry",
  "description": "Runtime-defined ledger entry"
}

Then, set the lines field when posting the Ledger Entry using addLedgerEntry or reconcileTx:

AddRuntimeLedgerEntry query
mutation AddRuntimeLedgerEntry(
  $ik: SafeString!
  $entry: LedgerEntryInput!
) {
  addLedgerEntry(
    ik: $ik,
    entry: $entry
  ) {
    ... on AddLedgerEntryResult {
      entry {
        type
        created
        posted
      }
      lines {
        amount
        key
        description
        account {
          path
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}
 
AddRuntimeLedgerEntry variables
{
  "ik": "add-arbitrary-ledger-entry",
  "entry": {
    "type": "runtime_entry",
    "lines": [
        {
          "account": { "path": "assets/banks/user-cash" },
          "key": "funds_arrive_in_bank",
          "amount": "100"
        },
        {
          "account": { "path": "liabilities/users:test-user/available" },
          "key": "increase_user_balance",
          "amount": "100"
        }

    ]
  }
}
F Reconcile Transactions#

Your Ledger should accurately track the real-world movement of money within your product. This is done by reconciling transactions from your external financial systems with your Ledger.

The overall workflow is a three-step process:

  1. Transact at your external financial system.
  2. Sync the real-world money movement to FRAGMENT.
  3. Reconcile the transaction to a Ledger Entry using the API.

This whole process happens through a FRAGMENT Link.

d. Linked Accounts

#

After you set up the Link, create Linked Ledger Accounts, accounts in your Ledger that map 1:1 with accounts at your external financial system.

To define a Linked Ledger Account, set linkedAccount on a Ledger Account in your Schema:

Linked Ledger Account with hardcoded IDs
{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "children": [{
          "key": "operating",
          "name": "Operating Bank",
          "linkedAccount": {
            "linkId": "some-link-id",
            "externalId": "bank-account-1"
          }
        }]
      }
    ]
  }
}

The linkId comes from the Link you create in the dashboard. The externalId is the ID of the account at your external financial system.

The CLI automatically replaces variables with ${ENV_VAR} syntax when running fragment store-schema. This lets you use different External Accounts per environment:

Linked Ledger Account with env var IDs
{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "children": [{
          "key": "operating",
          "name": "Operating Bank",
          "linkedAccount": {
            "linkId": "${BANK_LINK_ID}",
            "externalId": "${BANK_ACCOUNT_ID}"
          }
        }]
      }
    ]
  }
}

To create a Linked Ledger Account that is part of a Ledger Account template, parameterize the linkedAccount field:

Linked Ledger Account with parameter IDs
{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "children": [{
          "key": "operating",
          "name": "Operating Bank",
          "template": true,
          "linkedAccount": {
            "linkId": "{{BANK_LINK_ID}}",
            "externalId": "{{BANK_ACCOUNT_ID}}"
          }
        }]
      }
    ]
  }
}

These parameters are then required when posting a Ledger Entry to a Linked Ledger Account. This can be useful if you're creating bank accounts per customer, for example.

e. Transact externally

#

Transactions at your external financial system are initiated in one of two ways:

  • You initiate a payment by calling their API.
  • You are notified by the external system that a transaction has occurred. This can happen via webhook, by polling their API, or receiving a periodic transaction report.

f. Sync transactions

#

Once a transaction occurs, you need to sync it with your FRAGMENT Ledger.

If you're using a Native Link, FRAGMENT automatically syncs transactions. You can skip ahead to Reconcile transactions.

If you're using a Custom Link, your sync process should call syncCustomTxs. Your sync process can periodically enumerate transactions in your external system or be triggered by webhook.

You may also want to sync and reconcile when your product makes a payment. You should only sync transactions that are settled, not pending or declined.

Once you have a set of transactions to sync, call syncCustomTxs:

syncCustomTxs mutation
mutation SyncTransactions(
  $link: LinkMatchInput!
  $txs: [CustomTxInput!]!
) {
  syncCustomTxs(link: $link, txs: $txs) {
    __typename
    ... on SyncCustomTxsResult {
      txs {
        id
        externalId
        amount
        date
        description
      }
    }
    ... on Error {
      code
      message
    }
  }
}
syncCustomTxs variables
{
  "link": { "id": "some-link-id" },
  "txs": [
    {
      "account": {
        "linkId": "some-link-id",
        "id": "bank-account-1"
      },
      "externalId": "tx-1",
      "description": "Processed ACH batch",
      "amount": "-100",
      "posted": "1968-01-01"
    },
    {
      "account": {
        "linkId": "some-link-id",
        "externalId": "bank-account-2"
      },
      "externalId": "tx-2",
      "description": "Received RTP payment",
      "amount": "100",
      "posted": "1968-01-01T16:45:00Z"
    }
  ]
}

You should ensure that externalId is a stable and unique identifier for each transaction, within the scope of its account. This identifier enforces idempotentency. This identifier is typically the ID of the transaction at the external system. Make sure you use the lowest level transaction ID available, not the ID of a higher level construct that may be linked to multiple transactions, like a payment.

Calling syncCustomTxs with a different description for an existing externalId updates the name of the External Account. amount and posted timestamp are immutable.

You can sync transactions from different accounts in the same API call, but they must all belong to the same Custom Link.

g. Reconcile a Tx

#

To reconcile a transaction from an external system, follow the same two-step process as when posting Ledger Entries:

  1. Define the structure of the Ledger Entry in your Schema.
  2. Post the Ledger Entry using the API.

Ledger Entries posting to a Linked Ledger Account must specify the Tx from the External Account tied to the Ledger Account. This lets FRAGMENT know which transaction to reconcile:

LedgerEntrySchema with Linked Ledger Account
{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account_via_link",
        "description": "Funding {{user_id}} for {{funding_amount}}",
        "lines": [
          {
            "account": { "path": "assets/operating" },
            "key": "funds_arrive_in_bank",
            "tx": {
              "externalId": "{{bank_transaction_id}}"
            }
          },
          {
            "account": { "path": "liabilities/users:{{user_id}}/available" },
            "key": "increase_user_balance"
          }
        ]
      }
    ]
  }
}

Notes:

  • Ledger Lines posting to a Linked Ledger Account must match 1:1 with the Tx that's being reconciled.
  • bank_transaction_id represents the ID of the transaction at the external system.

Instead of calling addLedgerEntry, Linked Ledger Accounts use the reconcileTx mutation:

reconcileTx mutation
mutation ReconcileTx(
  $entry: LedgerEntryInput!
) {
  reconcileTx(
    entry: $entry
  ) {
    ... on ReconcileTxResult {
      entry {
        type
        created
        posted
      }
      lines {
        amount
        key
        description
        account {
          path
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}
 

The parameters look similar to addLedgerEntry. Specify the Ledger Entry type that you are using and provide the parameters defined in the Schema:

reconcileTx variables
{
  "entry": {
    "type": "user_funding",
    "ledger": {
      "ik": "ledger-ik"
    },
    "parameters": {
      "txId": "tx_12345",
      "customerId": "customer-1"
    }
  }
}

ik and posted are optional when posting Ledger Entries with reconcileTx:

  • ik: the Tx.externalId is used to ensure that reconciling a transaction is idempotent
  • posted: the timestamp of the Ledger Entry is taken from the Tx to ensure the Ledger mirrors the external system
Reconciling multiple Txs#

Book transfers are a common type of money movement which produce two Txs at your bank as part of one payment.

To reconcile multiple Txs using reconcileTx:

LedgerEntrySchema with multiple Txs
{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account_via_link",
        "description": "Funding {{user_id}} for {{funding_amount}}",
        "lines": [
          {
            "key": "funds_arrive_in_operating_bank",
            "account": { "path": "assets/operating-bank-account" },
            "tx": {
              "externalId": "{{bank_transaction_id}}"
            }
          },
          {
            "key": "funds_leave_holding_bank",
            "account": { "path": "assets/holding-bank-account" },
            "tx": {
              "externalId": "{{bank_transaction_id}}"
            }
          }
        ]
      }
    ]
  }
}

Notes:

  • Reconciling multiple Txs is only permitted if they have the same posted timestamp.
  • You can only reconcile multiple Txs within the same Link.

h. Unreconciled Txs

#

Transactions synced to FRAGMENT but not reconciled to a Ledger are considered unreconciled.