API Reference

• Introduction
• Authentication
• Auth
  • Clients
    • getList clients
    • postCreate client
    • getRead client
    • putUpdate client
    • delDelete client
    • postAdd a secret to a client
    • delDelete a secret from a client
    • putAdd scope to client
    • delDelete scope from client
  • Scopes
    • getList scopes
    • postCreate scope
    • getRead scope
    • putUpdate scope
    • delDelete scope
    • putAdd a transient scope to a scope
    • delDelete a transient scope from a scope
  • Users
    • getList users
    • getRead user
  • Auth
    • getGet server info
    • getList clients
    • postCreate client
    • getRead client
    • putUpdate client
    • delDelete client
    • postAdd a secret to a client
    • delDelete a secret from a client
    • putAdd scope to client
    • delDelete scope from client
    • getList scopes
    • postCreate scope
    • getRead scope
    • putUpdate scope
    • delDelete scope
    • putAdd a transient scope to a scope
    • delDelete a transient scope from a scope
    • getList users
    • getRead user
• Ledger
  • Ledger
    • getShow server information
    • getGet information about a ledger
    • headCount the accounts from a ledger
    • getList accounts from a ledger
    • getGet account by its address
    • postAdd metadata to an account
    • getGet the mapping of a ledger
    • putUpdate the mapping of a ledger
    • postExecute a Numscript
    • getGet statistics from a ledger
    • headCount the transactions from a ledger
    • getList transactions from a ledger
    • postCreate a new transaction to a ledger
    • getGet transaction from a ledger by its ID
    • postSet the metadata of a transaction by its ID
    • postRevert a ledger transaction by its ID
    • postCreate a new batch of transactions to a ledger
    • getGet the balances from a ledger's account
    • getGet the aggregated balances from selected accounts
    • getList the logs from a ledger
  • Server
    • getShow server information
  • Accounts
    • headCount the accounts from a ledger
    • getList accounts from a ledger
    • getGet account by its address
    • postAdd metadata to an account
  • Mapping
    • getGet the mapping of a ledger
    • putUpdate the mapping of a ledger
  • Script
    • postExecute a Numscript
  • Stats
    • getGet statistics from a ledger
  • Transactions
    • headCount the transactions from a ledger
    • getList transactions from a ledger
    • postCreate a new transaction to a ledger
    • getGet transaction from a ledger by its ID
    • postSet the metadata of a transaction by its ID
    • postRevert a ledger transaction by its ID
    • postCreate a new batch of transactions to a ledger
  • Balances
    • getGet the balances from a ledger's account
    • getGet the aggregated balances from selected accounts
• Payments
  • Payments
    • getGet server info
    • getList payments
    • getGet a payment
    • patchUpdate metadata
    • getList accounts
    • getList all installed connectors
    • getList the configs of each available connector
    • postInstall a connector
    • delUninstall a connector
    • getRead the config of a connector
    • postReset a connector
    • getList tasks from a connector
    • getRead a specific task of the connector
    • postTransfer funds between Connector accounts
    • getList transfers and their statuses
    • postTransfer funds between Stripe accounts
• Search
  • Search
    • getGet server info
    • postSearch
• Wallets
  • Wallets
    • getGet server info
    • getgetTransactions
    • getList all wallets
    • postCreate a new wallet
    • getGet a wallet
    • patchUpdate a wallet
    • getGet wallet summary
    • getList balances of a wallet
    • postCreate a balance
    • getGet detailed balance
    • postDebit a wallet
    • postCredit a wallet
    • getGet all holds for a wallet
    • getGet a hold
    • postConfirm a hold
    • postCancel a hold
• Webhooks
  • Webhooks
    • getGet many configs
    • postInsert a new config
    • delDelete one config
    • getTest one config
    • putActivate one config
    • putDeactivate one config
    • putChange the signing secret of a config
• Flows
  • Flows
    • getList registered workflows
    • postCreate workflow
    • getGet a flow by id
    • postRun workflow
    • getList instances of a workflow
    • getGet a workflow instance by id
    • postSend an event to a running workflow
    • putCancel a running workflow
    • getGet a workflow instance history by id
    • getGet a workflow instance stage history

API docs by Redocly

Formance Stack API (v1.0.20230710)

Download OpenAPI specification:Download

Formance: support@formance.com URL: https://www.formance.com

Open, modular foundation for unique payments flows

Introduction

This API is documented in OpenAPI format.

Authentication

Formance Stack offers one forms of authentication:

• OAuth2 OAuth2 - an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

Authorization

Security Scheme Type: OAuth2

Flow type: clientCredentials

Token URL:

Clients

List clients

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/clients

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "public": true,
    • "redirectUris": [

      • "string"

      ],
    • "description": "string",
    • "name": "string",
    • "trusted": true,
    • "postLogoutRedirectUris": [

      • "string"

      ],
    • "metadata": {

      • "property1": null,
      • "property2": null

      },
    • "id": "string",
    • "scopes": [

      • "string"

      ],
    • "secrets": [

      • {

        • "lastDigits": "string",
        • "name": "string",
        • "id": "string",
        • "metadata": {

          • "property1": null,
          • "property2": null

          }

        }

      ]

    }

  ]

}

Create client

Authorizations:

Authorization

Request Body schema: application/json

public	boolean
redirectUris	Array of strings
description	string
name required	string
trusted	boolean
postLogoutRedirectUris	Array of strings
	object (Metadata)

Responses

local server

http://localhost/api/auth/clients

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients

Request samples

• Payload

Content type

application/json

{

• "public": true,
• "redirectUris": [

  • "string"

  ],
• "description": "string",
• "name": "string",
• "trusted": true,
• "postLogoutRedirectUris": [

  • "string"

  ],
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 201

Content type

application/json

{

• "data": {

  • "public": true,
  • "redirectUris": [

    • "string"

    ],
  • "description": "string",
  • "name": "string",
  • "trusted": true,
  • "postLogoutRedirectUris": [

    • "string"

    ],
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "scopes": [

    • "string"

    ],
  • "secrets": [

    • {

      • "lastDigits": "string",
      • "name": "string",
      • "id": "string",
      • "metadata": {

        • "property1": null,
        • "property2": null

        }

      }

    ]

  }

}

Read client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Responses

local server

http://localhost/api/auth/clients/{clientId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "public": true,
  • "redirectUris": [

    • "string"

    ],
  • "description": "string",
  • "name": "string",
  • "trusted": true,
  • "postLogoutRedirectUris": [

    • "string"

    ],
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "scopes": [

    • "string"

    ],
  • "secrets": [

    • {

      • "lastDigits": "string",
      • "name": "string",
      • "id": "string",
      • "metadata": {

        • "property1": null,
        • "property2": null

        }

      }

    ]

  }

}

Update client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Request Body schema: application/json

public	boolean
redirectUris	Array of strings
description	string
name required	string
trusted	boolean
postLogoutRedirectUris	Array of strings
	object (Metadata)

Responses

local server

http://localhost/api/auth/clients/{clientId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}

Request samples

• Payload

Content type

application/json

{

• "public": true,
• "redirectUris": [

  • "string"

  ],
• "description": "string",
• "name": "string",
• "trusted": true,
• "postLogoutRedirectUris": [

  • "string"

  ],
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "public": true,
  • "redirectUris": [

    • "string"

    ],
  • "description": "string",
  • "name": "string",
  • "trusted": true,
  • "postLogoutRedirectUris": [

    • "string"

    ],
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "scopes": [

    • "string"

    ],
  • "secrets": [

    • {

      • "lastDigits": "string",
      • "name": "string",
      • "id": "string",
      • "metadata": {

        • "property1": null,
        • "property2": null

        }

      }

    ]

  }

}

Delete client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Responses

local server

http://localhost/api/auth/clients/{clientId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}

Add a secret to a client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Request Body schema: application/json

name required	string
	object (Metadata)

Responses

local server

http://localhost/api/auth/clients/{clientId}/secrets

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/secrets

Request samples

• Payload

Content type

application/json

{

• "name": "string",
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "name": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "lastDigits": "string",
  • "clear": "string"

  }

}

Delete a secret from a client

Authorizations:

Authorization

path Parameters

clientId required	string Client ID
secretId required	string Secret ID

Responses

local server

http://localhost/api/auth/clients/{clientId}/secrets/{secretId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/secrets/{secretId}

Add scope to client

Authorizations:

Authorization

path Parameters

clientId required	string Client ID
scopeId required	string Scope ID

Responses

local server

http://localhost/api/auth/clients/{clientId}/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/scopes/{scopeId}

Delete scope from client

Authorizations:

Authorization

path Parameters

clientId required	string Client ID
scopeId required	string Scope ID

Responses

local server

http://localhost/api/auth/clients/{clientId}/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/scopes/{scopeId}

Scopes

List scopes

List Scopes

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/scopes

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "label": "string",
    • "metadata": {

      • "property1": null,
      • "property2": null

      },
    • "id": "string",
    • "transient": [

      • "string"

      ]

    }

  ]

}

Create scope

Create scope

Authorizations:

Authorization

Request Body schema: application/json

label required	string
	object (Metadata)

Responses

local server

http://localhost/api/auth/scopes

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes

Request samples

• Payload

Content type

application/json

{

• "label": "string",
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 201

Content type

application/json

{

• "data": {

  • "label": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "transient": [

    • "string"

    ]

  }

}

Read scope

Read scope

Authorizations:

Authorization

path Parameters

scopeId required

string Scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "label": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "transient": [

    • "string"

    ]

  }

}

Update scope

Update scope

Authorizations:

Authorization

path Parameters

scopeId required

string Scope ID

Request Body schema: application/json

label required	string
	object (Metadata)

Responses

local server

http://localhost/api/auth/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}

Request samples

• Payload

Content type

application/json

{

• "label": "string",
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "label": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "transient": [

    • "string"

    ]

  }

}

Delete scope

Delete scope

Authorizations:

Authorization

path Parameters

scopeId required

string Scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}

Add a transient scope to a scope

Add a transient scope to a scope

Authorizations:

Authorization

path Parameters

scopeId required	string Scope ID
transientScopeId required	string Transient scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}/transient/{transientScopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}/transient/{transientScopeId}

Delete a transient scope from a scope

Delete a transient scope from a scope

Authorizations:

Authorization

path Parameters

scopeId required	string Scope ID
transientScopeId required	string Transient scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}/transient/{transientScopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}/transient/{transientScopeId}

Users

List users

List users

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/users

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/users

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "id": "3bb03708-312f-48a0-821a-e765837dc2c4",
    • "subject": "Jane Doe",
    • "email": "user1@orga1.com"

    }

  ]

}

Read user

Read user

Authorizations:

Authorization

path Parameters

userId required

string User ID

Responses

local server

http://localhost/api/auth/users/{userId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/users/{userId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "id": "3bb03708-312f-48a0-821a-e765837dc2c4",
  • "subject": "Jane Doe",
  • "email": "user1@orga1.com"

  }

}

Auth

Get server info

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/_info

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/_info

Response samples

• 200

Content type

application/json

{

• "version": "string"

}

List clients

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/clients

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "public": true,
    • "redirectUris": [

      • "string"

      ],
    • "description": "string",
    • "name": "string",
    • "trusted": true,
    • "postLogoutRedirectUris": [

      • "string"

      ],
    • "metadata": {

      • "property1": null,
      • "property2": null

      },
    • "id": "string",
    • "scopes": [

      • "string"

      ],
    • "secrets": [

      • {

        • "lastDigits": "string",
        • "name": "string",
        • "id": "string",
        • "metadata": {

          • "property1": null,
          • "property2": null

          }

        }

      ]

    }

  ]

}

Create client

Authorizations:

Authorization

Request Body schema: application/json

public	boolean
redirectUris	Array of strings
description	string
name required	string
trusted	boolean
postLogoutRedirectUris	Array of strings
	object (Metadata)

Responses

local server

http://localhost/api/auth/clients

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients

Request samples

• Payload

Content type

application/json

{

• "public": true,
• "redirectUris": [

  • "string"

  ],
• "description": "string",
• "name": "string",
• "trusted": true,
• "postLogoutRedirectUris": [

  • "string"

  ],
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 201

Content type

application/json

{

• "data": {

  • "public": true,
  • "redirectUris": [

    • "string"

    ],
  • "description": "string",
  • "name": "string",
  • "trusted": true,
  • "postLogoutRedirectUris": [

    • "string"

    ],
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "scopes": [

    • "string"

    ],
  • "secrets": [

    • {

      • "lastDigits": "string",
      • "name": "string",
      • "id": "string",
      • "metadata": {

        • "property1": null,
        • "property2": null

        }

      }

    ]

  }

}

Read client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Responses

local server

http://localhost/api/auth/clients/{clientId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "public": true,
  • "redirectUris": [

    • "string"

    ],
  • "description": "string",
  • "name": "string",
  • "trusted": true,
  • "postLogoutRedirectUris": [

    • "string"

    ],
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "scopes": [

    • "string"

    ],
  • "secrets": [

    • {

      • "lastDigits": "string",
      • "name": "string",
      • "id": "string",
      • "metadata": {

        • "property1": null,
        • "property2": null

        }

      }

    ]

  }

}

Update client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Request Body schema: application/json

public	boolean
redirectUris	Array of strings
description	string
name required	string
trusted	boolean
postLogoutRedirectUris	Array of strings
	object (Metadata)

Responses

local server

http://localhost/api/auth/clients/{clientId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}

Request samples

• Payload

Content type

application/json

{

• "public": true,
• "redirectUris": [

  • "string"

  ],
• "description": "string",
• "name": "string",
• "trusted": true,
• "postLogoutRedirectUris": [

  • "string"

  ],
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "public": true,
  • "redirectUris": [

    • "string"

    ],
  • "description": "string",
  • "name": "string",
  • "trusted": true,
  • "postLogoutRedirectUris": [

    • "string"

    ],
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "scopes": [

    • "string"

    ],
  • "secrets": [

    • {

      • "lastDigits": "string",
      • "name": "string",
      • "id": "string",
      • "metadata": {

        • "property1": null,
        • "property2": null

        }

      }

    ]

  }

}

Delete client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Responses

local server

http://localhost/api/auth/clients/{clientId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}

Add a secret to a client

Authorizations:

Authorization

path Parameters

clientId required

string Client ID

Request Body schema: application/json

name required	string
	object (Metadata)

Responses

local server

http://localhost/api/auth/clients/{clientId}/secrets

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/secrets

Request samples

• Payload

Content type

application/json

{

• "name": "string",
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "name": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "lastDigits": "string",
  • "clear": "string"

  }

}

Delete a secret from a client

Authorizations:

Authorization

path Parameters

clientId required	string Client ID
secretId required	string Secret ID

Responses

local server

http://localhost/api/auth/clients/{clientId}/secrets/{secretId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/secrets/{secretId}

Add scope to client

Authorizations:

Authorization

path Parameters

clientId required	string Client ID
scopeId required	string Scope ID

Responses

local server

http://localhost/api/auth/clients/{clientId}/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/scopes/{scopeId}

Delete scope from client

Authorizations:

Authorization

path Parameters

clientId required	string Client ID
scopeId required	string Scope ID

Responses

local server

http://localhost/api/auth/clients/{clientId}/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/clients/{clientId}/scopes/{scopeId}

List scopes

List Scopes

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/scopes

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "label": "string",
    • "metadata": {

      • "property1": null,
      • "property2": null

      },
    • "id": "string",
    • "transient": [

      • "string"

      ]

    }

  ]

}

Create scope

Create scope

Authorizations:

Authorization

Request Body schema: application/json

label required	string
	object (Metadata)

Responses

local server

http://localhost/api/auth/scopes

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes

Request samples

• Payload

Content type

application/json

{

• "label": "string",
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 201

Content type

application/json

{

• "data": {

  • "label": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "transient": [

    • "string"

    ]

  }

}

Read scope

Read scope

Authorizations:

Authorization

path Parameters

scopeId required

string Scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "label": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "transient": [

    • "string"

    ]

  }

}

Update scope

Update scope

Authorizations:

Authorization

path Parameters

scopeId required

string Scope ID

Request Body schema: application/json

label required	string
	object (Metadata)

Responses

local server

http://localhost/api/auth/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}

Request samples

• Payload

Content type

application/json

{

• "label": "string",
• "metadata": {

  • "property1": null,
  • "property2": null

  }

}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "label": "string",
  • "metadata": {

    • "property1": null,
    • "property2": null

    },
  • "id": "string",
  • "transient": [

    • "string"

    ]

  }

}

Delete scope

Delete scope

Authorizations:

Authorization

path Parameters

scopeId required

string Scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}

Add a transient scope to a scope

Add a transient scope to a scope

Authorizations:

Authorization

path Parameters

scopeId required	string Scope ID
transientScopeId required	string Transient scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}/transient/{transientScopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}/transient/{transientScopeId}

Delete a transient scope from a scope

Delete a transient scope from a scope

Authorizations:

Authorization

path Parameters

scopeId required	string Scope ID
transientScopeId required	string Transient scope ID

Responses

local server

http://localhost/api/auth/scopes/{scopeId}/transient/{transientScopeId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/scopes/{scopeId}/transient/{transientScopeId}

List users

List users

Authorizations:

Authorization

Responses

local server

http://localhost/api/auth/users

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/users

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "id": "3bb03708-312f-48a0-821a-e765837dc2c4",
    • "subject": "Jane Doe",
    • "email": "user1@orga1.com"

    }

  ]

}

Read user

Read user

Authorizations:

Authorization

path Parameters

userId required

string User ID

Responses

local server

http://localhost/api/auth/users/{userId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/auth/users/{userId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "id": "3bb03708-312f-48a0-821a-e765837dc2c4",
  • "subject": "Jane Doe",
  • "email": "user1@orga1.com"

  }

}

Ledger

Show server information

Authorizations:

Authorization

Responses

local server

http://localhost/api/ledger/_info

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/_info

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "config": {

    • "storage": {

      • "driver": "string",
      • "ledgers": [

        • "string"

        ]

      }

    },
  • "server": "string",
  • "version": "string"

  }

}

Get information about a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Responses

local server

http://localhost/api/ledger/{ledger}/_info

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/_info

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "name": "ledger001",
  • "storage": {

    • "migrations": [

      • {

        • "version": 11,
        • "name": "migrations:001",
        • "date": "2019-08-24T14:15:22Z",
        • "state": "to do"

        }

      ]

    }

  }

}

Count the accounts from a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

address	string Example: address=users:.+ Filter accounts by address pattern (regular expression placed between ^ and $).
metadata	object Example: Filter accounts by metadata key value pairs. The filter can be used like this metadata[key]=value1&metadata[a.nested.key]=value2

Responses

local server

http://localhost/api/ledger/{ledger}/accounts

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

List accounts from a ledger

List accounts from a ledger, sorted by address in descending order.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
page_size	integer <int64> [ 1 .. 1000 ] Deprecated Default: 15 Example: page_size=100 The maximum number of results to return per page. Deprecated, please use pageSize instead.
after	string Example: after=users:003 Pagination cursor, will return accounts after given address, in descending order.
address	string Example: address=users:.+ Filter accounts by address pattern (regular expression placed between ^ and $).
metadata	object Example: Filter accounts by metadata key value pairs. Nested objects can be used as seen in the example below.
balance	integer <int64> Example: balance=2400 Filter accounts by their balance (default operator is gte)
balanceOperator	string Enum: "gte" "lte" "gt" "lt" "e" "ne" Example: balanceOperator=gte Operator used for the filtering of balances can be greater than/equal, less than/equal, greater than, less than, equal or not.
balance_operator	string Deprecated Enum: "gte" "lte" "gt" "lt" "e" "ne" Example: balance_operator=gte Operator used for the filtering of balances can be greater than/equal, less than/equal, greater than, less than, equal or not. Deprecated, please use balanceOperator instead.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. Deprecated, please use cursor instead.

Responses

local server

http://localhost/api/ledger/{ledger}/accounts

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "address": "users:001",
      • "type": "virtual",
      • "metadata": {

        • "admin": true,
        • "a": {

          • "nested": {

            • "key": "value"

            }

          }

        }

      }

    ]

  }

}

Get account by its address

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
address required	string Example: users:001 Exact address of the account. It must match the following regular expressions pattern: ^\w+(:\w+)*$

Responses

local server

http://localhost/api/ledger/{ledger}/accounts/{address}

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts/{address}

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "address": "users:001",
  • "type": "virtual",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "volumes": {

    • "COIN": {

      • "input": 100,
      • "output": 0

      }

    },
  • "balances": {

    • "COIN": 100

    }

  }

}

Add metadata to an account

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
address required	string Example: users:001 Exact address of the account. It must match the following regular expressions pattern: ^\w+(:\w+)*$

Request Body schema: application/json

required

metadata

property name* additional property

any

Responses

local server

http://localhost/api/ledger/{ledger}/accounts/{address}/metadata

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts/{address}/metadata

Request samples

• Payload

Content type

application/json

{

• "admin": true,
• "a": {

  • "nested": {

    • "key": "value"

    }

  }

}

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

Get the mapping of a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Responses

local server

http://localhost/api/ledger/{ledger}/mapping

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/mapping

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "contracts": [

    • {

      • "account": "users:001",
      • "expr": { }

      }

    ]

  }

}

Update the mapping of a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Request Body schema: application/json

required

required	Array of objects (Contract)
Array account string expr required object

Responses

local server

http://localhost/api/ledger/{ledger}/mapping

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/mapping

Request samples

• Payload

Content type

application/json

{

• "contracts": [

  • {

    • "account": "users:001",
    • "expr": { }

    }

  ]

}

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "contracts": [

    • {

      • "account": "users:001",
      • "expr": { }

      }

    ]

  }

}

Execute a Numscript Deprecated

This route is deprecated, and has been merged into POST /{ledger}/transactions.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

preview

boolean Example: preview=true Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request Body schema: application/json

required

plain required	string
vars	object
reference	string Reference to attach to the generated transaction
	object or null (ledgerMetadata)

Responses

local server

http://localhost/api/ledger/{ledger}/script

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/script

Request samples

• Payload

Content type

application/json

{

• "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
• "vars": {

  • "user": "users:042"

  },
• "reference": "order_1234",
• "metadata": {

  • "admin": true,
  • "a": {

    • "nested": {

      • "key": "value"

      }

    }

  }

}

Response samples

• 200

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9",
• "transaction": {

  • "timestamp": "2019-08-24T14:15:22Z",
  • "postings": [

    • {

      • "amount": 100,
      • "asset": "COIN",
      • "destination": "users:002",
      • "source": "users:001"

      }

    ],
  • "reference": "ref:001",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "txid": 0,
  • "preCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    },
  • "postCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    }

  }

}

Get statistics from a ledger

Get statistics from a ledger. (aggregate metrics on accounts and transactions)

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 name of the ledger

Responses

local server

http://localhost/api/ledger/{ledger}/stats

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/stats

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "accounts": 0,
  • "transactions": 0

  }

}

Count the transactions from a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

reference	string Example: reference=ref:001 Filter transactions by reference field.
account	string Example: account=users:001 Filter transactions with postings involving given account, either as source or destination (regular expression placed between ^ and $).
source	string Example: source=users:001 Filter transactions with postings involving given account at source (regular expression placed between ^ and $).
destination	string Example: destination=users:001 Filter transactions with postings involving given account at destination (regular expression placed between ^ and $).
startTime	string <date-time> Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute).
start_time	string <date-time> Deprecated Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute). Deprecated, please use startTime instead.
endTime	string <date-time> Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute).
end_time	string <date-time> Deprecated Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute). Deprecated, please use endTime instead.
metadata	object Example: Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

List transactions from a ledger

List transactions from a ledger, sorted by txid in descending order.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
page_size	integer <int64> [ 1 .. 1000 ] Deprecated Default: 15 Example: page_size=100 The maximum number of results to return per page. Deprecated, please use pageSize instead.
after	string Example: after=1234 Pagination cursor, will return transactions after given txid (in descending order).
reference	string Example: reference=ref:001 Find transactions by reference field.
account	string Example: account=users:001 Filter transactions with postings involving given account, either as source or destination (regular expression placed between ^ and $).
source	string Example: source=users:001 Filter transactions with postings involving given account at source (regular expression placed between ^ and $).
destination	string Example: destination=users:001 Filter transactions with postings involving given account at destination (regular expression placed between ^ and $).
startTime	string <date-time> Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute).
start_time	string <date-time> Deprecated Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute). Deprecated, please use startTime instead.
endTime	string <date-time> Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute).
end_time	string <date-time> Deprecated Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute). Deprecated, please use endTime instead.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. Deprecated, please use cursor instead.
metadata	object Example: Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "timestamp": "2019-08-24T14:15:22Z",
      • "postings": [

        • {

          • "amount": 100,
          • "asset": "COIN",
          • "destination": "users:002",
          • "source": "users:001"

          }

        ],
      • "reference": "ref:001",
      • "metadata": {

        • "admin": true,
        • "a": {

          • "nested": {

            • "key": "value"

            }

          }

        },
      • "txid": 0,
      • "preCommitVolumes": {

        • "orders:1": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          },
        • "orders:2": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          }

        },
      • "postCommitVolumes": {

        • "orders:1": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          },
        • "orders:2": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          }

        }

      }

    ]

  }

}

Create a new transaction to a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

preview

boolean Example: preview=true Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request Body schema: application/json

required

The request body must contain at least one of the following objects:

• postings: suitable for simple transactions
• script: enabling more complex transactions with Numscript

timestamp	string <date-time>
	Array of objects (Posting)
	object
reference	string
	object or null (ledgerMetadata)

Responses

local server

http://localhost/api/ledger/{ledger}/transactions

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions

Request samples

• Payload

Content type

application/json

{

• "timestamp": "2019-08-24T14:15:22Z",
• "postings": [

  • {

    • "amount": 100,
    • "asset": "COIN",
    • "destination": "users:002",
    • "source": "users:001"

    }

  ],
• "script": {

  • "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
  • "vars": {

    • "user": "users:042"

    }

  },
• "reference": "ref:001",
• "metadata": {

  • "admin": true,
  • "a": {

    • "nested": {

      • "key": "value"

      }

    }

  }

}

Response samples

• 200
• default

Content type

application/json

{

• "data": [

  • {

    • "timestamp": "2019-08-24T14:15:22Z",
    • "postings": [

      • {

        • "amount": 100,
        • "asset": "COIN",
        • "destination": "users:002",
        • "source": "users:001"

        }

      ],
    • "reference": "ref:001",
    • "metadata": {

      • "admin": true,
      • "a": {

        • "nested": {

          • "key": "value"

          }

        }

      },
    • "txid": 0,
    • "preCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      },
    • "postCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      }

    }

  ]

}

Get transaction from a ledger by its ID

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
txid required	integer <int64> >= 0 Example: 1234 Transaction ID.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/{txid}

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/{txid}

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "timestamp": "2019-08-24T14:15:22Z",
  • "postings": [

    • {

      • "amount": 100,
      • "asset": "COIN",
      • "destination": "users:002",
      • "source": "users:001"

      }

    ],
  • "reference": "ref:001",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "txid": 0,
  • "preCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    },
  • "postCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    }

  }

}

Set the metadata of a transaction by its ID

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
txid required	integer <int64> >= 0 Example: 1234 Transaction ID.

Request Body schema: application/json

metadata

property name* additional property

any

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/{txid}/metadata

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/{txid}/metadata

Request samples

• Payload

Content type

application/json

{

• "admin": true,
• "a": {

  • "nested": {

    • "key": "value"

    }

  }

}

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

Revert a ledger transaction by its ID

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
txid required	integer <int64> >= 0 Example: 1234 Transaction ID.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/{txid}/revert

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/{txid}/revert

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "timestamp": "2019-08-24T14:15:22Z",
  • "postings": [

    • {

      • "amount": 100,
      • "asset": "COIN",
      • "destination": "users:002",
      • "source": "users:001"

      }

    ],
  • "reference": "ref:001",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "txid": 0,
  • "preCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    },
  • "postCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    }

  }

}

Create a new batch of transactions to a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Request Body schema: application/json

required

required	Array of objects (TransactionData)
Array required Array of objects (Posting) reference string object or null (ledgerMetadata) timestamp string <date-time>

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/batch

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/batch

Request samples

• Payload

Content type

application/json

{

• "transactions": [

  • {

    • "postings": [

      • {

        • "amount": 100,
        • "asset": "COIN",
        • "destination": "users:002",
        • "source": "users:001"

        }

      ],
    • "reference": "ref:001",
    • "metadata": {

      • "admin": true,
      • "a": {

        • "nested": {

          • "key": "value"

          }

        }

      },
    • "timestamp": "2019-08-24T14:15:22Z"

    }

  ]

}

Response samples

• 200
• default

Content type

application/json

{

• "data": [

  • {

    • "timestamp": "2019-08-24T14:15:22Z",
    • "postings": [

      • {

        • "amount": 100,
        • "asset": "COIN",
        • "destination": "users:002",
        • "source": "users:001"

        }

      ],
    • "reference": "ref:001",
    • "metadata": {

      • "admin": true,
      • "a": {

        • "nested": {

          • "key": "value"

          }

        }

      },
    • "txid": 0,
    • "preCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      },
    • "postCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      }

    }

  ]

}

Get the balances from a ledger's account

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

address	string Example: address=users:001 Filter balances involving given account, either as source or destination.
after	string Example: after=users:003 Pagination cursor, will return accounts after given address, in descending order.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. Deprecated, please use cursor instead.

Responses

local server

http://localhost/api/ledger/{ledger}/balances

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/balances

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "account1": {

        • "USD": 100,
        • "EUR": 23

        },
      • "account2": {

        • "CAD": 20,
        • "JPY": 21

        }

      }

    ]

  }

}

Get the aggregated balances from selected accounts

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

address

string Example: address=users:001 Filter balances involving given account, either as source or destination.

Responses

local server

http://localhost/api/ledger/{ledger}/aggregate/balances

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/aggregate/balances

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "USD": 100,
  • "EUR": 12

  }

}

List the logs from a ledger

List the logs from a ledger, sorted by ID in descending order.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
page_size	integer <int64> [ 1 .. 1000 ] Deprecated Default: 15 Example: page_size=100 The maximum number of results to return per page. Deprecated, please use pageSize instead.
after	string Example: after=1234 Pagination cursor, will return the logs after a given ID. (in descending order).
startTime	string <date-time> Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute).
start_time	string <date-time> Deprecated Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute). Deprecated, please use startTime instead.
endTime	string <date-time> Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute).
end_time	string <date-time> Deprecated Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute). Deprecated, please use endTime instead.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. Deprecated, please use cursor instead.

Responses

local server

http://localhost/api/ledger/{ledger}/logs

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/logs

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "id": 1234,
      • "type": "NEW_TRANSACTION",
      • "data": { },
      • "hash": "9ee060170400f556b7e1575cb13f9db004f150a08355c7431c62bc639166431e",
      • "date": "2019-08-24T14:15:22Z"

      }

    ]

  }

}

Server

Show server information

Authorizations:

Authorization

Responses

local server

http://localhost/api/ledger/_info

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/_info

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "config": {

    • "storage": {

      • "driver": "string",
      • "ledgers": [

        • "string"

        ]

      }

    },
  • "server": "string",
  • "version": "string"

  }

}

Accounts

Count the accounts from a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

address	string Example: address=users:.+ Filter accounts by address pattern (regular expression placed between ^ and $).
metadata	object Example: Filter accounts by metadata key value pairs. The filter can be used like this metadata[key]=value1&metadata[a.nested.key]=value2

Responses

local server

http://localhost/api/ledger/{ledger}/accounts

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

List accounts from a ledger

List accounts from a ledger, sorted by address in descending order.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
page_size	integer <int64> [ 1 .. 1000 ] Deprecated Default: 15 Example: page_size=100 The maximum number of results to return per page. Deprecated, please use pageSize instead.
after	string Example: after=users:003 Pagination cursor, will return accounts after given address, in descending order.
address	string Example: address=users:.+ Filter accounts by address pattern (regular expression placed between ^ and $).
metadata	object Example: Filter accounts by metadata key value pairs. Nested objects can be used as seen in the example below.
balance	integer <int64> Example: balance=2400 Filter accounts by their balance (default operator is gte)
balanceOperator	string Enum: "gte" "lte" "gt" "lt" "e" "ne" Example: balanceOperator=gte Operator used for the filtering of balances can be greater than/equal, less than/equal, greater than, less than, equal or not.
balance_operator	string Deprecated Enum: "gte" "lte" "gt" "lt" "e" "ne" Example: balance_operator=gte Operator used for the filtering of balances can be greater than/equal, less than/equal, greater than, less than, equal or not. Deprecated, please use balanceOperator instead.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. Deprecated, please use cursor instead.

Responses

local server

http://localhost/api/ledger/{ledger}/accounts

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "address": "users:001",
      • "type": "virtual",
      • "metadata": {

        • "admin": true,
        • "a": {

          • "nested": {

            • "key": "value"

            }

          }

        }

      }

    ]

  }

}

Get account by its address

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
address required	string Example: users:001 Exact address of the account. It must match the following regular expressions pattern: ^\w+(:\w+)*$

Responses

local server

http://localhost/api/ledger/{ledger}/accounts/{address}

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts/{address}

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "address": "users:001",
  • "type": "virtual",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "volumes": {

    • "COIN": {

      • "input": 100,
      • "output": 0

      }

    },
  • "balances": {

    • "COIN": 100

    }

  }

}

Add metadata to an account

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
address required	string Example: users:001 Exact address of the account. It must match the following regular expressions pattern: ^\w+(:\w+)*$

Request Body schema: application/json

required

metadata

property name* additional property

any

Responses

local server

http://localhost/api/ledger/{ledger}/accounts/{address}/metadata

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/accounts/{address}/metadata

Request samples

• Payload

Content type

application/json

{

• "admin": true,
• "a": {

  • "nested": {

    • "key": "value"

    }

  }

}

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

Mapping

Get the mapping of a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Responses

local server

http://localhost/api/ledger/{ledger}/mapping

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/mapping

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "contracts": [

    • {

      • "account": "users:001",
      • "expr": { }

      }

    ]

  }

}

Update the mapping of a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Request Body schema: application/json

required

required	Array of objects (Contract)
Array account string expr required object

Responses

local server

http://localhost/api/ledger/{ledger}/mapping

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/mapping

Request samples

• Payload

Content type

application/json

{

• "contracts": [

  • {

    • "account": "users:001",
    • "expr": { }

    }

  ]

}

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "contracts": [

    • {

      • "account": "users:001",
      • "expr": { }

      }

    ]

  }

}

Script

Execute a Numscript Deprecated

This route is deprecated, and has been merged into POST /{ledger}/transactions.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

preview

boolean Example: preview=true Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request Body schema: application/json

required

plain required	string
vars	object
reference	string Reference to attach to the generated transaction
	object or null (ledgerMetadata)

Responses

local server

http://localhost/api/ledger/{ledger}/script

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/script

Request samples

• Payload

Content type

application/json

{

• "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
• "vars": {

  • "user": "users:042"

  },
• "reference": "order_1234",
• "metadata": {

  • "admin": true,
  • "a": {

    • "nested": {

      • "key": "value"

      }

    }

  }

}

Response samples

• 200

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9",
• "transaction": {

  • "timestamp": "2019-08-24T14:15:22Z",
  • "postings": [

    • {

      • "amount": 100,
      • "asset": "COIN",
      • "destination": "users:002",
      • "source": "users:001"

      }

    ],
  • "reference": "ref:001",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "txid": 0,
  • "preCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    },
  • "postCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    }

  }

}

Stats

Get statistics from a ledger

Get statistics from a ledger. (aggregate metrics on accounts and transactions)

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 name of the ledger

Responses

local server

http://localhost/api/ledger/{ledger}/stats

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/stats

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "accounts": 0,
  • "transactions": 0

  }

}

Transactions

Count the transactions from a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

reference	string Example: reference=ref:001 Filter transactions by reference field.
account	string Example: account=users:001 Filter transactions with postings involving given account, either as source or destination (regular expression placed between ^ and $).
source	string Example: source=users:001 Filter transactions with postings involving given account at source (regular expression placed between ^ and $).
destination	string Example: destination=users:001 Filter transactions with postings involving given account at destination (regular expression placed between ^ and $).
startTime	string <date-time> Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute).
start_time	string <date-time> Deprecated Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute). Deprecated, please use startTime instead.
endTime	string <date-time> Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute).
end_time	string <date-time> Deprecated Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute). Deprecated, please use endTime instead.
metadata	object Example: Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

List transactions from a ledger

List transactions from a ledger, sorted by txid in descending order.

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
page_size	integer <int64> [ 1 .. 1000 ] Deprecated Default: 15 Example: page_size=100 The maximum number of results to return per page. Deprecated, please use pageSize instead.
after	string Example: after=1234 Pagination cursor, will return transactions after given txid (in descending order).
reference	string Example: reference=ref:001 Find transactions by reference field.
account	string Example: account=users:001 Filter transactions with postings involving given account, either as source or destination (regular expression placed between ^ and $).
source	string Example: source=users:001 Filter transactions with postings involving given account at source (regular expression placed between ^ and $).
destination	string Example: destination=users:001 Filter transactions with postings involving given account at destination (regular expression placed between ^ and $).
startTime	string <date-time> Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute).
start_time	string <date-time> Deprecated Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, "2023-01-02T15:04:01Z" includes the first second of 4th minute). Deprecated, please use startTime instead.
endTime	string <date-time> Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute).
end_time	string <date-time> Deprecated Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, "2023-01-02T15:04:01Z" excludes the first second of 4th minute). Deprecated, please use endTime instead.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. Deprecated, please use cursor instead.
metadata	object Example: Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "timestamp": "2019-08-24T14:15:22Z",
      • "postings": [

        • {

          • "amount": 100,
          • "asset": "COIN",
          • "destination": "users:002",
          • "source": "users:001"

          }

        ],
      • "reference": "ref:001",
      • "metadata": {

        • "admin": true,
        • "a": {

          • "nested": {

            • "key": "value"

            }

          }

        },
      • "txid": 0,
      • "preCommitVolumes": {

        • "orders:1": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          },
        • "orders:2": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          }

        },
      • "postCommitVolumes": {

        • "orders:1": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          },
        • "orders:2": {

          • "USD": {

            • "input": 100,
            • "output": 10,
            • "balance": 90

            }

          }

        }

      }

    ]

  }

}

Create a new transaction to a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

preview

boolean Example: preview=true Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request Body schema: application/json

required

The request body must contain at least one of the following objects:

• postings: suitable for simple transactions
• script: enabling more complex transactions with Numscript

timestamp	string <date-time>
	Array of objects (Posting)
	object
reference	string
	object or null (ledgerMetadata)

Responses

local server

http://localhost/api/ledger/{ledger}/transactions

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions

Request samples

• Payload

Content type

application/json

{

• "timestamp": "2019-08-24T14:15:22Z",
• "postings": [

  • {

    • "amount": 100,
    • "asset": "COIN",
    • "destination": "users:002",
    • "source": "users:001"

    }

  ],
• "script": {

  • "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
  • "vars": {

    • "user": "users:042"

    }

  },
• "reference": "ref:001",
• "metadata": {

  • "admin": true,
  • "a": {

    • "nested": {

      • "key": "value"

      }

    }

  }

}

Response samples

• 200
• default

Content type

application/json

{

• "data": [

  • {

    • "timestamp": "2019-08-24T14:15:22Z",
    • "postings": [

      • {

        • "amount": 100,
        • "asset": "COIN",
        • "destination": "users:002",
        • "source": "users:001"

        }

      ],
    • "reference": "ref:001",
    • "metadata": {

      • "admin": true,
      • "a": {

        • "nested": {

          • "key": "value"

          }

        }

      },
    • "txid": 0,
    • "preCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      },
    • "postCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      }

    }

  ]

}

Get transaction from a ledger by its ID

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
txid required	integer <int64> >= 0 Example: 1234 Transaction ID.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/{txid}

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/{txid}

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "timestamp": "2019-08-24T14:15:22Z",
  • "postings": [

    • {

      • "amount": 100,
      • "asset": "COIN",
      • "destination": "users:002",
      • "source": "users:001"

      }

    ],
  • "reference": "ref:001",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "txid": 0,
  • "preCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    },
  • "postCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    }

  }

}

Set the metadata of a transaction by its ID

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
txid required	integer <int64> >= 0 Example: 1234 Transaction ID.

Request Body schema: application/json

metadata

property name* additional property

any

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/{txid}/metadata

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/{txid}/metadata

Request samples

• Payload

Content type

application/json

{

• "admin": true,
• "a": {

  • "nested": {

    • "key": "value"

    }

  }

}

Response samples

• default

Content type

application/json

{

• "errorCode": "INSUFFICIENT_FUND",
• "errorMessage": "[INSUFFICIENT_FUND] account had insufficient funds",
• "details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"

}

Revert a ledger transaction by its ID

Authorizations:

Authorization

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
txid required	integer <int64> >= 0 Example: 1234 Transaction ID.

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/{txid}/revert

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/{txid}/revert

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "timestamp": "2019-08-24T14:15:22Z",
  • "postings": [

    • {

      • "amount": 100,
      • "asset": "COIN",
      • "destination": "users:002",
      • "source": "users:001"

      }

    ],
  • "reference": "ref:001",
  • "metadata": {

    • "admin": true,
    • "a": {

      • "nested": {

        • "key": "value"

        }

      }

    },
  • "txid": 0,
  • "preCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    },
  • "postCommitVolumes": {

    • "orders:1": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      },
    • "orders:2": {

      • "USD": {

        • "input": 100,
        • "output": 10,
        • "balance": 90

        }

      }

    }

  }

}

Create a new batch of transactions to a ledger

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

Request Body schema: application/json

required

required	Array of objects (TransactionData)
Array required Array of objects (Posting) reference string object or null (ledgerMetadata) timestamp string <date-time>

Responses

local server

http://localhost/api/ledger/{ledger}/transactions/batch

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/transactions/batch

Request samples

• Payload

Content type

application/json

{

• "transactions": [

  • {

    • "postings": [

      • {

        • "amount": 100,
        • "asset": "COIN",
        • "destination": "users:002",
        • "source": "users:001"

        }

      ],
    • "reference": "ref:001",
    • "metadata": {

      • "admin": true,
      • "a": {

        • "nested": {

          • "key": "value"

          }

        }

      },
    • "timestamp": "2019-08-24T14:15:22Z"

    }

  ]

}

Response samples

• 200
• default

Content type

application/json

{

• "data": [

  • {

    • "timestamp": "2019-08-24T14:15:22Z",
    • "postings": [

      • {

        • "amount": 100,
        • "asset": "COIN",
        • "destination": "users:002",
        • "source": "users:001"

        }

      ],
    • "reference": "ref:001",
    • "metadata": {

      • "admin": true,
      • "a": {

        • "nested": {

          • "key": "value"

          }

        }

      },
    • "txid": 0,
    • "preCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      },
    • "postCommitVolumes": {

      • "orders:1": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        },
      • "orders:2": {

        • "USD": {

          • "input": 100,
          • "output": 10,
          • "balance": 90

          }

        }

      }

    }

  ]

}

Balances

Get the balances from a ledger's account

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

address	string Example: address=users:001 Filter balances involving given account, either as source or destination.
after	string Example: after=users:003 Pagination cursor, will return accounts after given address, in descending order.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
pagination_token	string Deprecated Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. Deprecated, please use cursor instead.

Responses

local server

http://localhost/api/ledger/{ledger}/balances

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/balances

Response samples

• 200
• default

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "account1": {

        • "USD": 100,
        • "EUR": 23

        },
      • "account2": {

        • "CAD": 20,
        • "JPY": 21

        }

      }

    ]

  }

}

Get the aggregated balances from selected accounts

Authorizations:

Authorization

path Parameters

ledger required

string Example: ledger001 Name of the ledger.

query Parameters

address

string Example: address=users:001 Filter balances involving given account, either as source or destination.

Responses

local server

http://localhost/api/ledger/{ledger}/aggregate/balances

sandbox server

https://{organization}.sandbox.formance.cloud/api/ledger/{ledger}/aggregate/balances

Response samples

• 200
• default

Content type

application/json

{

• "data": {

  • "USD": 100,
  • "EUR": 12

  }

}

Payments

Get server info

Authorizations:

Authorization

Responses

local server

http://localhost/api/payments/_info

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/_info

Response samples

• 200

Content type

application/json

{

• "version": "string"

}

List payments

Authorizations:

Authorization

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
sort	Array of strings Example: sort=date:asc&sort=status:desc Fields used to sort payments (default is date:desc).

Responses

local server

http://localhost/api/payments/payments

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/payments

Response samples

• 200

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "id": "XXX",
      • "reference": "string",
      • "accountID": "string",
      • "type": "PAY-IN",
      • "provider": "STRIPE",
      • "status": "PENDING",
      • "initialAmount": 100,
      • "scheme": "visa",
      • "asset": "USD",
      • "createdAt": "2019-08-24T14:15:22Z",
      • "raw": { },
      • "adjustments": [

        • {

          • "status": "PENDING",
          • "amount": 100,
          • "date": "2019-08-24T14:15:22Z",
          • "raw": { },
          • "absolute": true

          }

        ],
      • "metadata": {

        • "key": "string"

        }

      }

    ]

  }

}

Get a payment

Authorizations:

Authorization

path Parameters

paymentId required

string Example: XXX The payment ID.

Responses

local server

http://localhost/api/payments/payments/{paymentId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/payments/{paymentId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "id": "XXX",
  • "reference": "string",
  • "accountID": "string",
  • "type": "PAY-IN",
  • "provider": "STRIPE",
  • "status": "PENDING",
  • "initialAmount": 100,
  • "scheme": "visa",
  • "asset": "USD",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "raw": { },
  • "adjustments": [

    • {

      • "status": "PENDING",
      • "amount": 100,
      • "date": "2019-08-24T14:15:22Z",
      • "raw": { },
      • "absolute": true

      }

    ],
  • "metadata": {

    • "key": "string"

    }

  }

}

Update metadata

Authorizations:

Authorization

path Parameters

paymentId required

string Example: XXX The payment ID.

Request Body schema: application/json

required

key

string

Responses

local server

http://localhost/api/payments/payments/{paymentId}/metadata

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/payments/{paymentId}/metadata

Request samples

• Payload

Content type

application/json

{

• "key": "string"

}

List accounts

Authorizations:

Authorization

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.
sort	Array of strings Example: sort=date:asc&sort=status:desc Fields used to sort payments (default is date:desc).

Responses

local server

http://localhost/api/payments/accounts

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/accounts

Response samples

• 200

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "id": "string",
      • "createdAt": "2019-08-24T14:15:22Z",
      • "provider": "STRIPE",
      • "reference": "string",
      • "type": "TARGET"

      }

    ]

  }

}

List all installed connectors

List all installed connectors.

Authorizations:

Authorization

Responses

local server

http://localhost/api/payments/connectors

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors

Response samples

• 200

Content type

application/json

{

• "data": [

  • {

    • "provider": "STRIPE",
    • "enabled": true

    }

  ]

}

List the configs of each available connector

List the configs of each available connector.

Authorizations:

Authorization

Responses

local server

http://localhost/api/payments/connectors/configs

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/configs

Response samples

• 200

Content type

application/json

{

• "data": {

  • "connector": {

    • "key": {

      • "dataType": "string",
      • "required": true

      }

    }

  }

}

Install a connector

Install a connector by its name and config.

Authorizations:

Authorization

path Parameters

connector required

string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" The name of the connector.

Request Body schema: application/json

required

Any of

pollingPeriod	string Default: "120s" The frequency at which the connector will try to fetch new BalanceTransaction objects from Stripe API.
apiKey required	string
pageSize	integer <int64> >= 0 Default: 10 Number of BalanceTransaction to fetch at each polling interval.

Responses

local server

http://localhost/api/payments/connectors/{connector}

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/{connector}

Request samples

• Payload

Content type

application/json

Example

StripeConfigDummyPayConfigWiseConfigModulrConfigCurrencyCloudConfigBankingCircleConfigStripeConfig

{

• "pollingPeriod": "60s",
• "apiKey": "XXX",
• "pageSize": 50

}

Uninstall a connector

Uninstall a connector by its name.

Authorizations:

Authorization

path Parameters

connector required

string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" The name of the connector.

Responses

local server

http://localhost/api/payments/connectors/{connector}

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/{connector}

Read the config of a connector

Read connector config

Authorizations:

Authorization

path Parameters

connector required

string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" The name of the connector.

Responses

local server

http://localhost/api/payments/connectors/{connector}/config

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/{connector}/config

Response samples

• 200

Content type

application/json

{

• "data": {

  • "pollingPeriod": "60s",
  • "apiKey": "XXX",
  • "pageSize": 50

  }

}

Reset a connector

Reset a connector by its name. It will remove the connector and ALL PAYMENTS generated with it.

Authorizations:

Authorization

path Parameters

connector required

string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" The name of the connector.

Responses

local server

http://localhost/api/payments/connectors/{connector}/reset

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/{connector}/reset

List tasks from a connector

List all tasks associated with this connector.

Authorizations:

Authorization

path Parameters

connector required

string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" The name of the connector.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page.
cursor	string Example: cursor=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ== Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set.

Responses

local server

http://localhost/api/payments/connectors/{connector}/tasks

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/{connector}/tasks

Response samples

• 200

Content type

application/json

{

• "cursor": {

  • "pageSize": 15,
  • "hasMore": false,
  • "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
  • "next": "",
  • "data": [

    • {

      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "connectorId": "7200b21f-cb26-4f4f-9504-421d49021e96",
      • "createdAt": "2019-08-24T14:15:22Z",
      • "updatedAt": "2019-08-24T14:15:22Z",
      • "status": "PENDING",
      • "state": { },
      • "error": "string",
      • "descriptor": {

        • "name": "string",
        • "main": true,
        • "account": "string"

        }

      }

    ]

  }

}

Read a specific task of the connector

Get a specific task associated to the connector.

Authorizations:

Authorization

path Parameters

connector required	string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" The name of the connector.
taskId required	string Example: task1 The task ID.

Responses

local server

http://localhost/api/payments/connectors/{connector}/tasks/{taskId}

sandbox server

https://{organization}.sandbox.formance.cloud/api/payments/connectors/{connector}/tasks/{taskId}

Response samples

• 200

Content type

application/json

{

• "data": {

  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connectorId": "7200b21f-cb26-4f4f-9504-421d49021e96",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "PENDING",
  • "state": { },
  • "error": "string",
  • "descriptor":