Formance Stack API (INTERNAL)

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: https://localhost/api/auth/oauth/token

Refresh URL: https://localhost/api/auth/oauth/token

Clients

List clients

Responses

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
]
}

Create client

Request Body schema: application/json

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

Responses

Request samples

Payload

Content type

application/json

{"public": true,
"redirectUris": ["string"
],
"description": "string",
"name": "string",
"trusted": true,
"postLogoutRedirectUris": ["string"
],
"metadata": {"property1": null,
"property2": null
},
"scopes": ["string"
]
}

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
}

Read client

path Parameters

clientId

required

string

Client ID

Responses

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
}

Update client

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)
scopes	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"public": true,
"redirectUris": ["string"
],
"description": "string",
"name": "string",
"trusted": true,
"postLogoutRedirectUris": ["string"
],
"metadata": {"property1": null,
"property2": null
},
"scopes": ["string"
]
}

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
}

Delete client

path Parameters

clientId

required

string

Client ID

Responses

Add a secret to a client

path Parameters

clientId

required

string

Client ID

Request Body schema: application/json

name required	string
	object (Metadata)

Responses

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

path Parameters

clientId required	string Client ID
secretId required	string Secret ID

Responses

Users

List users

Responses

Response samples

200

Content type

application/json

{"data": [{"id": "3bb03708-312f-48a0-821a-e765837dc2c4",
"subject": "Jane Doe",
"email": "user1@orga1.com"
}
]
}

Read user

path Parameters

userId

required

string

User ID

Responses

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

Responses

Response samples

200

Content type

application/json

{"version": "string"
}

List clients

Responses

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
]
}

Create client

Request Body schema: application/json

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

Responses

Request samples

Payload

Content type

application/json

{"public": true,
"redirectUris": ["string"
],
"description": "string",
"name": "string",
"trusted": true,
"postLogoutRedirectUris": ["string"
],
"metadata": {"property1": null,
"property2": null
},
"scopes": ["string"
]
}

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
}

Read client

path Parameters

clientId

required

string

Client ID

Responses

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
}

Update client

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)
scopes	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"public": true,
"redirectUris": ["string"
],
"description": "string",
"name": "string",
"trusted": true,
"postLogoutRedirectUris": ["string"
],
"metadata": {"property1": null,
"property2": null
},
"scopes": ["string"
]
}

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
},
"scopes": ["string"
],
"id": "string",
"secrets": [{"lastDigits": "string",
"name": "string",
"id": "string",
"metadata": {"property1": null,
"property2": null
}
}
]
}
}

Delete client

path Parameters

clientId

required

string

Client ID

Responses

Add a secret to a client

path Parameters

clientId

required

string

Client ID

Request Body schema: application/json

name required	string
	object (Metadata)

Responses

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

path Parameters

clientId required	string Client ID
secretId required	string Secret ID

Responses

List users

Responses

Response samples

200

Content type

application/json

{"data": [{"id": "3bb03708-312f-48a0-821a-e765837dc2c4",
"subject": "Jane Doe",
"email": "user1@orga1.com"
}
]
}

Read user

path Parameters

userId

required

string

User ID

Responses

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

Responses

Response samples

200
default

Content type

application/json

{"data": {"config": {"storage": {"driver": "string",
"ledgers": ["string"
]
}
},
"server": "string",
"version": "string"
}
}

Get information about a ledger

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Responses

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

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 $).
	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

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.

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 $).
	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

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

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

Response samples

200
default

Content type

application/json

{"data": {"address": "users:001",
"type": "virtual",
"metadata": {"admin": true,
"a": {"nested": {"key": "value"
}
}
},
"volumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"balances": {"COIN": 100
}
}
}

Add metadata to an account

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

Request samples

Payload

Content type

application/json

{"property1": null,
"property2": null
}

Response samples

400
404
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

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Responses

Response samples

200
default

Content type

application/json

{"data": {"contracts": [{"account": "users:001",
"expr": { }
}
]
}
}

Update the mapping of a ledger

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

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.

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
	object
reference	string Reference to attach to the generated transaction
	object or null (Metadata1)

Responses

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": {"property1": null,
"property2": null
}
}

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": {"property1": null,
"property2": null
},
"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)

path Parameters

ledger

required

string

Example: ledger001

name of the ledger

Responses

Response samples

200
default

Content type

application/json

{"data": {"accounts": 0,
"transactions": 0
}
}

Count the transactions from a ledger

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

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.

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.
	object Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

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": {"property1": null,
"property2": null
},
"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

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 (Metadata1)

Responses

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": {"property1": null,
"property2": null
}
}

Response samples

200
400
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": {"property1": null,
"property2": null
},
"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

path Parameters

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

Responses

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": {"property1": null,
"property2": null
},
"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

path Parameters

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

Request Body schema: application/json

metadata

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"property1": null,
"property2": null
}

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

path Parameters

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

query Parameters

disableChecks

boolean

Allow to disable balances checks

Responses

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": {"property1": null,
"property2": null
},
"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

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 (Metadata1)
timestamp	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"transactions": [{"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"property1": null,
"property2": null
},
"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": {"property1": null,
"property2": null
},
"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

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

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

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

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.

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

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"
}
]
}
}

Show server information

Responses

Response samples

200
default

Content type

application/json

{"server": "string",
"version": "string"
}

List ledgers

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] 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

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"name": "string",
"addedAt": "2019-08-24T14:15:22Z",
"bucket": "string"
}
]
}
}

Get a ledger

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Responses

Response samples

200
default

Content type

application/json

{"name": "string",
"addedAt": "2019-08-24T14:15:22Z",
"bucket": "string"
}

Create a ledger

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Request Body schema: application/json

bucket

string

Responses

Request samples

Payload

Content type

application/json

{"bucket": "string"
}

Response samples

400
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

Get information about a ledger

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Responses

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"
}
]
}
}
}

Bulk request

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Request Body schema: application/json

Array

action required	string CREATE_TRANSACTION
ik	string
	object (V2PostTransaction)

Responses

Request samples

Payload

Content type

application/json

[{"action": "string",
"ik": "string",
"data": {"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"
}
}
}
]

Response samples

200
400
default

Content type

application/json

{"data": [{"responseType": "string",
"data": {"timestamp": "2019-08-24T14:15:22Z",
"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"admin": "true"
},
"id": 0,
"reverted": true
}
}
]
}

Count the accounts from a ledger

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

pit	string <date-time>

Request Body schema: application/json

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

List accounts from a ledger

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

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] 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.
expand	string
pit	string <date-time>

Request Body schema: application/json

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"address": "users:001",
"metadata": {"admin": "true"
},
"volumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"effectiveVolumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
}
}
]
}
}

Get account by its address

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+)*$`

query Parameters

expand	string
pit	string <date-time>

Responses

Response samples

200
default

Content type

application/json

{"data": {"address": "users:001",
"metadata": {"admin": "true"
},
"volumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"effectiveVolumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
}
}
}

Add metadata to an account

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+)*$`

query Parameters

dryRun

boolean

Example: dryRun=true

Set the dry run mode. Dry run mode doesn't add the logs to the database or publish a message to the message broker.

header Parameters

Idempotency-Key

string

Use an idempotency key

Request Body schema: application/json
required

metadata

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"admin": "true"
}

Response samples

400
404
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

Delete metadata by key

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
address required	string Account address
key required	string Example: foo The key to remove.

Responses

Get statistics from a ledger

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

path Parameters

ledger

required

string

Example: ledger001

name of the ledger

Responses

Response samples

200
default

Content type

application/json

{"data": {"accounts": 0,
"transactions": 0
}
}

Count the transactions from a ledger

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

pit	string <date-time>

Request Body schema: application/json

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

List transactions from a ledger

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

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] 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.
expand	string
pit	string <date-time>

Request Body schema: application/json

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
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"
},
"id": 0,
"reverted": true,
"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

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

dryRun

boolean

Example: dryRun=true

Set the dryRun mode. dry run mode doesn't add the logs to the database or publish a message to the message broker.

header Parameters

Idempotency-Key

string

Use an idempotency key

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 (V2Posting)
	object
reference	string
required	object (V2Metadata)

Responses

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"
}
}

Response samples

200
400
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"
},
"id": 0,
"reverted": true
}
}

Get transaction from a ledger by its ID

path Parameters

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

query Parameters

expand	string
pit	string <date-time>

Responses

Response samples

200
404
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"
},
"id": 0,
"reverted": true,
"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

path Parameters

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

query Parameters

dryRun

boolean

Example: dryRun=true

Set the dryRun mode. Dry run mode doesn't add the logs to the database or publish a message to the message broker.

header Parameters

Idempotency-Key

string

Use an idempotency key

Request Body schema: application/json

metadata

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"admin": "true"
}

Response samples

400
404
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

Delete metadata by key

path Parameters

ledger required	string Example: ledger001 Name of the ledger.
id required	integer <bigint> >= 0 Example: 1234 Transaction ID.
key required	string Example: foo The key to remove.

Responses

Response samples

400
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

Revert a ledger transaction by its ID

path Parameters

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

query Parameters

force

boolean

Force revert

Responses

Response samples

201
400
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"
},
"id": 0,
"reverted": true
}
}

Get the aggregated balances from selected accounts

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

pit	string <date-time>

Request Body schema: application/json

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

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.

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] 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.
pit	string <date-time>

Request Body schema: application/json

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

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

Responses

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

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 $).
	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

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.

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 $).
	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

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

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

Response samples

200
default

Content type

application/json

{"data": {"address": "users:001",
"type": "virtual",
"metadata": {"admin": true,
"a": {"nested": {"key": "value"
}
}
},
"volumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"balances": {"COIN": 100
}
}
}

Add metadata to an account

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

Request samples

Payload

Content type

application/json

{"property1": null,
"property2": null
}

Response samples

400
404
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

path Parameters

ledger

required

string

Example: ledger001

Name of the ledger.

Responses

Response samples

200
default

Content type

application/json

{"data": {"contracts": [{"account": "users:001",
"expr": { }
}
]
}
}

Update the mapping of a ledger

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

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.

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
	object
reference	string Reference to attach to the generated transaction
	object or null (Metadata1)

Responses

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": {"property1": null,
"property2": null
}
}

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": {"property1": null,
"property2": null
},
"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)

path Parameters

ledger

required

string

Example: ledger001

name of the ledger

Responses

Response samples

200
default

Content type

application/json

{"data": {"accounts": 0,
"transactions": 0
}
}

Transactions

Count the transactions from a ledger

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

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.

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.
	object Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

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": {"property1": null,
"property2": null
},
"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

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 (Metadata1)

Responses

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": {"property1": null,
"property2": null
}
}

Response samples

200
400
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": {"property1": null,
"property2": null
},
"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

path Parameters

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

Responses

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": {"property1": null,
"property2": null
},
"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

path Parameters

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

Request Body schema: application/json

metadata

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"property1": null,
"property2": null
}

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

path Parameters

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

query Parameters

disableChecks

boolean

Allow to disable balances checks

Responses

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": {"property1": null,
"property2": null
},
"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

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 (Metadata1)
timestamp	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"transactions": [{"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"property1": null,
"property2": null
},
"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": {"property1": null,
"property2": null
},
"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

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

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

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

Response samples

200
default

Content type

application/json

{"data": {"USD": 100,
"EUR": 12
}
}

Payments

Get server info

Responses

Response samples

200

Content type

application/json

{"version": "string"
}

Create a payment

Request Body schema: application/json
required

reference required	string
connectorID required	string
createdAt required	string <date-time>
amount required	integer <bigint> >= 0
type required	string (PaymentType) Enum: "PAY-IN" "PAYOUT" "TRANSFER" "OTHER"
status required	string (PaymentStatus) Enum: "PENDING" "SUCCEEDED" "CANCELLED" "FAILED" "EXPIRED" "REFUNDED" "OTHER"
scheme required	string (PaymentScheme) Enum: "unknown" "other" "visa" "mastercard" "amex" "diners" "discover" "jcb" "unionpay" "alipay" "cup" "sepa debit" "sepa credit" "sepa" "apple pay" "google pay" "doku" "dragonpay" "maestro" "molpay" "a2a" "ach debit" "ach" "rtp"
asset required	string
sourceAccountID	string
destinationAccountID	string

Responses

Request samples

Payload

Content type

application/json

{"reference": "string",
"connectorID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"amount": 100,
"type": "PAY-IN",
"status": "PENDING",
"scheme": "unknown",
"asset": "USD",
"sourceAccountID": "string",
"destinationAccountID": "string"
}

Response samples

200

Content type

application/json

{"data": {"id": "XXX",
"reference": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"provider": "STRIPE",
"type": "PAY-IN",
"status": "PENDING",
"initialAmount": 100,
"amount": 100,
"scheme": "unknown",
"asset": "USD",
"createdAt": "2019-08-24T14:15:22Z",
"raw": { },
"adjustments": [{"status": "PENDING",
"amount": 100,
"date": "2019-08-24T14:15:22Z",
"raw": { },
"absolute": true
}
],
"metadata": {"property1": "string",
"property2": "string"
}
}
}

List payments

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

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "XXX",
"reference": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"provider": "STRIPE",
"type": "PAY-IN",
"status": "PENDING",
"initialAmount": 100,
"amount": 100,
"scheme": "unknown",
"asset": "USD",
"createdAt": "2019-08-24T14:15:22Z",
"raw": { },
"adjustments": [{"status": "PENDING",
"amount": 100,
"date": "2019-08-24T14:15:22Z",
"raw": { },
"absolute": true
}
],
"metadata": {"property1": "string",
"property2": "string"
}
}
]
}
}

Get a payment

path Parameters

paymentId

required

string

Example: XXX

The payment ID.

Responses

Response samples

200

Content type

application/json

{"data": {"id": "XXX",
"reference": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"provider": "STRIPE",
"type": "PAY-IN",
"status": "PENDING",
"initialAmount": 100,
"amount": 100,
"scheme": "unknown",
"asset": "USD",
"createdAt": "2019-08-24T14:15:22Z",
"raw": { },
"adjustments": [{"status": "PENDING",
"amount": 100,
"date": "2019-08-24T14:15:22Z",
"raw": { },
"absolute": true
}
],
"metadata": {"property1": "string",
"property2": "string"
}
}
}

Update metadata

path Parameters

paymentId

required

string

Example: XXX

The payment ID.

Request Body schema: application/json
required

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"property1": "string",
"property2": "string"
}

List Transfer Initiations

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).
query	string Filters used to filter resources.

Responses

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "XXX",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"scheduledAt": "2019-08-24T14:15:22Z",
"description": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"type": "TRANSFER",
"amount": 0,
"asset": "USD",
"status": "WAITING_FOR_VALIDATION",
"error": "string",
"relatedPayments": [{"paymentID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"status": "PENDING",
"error": "string"
}
]
}
]
}
}

Create a TransferInitiation

Create a transfer initiation

Request Body schema: application/json
required

reference required	string
scheduledAt required	string <date-time>
description required	string
sourceAccountID required	string
destinationAccountID required	string
connectorID	string
provider	string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"
type required	string Enum: "TRANSFER" "PAYOUT"
amount required	integer <bigint>
asset required	string
validated required	boolean

Responses

Request samples

Payload

Content type

application/json

{"reference": "XXX",
"scheduledAt": "2019-08-24T14:15:22Z",
"description": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"provider": "STRIPE",
"type": "TRANSFER",
"amount": 0,
"asset": "USD",
"validated": true
}

Response samples

200

Content type

application/json

{"data": {"id": "XXX",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"scheduledAt": "2019-08-24T14:15:22Z",
"description": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"type": "TRANSFER",
"amount": 0,
"asset": "USD",
"status": "WAITING_FOR_VALIDATION",
"error": "string",
"relatedPayments": [{"paymentID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"status": "PENDING",
"error": "string"
}
]
}
}

Get a transfer initiation

path Parameters

transferId

required

string

Example: XXX

The transfer ID.

Responses

Response samples

200

Content type

application/json

{"data": {"id": "XXX",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"scheduledAt": "2019-08-24T14:15:22Z",
"description": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"type": "TRANSFER",
"amount": 0,
"asset": "USD",
"status": "WAITING_FOR_VALIDATION",
"error": "string",
"relatedPayments": [{"paymentID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"status": "PENDING",
"error": "string"
}
]
}
}

Delete a transfer initiation

Delete a transfer initiation by its id.

path Parameters

transferId

required

string

Example: XXX

The transfer ID.

Responses

Update the status of a transfer initiation

Update a transfer initiation status

path Parameters

transferId

required

string

Example: XXX

The transfer ID.

Request Body schema: application/json
required

status

required

string

Enum: "WAITING_FOR_VALIDATION" "PROCESSING" "PROCESSED" "FAILED" "REJECTED" "VALIDATED"

Responses

Request samples

Payload

Content type

application/json

{"status": "WAITING_FOR_VALIDATION"
}

Retry a failed transfer initiation

path Parameters

transferId

required

string

Example: XXX

The transfer ID.

Responses

List Pools

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).
query	string Filters used to filter resources.

Responses

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "string",
"name": "string",
"accounts": ["string"
]
}
]
}
}

Create a Pool

Request Body schema: application/json
required

name required	string
accountIDs required	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"accountIDs": ["string"
]
}

Response samples

200

Content type

application/json

{"data": {"id": "string",
"name": "string",
"accounts": ["string"
]
}
}

Get a Pool

path Parameters

poolId

required

string

Example: XXX

The pool ID.

Responses

Response samples

200

Content type

application/json

{"data": {"id": "string",
"name": "string",
"accounts": ["string"
]
}
}

Delete a Pool

Delete a pool by its id.

path Parameters

poolId

required

string

Example: XXX

The pool ID.

Responses

Add an account to a pool

path Parameters

poolId

required

string

Example: XXX

The pool ID.

Request Body schema: application/json
required

accountID

required

string

Responses

Request samples

Payload

Content type

application/json

{"accountID": "string"
}

Remove an account from a pool

Remove an account from a pool by its id.

path Parameters

poolId required	string Example: XXX The pool ID.
accountId required	string Example: XXX The account ID.

Responses

Get pool balances

path Parameters

poolId

required

string

Example: XXX

The pool ID.

query Parameters

at

required

string <date-time>

Filter balances by date.

Responses

Response samples

200

Content type

application/json

{"data": {"balances": [{"amount": 100,
"asset": "USD"
}
]
}
}

List accounts

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

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"reference": "string",
"connectorID": "string",
"defaultCurrency": "string",
"defaultAsset": "string",
"accountName": "string",
"type": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"raw": { }
}
]
}
}

Get an account

path Parameters

accountId

required

string

Example: XXX

The account ID.

Responses

Response samples

200

Content type

application/json

{"data": {"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"reference": "string",
"connectorID": "string",
"defaultCurrency": "string",
"defaultAsset": "string",
"accountName": "string",
"type": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"raw": { }
}
}

Get account balances

path Parameters

accountId

required

string

Example: XXX

The account ID.

query Parameters

limit	integer <int64> The maximum number of results to return per page.
asset	string Filter balances by currency. If not specified, all account's balances will be returned.
from	string <date-time> Filter balances by date. If not specified, all account's balances will be returned.
to	string <date-time> Filter balances by date. If not specified, default will be set to now.
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

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"accountId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"lastUpdatedAt": "2019-08-24T14:15:22Z",
"currency": "string",
"asset": "string",
"balance": 0
}
]
}
}

Create a BankAccount in Payments and on the PSP

Create a bank account in Payments and on the PSP.

Request Body schema: application/json
required

country required	string
connectorID required	string
name required	string
accountNumber	string
iban	string
swiftBicCode	string
	object or null (BankAccountMetadata)

Responses

Request samples

Payload

Content type

application/json

{"country": "GB",
"connectorID": "string",
"name": "My account",
"accountNumber": "string",
"iban": "string",
"swiftBicCode": "string",
"metadata": {"property1": "string",
"property2": "string"
}
}

Response samples

200

Content type

application/json

{"data": {"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"country": "string",
"connectorID": "string",
"provider": "string",
"iban": "string",
"accountNumber": "string",
"swiftBicCode": "string",
"metadata": {"property1": "string",
"property2": "string"
}
}
}

List bank accounts created by user on Formance

List all bank accounts created by user on Formance.

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

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"country": "string",
"connectorID": "string",
"provider": "string",
"iban": "string",
"accountNumber": "string",
"swiftBicCode": "string",
"metadata": {"property1": "string",
"property2": "string"
}
}
]
}
}

Get a bank account created by user on Formance

path Parameters

bankAccountId

required

string

Example: XXX

The bank account ID.

Responses

Response samples

200

Content type

application/json

{"data": {"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"country": "string",
"connectorID": "string",
"provider": "string",
"iban": "string",
"accountNumber": "string",
"swiftBicCode": "string",
"metadata": {"property1": "string",
"property2": "string"
}
}
}

List all installed connectors

List all installed connectors.

Responses

Response samples

200

Content type

application/json

{"data": [{"provider": "STRIPE",
"name": "string",
"connectorID": "string",
"enabled": true
}
]
}

List the configs of each available connector

List the configs of each available connector.

Responses

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.

path Parameters

connector

required

string (Connector)

Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"

The name of the connector.

Request Body schema: application/json
required

Any of

name required	string
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

Request samples

Payload

Content type

application/json

Example

StripeConfig

{"name": "My Stripe Account",
"pollingPeriod": "60s",
"apiKey": "XXX",
"pageSize": 50
}

Response samples

201

Content type

application/json

{"data": {"connectorID": "string"
}
}

Uninstall a connector Deprecated

Uninstall a connector by its name.

path Parameters

connector

required

string (Connector)

Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"

The name of the connector.

Responses

Uninstall a connector

Uninstall a connector by its name.

path Parameters

connector required	string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN" The name of the connector.
connectorId required	string Example: XXX The connector ID.

Responses

Read the config of a connector Deprecated

Read connector config

path Parameters

connector

required

string (Connector)

Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"

The name of the connector.

Responses

Response samples

200

Content type

application/json

{"data": {"name": "My Stripe Account",
"pollingPeriod": "60s",
"apiKey": "XXX",
"pageSize": 50
}
}

Read the config of a connector

Read connector config

path Parameters

connector required	string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN" The name of the connector.
connectorId required	string Example: XXX The connector ID.

Responses

Response samples

200

Content type

application/json

{"data": {"name": "My Stripe Account",
"pollingPeriod": "60s",
"apiKey": "XXX",
"pageSize": 50
}
}

Reset a connector Deprecated

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

path Parameters

connector

required

string (Connector)

Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"

The name of the connector.

Responses

Reset a connector

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

path Parameters

connector required	string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN" The name of the connector.
connectorId required	string Example: XXX The connector ID.

Responses

List tasks from a connector Deprecated

List all tasks associated with this connector.

path Parameters

connector

required

string (Connector)

Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"

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

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"connectorID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "PENDING",
"state": { },
"error": "string",
"descriptor": {"name": "string",
"main": true,
"account": "string"
}
}
]
}
}

List tasks from a connector

List all tasks associated with this connector.

path Parameters

connector required	string (Connector) Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN" The name of the connector.
connectorId required	string Example: XXX The connector ID.

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

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"connectorID": "string",
"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 Deprecated

Get a specific task associated to the connector.

path Parameters

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

Responses

Response samples

200

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"connectorID": "string",
"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.

path Parameters

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

Responses

Response samples

200

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"connectorID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "PENDING",
"state": { },
"error": "string",
"descriptor": {"name": "string",
"main": true,
"account": "string"
}
}
}

Transfer funds between Connector accounts

Execute a transfer between two accounts.

path Parameters

connector

required

string (Connector)

Enum: "STRIPE" "DUMMY-PAY" "WISE" "MODULR" "CURRENCY-CLOUD" "BANKING-CIRCLE" "MANGOPAY" "MONEYCORP" "ATLAR" "ADYEN"

The name of the connector.

Request Body schema: application/json
required

amount required	integer <bigint> >= 0
asset required	string
destination required	string
source	string

Responses

Request samples

Payload

Content type

application/json

{"amount": 100,
"asset": "USD",
"destination": "acct_1Gqj58KZcSIg2N2q",
"source": "acct_1Gqj58KZcSIg2N2q"
}

Response samples

200

Content type

application/json

{"id": "string"
}

Search

Get server info

Responses

Response samples

200

Content type

application/json

{"version": "string"
}

Search

ElasticSearch query engine

Request Body schema: application/json
required

ledgers	Array of strings
after	Array of strings
pageSize	integer <int64> >= 0
terms	Array of strings
sort	string
policy	string
target	string
cursor	string
raw	object

Responses

Request samples

Payload

Content type

application/json

{"ledgers": ["quickstart"
],
"after": ["users:002"
],
"pageSize": 0,
"terms": ["destination=central_bank1"
],
"sort": "id:asc",
"policy": "OR",
"target": "string",
"cursor": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"raw": {"query": {"match_all": { }
}
}
}

Response samples

200

Content type

application/json

{"data": { },
"cursor": {"pageSize": 0,
"hasMore": true,
"total": {"value": 1,
"relation": "eq"
},
"next": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"data": [{ }
]
}
}

Wallets

Get server info

Responses

Response samples

200
default

Content type

application/json

{"version": "string"
}

getTransactions

query Parameters

pageSize	integer [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page
walletID	string Example: walletID=wallet1 A wallet ID to filter on
cursor	string Example: cursor=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. No other parameters can be set when the cursor is set.

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"ledger": "string",
"timestamp": "2019-08-24T14:15:22Z",
"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"property1": "string",
"property2": "string"
},
"id": 0,
"preCommitVolumes": {"property1": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"property2": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
}
},
"postCommitVolumes": {"property1": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"property2": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
}
}
}
]
}
}

List all wallets

query Parameters

name	string Example: name=wallet1 Filter on wallet name
metadata	object Example: metadata[admin]=true Filter wallets by metadata key value pairs. Nested objects can be used as seen in the example below.
pageSize	integer [ 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. 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 the pagination token is set.

Responses

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"metadata": {"property1": "string",
"property2": "string"
},
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"ledger": "string"
}
]
}
}

Create a new wallet

Request Body schema: application/json

required	object Custom metadata to attach to this wallet.
name required	string

Responses

Request samples

Payload

Content type

application/json

{"metadata": {"property1": "string",
"property2": "string"
},
"name": "string"
}

Response samples

201
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"metadata": {"property1": "string",
"property2": "string"
},
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"ledger": "string"
}
}

Get a wallet

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"metadata": {"property1": "string",
"property2": "string"
},
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"balances": {"main": {"assets": {"property1": 0,
"property2": 0
}
}
},
"ledger": "string"
}
}

Update a wallet

path Parameters

id

required

string

Request Body schema: application/json

required

object

Custom metadata to attach to this wallet.

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"metadata": {"property1": "string",
"property2": "string"
}
}

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Get wallet summary

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"balances": [{"name": "string",
"expiresAt": "2019-08-24T14:15:22Z",
"priority": 0,
"assets": {"property1": 0,
"property2": 0
}
}
],
"availableFunds": {"property1": 0,
"property2": 0
},
"expiredFunds": {"property1": 0,
"property2": 0
},
"expirableFunds": {"property1": 0,
"property2": 0
},
"holdFunds": {"property1": 0,
"property2": 0
}
}

List balances of a wallet

path Parameters

id

required

string

Responses

Response samples

200

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"name": "string",
"expiresAt": "2019-08-24T14:15:22Z",
"priority": 0
}
]
}
}

Create a balance

path Parameters

id

required

string

Request Body schema: application/json

name required	string
expiresAt	string <date-time>
priority	integer <bigint>

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"expiresAt": "2019-08-24T14:15:22Z",
"priority": 0
}

Response samples

201
default

Content type

application/json

{"data": {"name": "string",
"expiresAt": "2019-08-24T14:15:22Z",
"priority": 0
}
}

Get detailed balance

path Parameters

id required	string
balanceName required	string

Responses

Response samples

200
default

Content type

application/json

{"data": {"name": "string",
"expiresAt": "2019-08-24T14:15:22Z",
"priority": 0,
"assets": {"property1": 0,
"property2": 0
}
}
}

Debit a wallet

path Parameters

id

required

string

Request Body schema: application/json

required	object (Monetary)
pending	boolean Set to true to create a pending hold. If false, the wallet will be debited immediately.
required	object Metadata associated with the wallet.
description	string
	any (Subject)
balances	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"amount": {"asset": "USD/2",
"amount": 100
},
"metadata": {"key": ""
},
"pending": true
}

Response samples

201
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"walletID": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"description": "string",
"destination": {"type": "string",
"identifier": "string"
}
}
}

Credit a wallet

path Parameters

id

required

string

Request Body schema: application/json

required	object (Monetary)
required	object Metadata associated with the wallet.
reference	string
required	Array of any (Subject)
balance	string The balance to credit

Responses

Request samples

Payload

Content type

application/json

{"amount": {"asset": "USD/2",
"amount": 100
},
"metadata": {"key": ""
},
"sources": [ ]
}

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Get all holds for a wallet

query Parameters

pageSize	integer [ 1 .. 1000 ] Default: 15 Example: pageSize=100 The maximum number of results to return per page
walletID	string Example: walletID=wallet1 The wallet to filter on
metadata	object Example: metadata[admin]=true Filter holds by metadata key value pairs. Nested objects can be used as seen in the example below.
cursor	string Example: cursor=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. No other parameters can be set when the pagination token is set.

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"walletID": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"description": "string",
"destination": {"type": "string",
"identifier": "string"
}
}
]
}
}

Get a hold

path Parameters

holdID

required

string

The hold ID

Responses

Response samples

200
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"walletID": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"description": "string",
"destination": {"type": "string",
"identifier": "string"
},
"remaining": 10,
"originalAmount": 100
}
}

Confirm a hold

path Parameters

hold_id

required

string

Request Body schema: application/json

amount	integer <bigint> Define the amount to transfer.
final	boolean Define a final confirmation. Remaining funds will be returned to the wallet.

Responses

Request samples

Payload

Content type

application/json

{"amount": 100,
"final": true
}

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Cancel a hold

path Parameters

hold_id

required

string

Responses

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Webhooks

Get many configs

Sorted by updated date descending

query Parameters

id	string Example: id=4997257d-dfb6-445b-929c-cbe2ab182818 Optional filter by Config ID
endpoint	string Example: endpoint=https://example.com Optional filter by endpoint URL

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"hasMore": false,
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}

Insert a new config

Insert a new webhooks config.

The endpoint should be a valid https URL and be unique.

The secret is the endpoint's verification secret. If not passed or empty, a secret is automatically generated. The format is a random string of bytes of size 24, base64 encoded. (larger size after encoding)

All eventTypes are converted to lower-case when inserted.

Request Body schema: application/json
required

endpoint required	string
secret	string
eventTypes required	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
]
}

Response samples

200
400
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Delete one config

Delete a webhooks config by ID.

path Parameters

id

required

string

Example: 4997257d-dfb6-445b-929c-cbe2ab182818

Config ID

Responses

Response samples

400
404
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "[VALIDATION] invalid 'cursor' query param",
"details": "https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9"
}

Test one config

Test a config by sending a webhook to its endpoint.

path Parameters

id

required

string

Example: 4997257d-dfb6-445b-929c-cbe2ab182818

Config ID

Responses

Response samples

200
400
404
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"webhookID": "ed6f2707-2d7c-4644-ad05-94c5b6604899",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"config": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"payload": "{\"data\":\"test\"}",
"statusCode": 200,
"retryAttempt": 1,
"status": "success",
"nextRetryAfter": "2019-08-24T14:15:22Z"
}
}

Activate one config

Activate a webhooks config by ID, to start receiving webhooks to its endpoint.

path Parameters

id

required

string

Example: 4997257d-dfb6-445b-929c-cbe2ab182818

Config ID

Responses

Response samples

200
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Deactivate one config

Deactivate a webhooks config by ID, to stop receiving webhooks to its endpoint.

path Parameters

id

required

string

Example: 4997257d-dfb6-445b-929c-cbe2ab182818

Config ID

Responses

Response samples

200
404
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Change the signing secret of a config

Change the signing secret of the endpoint of a webhooks config.

If not passed or empty, a secret is automatically generated. The format is a random string of bytes of size 24, base64 encoded. (larger size after encoding)

path Parameters

id

required

string

Example: 4997257d-dfb6-445b-929c-cbe2ab182818

Config ID

Request Body schema: application/json

secret

required

string

Responses

Request samples

Payload

Content type

application/json

{"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3"
}

Response samples

200
400
default

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"endpoint": "https://example.com",
"secret": "V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3",
"eventTypes": ["TYPE1",
"TYPE2"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Orchestration

Get server info

Responses

Response samples

200
default

Content type

application/json

{"version": "string"
}

List triggers

Responses

Response samples

200
default

Content type

application/json

{"data": [{"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { },
"id": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

Create trigger

Request Body schema: application/json

event required	string
workflowID required	string
filter	string
	object

Responses

Request samples

Payload

Content type

application/json

{"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { }
}

Response samples

201
default

Content type

application/json

{"data": {"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { },
"id": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Read trigger

path Parameters

triggerID

required

string

The trigger id

Responses

Response samples

200
default

Content type

application/json

{"data": {"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { },
"id": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Delete trigger

Read trigger

path Parameters

triggerID

required

string

The trigger id

Responses

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

List triggers occurrences

path Parameters

triggerID

required

string

The trigger id

Responses

Response samples

200
default

Content type

application/json

{"data": [{"date": "2019-08-24T14:15:22Z",
"workflowInstanceID": "string",
"triggerID": "string",
"event": { }
}
]
}

List registered workflows

Responses

Response samples

200
default

Content type

application/json

{"data": [{"config": {"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": "string"
}
]
}

Create workflow

Create a workflow

Request Body schema: application/json

name	string
required	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
}

Response samples

201
default

Content type

application/json

{"data": {"config": {"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": "string"
}
}

Get a flow by id

path Parameters

flowId

required

string

Example: xxx

The flow id

Responses

Response samples

200
default

Content type

application/json

{"data": {"config": {"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": "string"
}
}

Delete a flow by id

path Parameters

flowId

required

string

Example: xxx

The flow id

Responses

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Run workflow

path Parameters

workflowID

required

string

Example: xxx

The flow id

query Parameters

wait	boolean Wait end of the workflow before return

Request Body schema: application/json

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"property1": "string",
"property2": "string"
}

Response samples

201
default

Content type

application/json

{"data": {"workflowID": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": [{"stage": 0,
"instanceID": "string",
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
],
"terminated": true,
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
}

List instances of a workflow

query Parameters

workflowID	string Example: workflowID=xxx A workflow id
running	boolean Example: running=true Filter running instances

Responses

Response samples

200
default

Content type

application/json

{"data": [{"workflowID": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": [{"stage": 0,
"instanceID": "string",
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
],
"terminated": true,
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
]
}

Get a workflow instance by id

path Parameters

instanceID

required

string

Example: xxx

The instance id

Responses

Response samples

200
default

Content type

application/json

{"data": {"workflowID": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": [{"stage": 0,
"instanceID": "string",
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
],
"terminated": true,
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
}

Send an event to a running workflow

path Parameters

instanceID

required

string

Example: xxx

The instance id

Request Body schema: application/json

name

required

string

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Cancel a running workflow

path Parameters

instanceID

required

string

Example: xxx

The instance id

Responses

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Get a workflow instance history by id

path Parameters

instanceID

required

string

Example: xxx

The instance id

Responses

Response samples

200
default

Content type

application/json

{"data": [{"name": "string",
"input": {"amount": {"asset": "string",
"amount": 0
},
"destination": {"wallet": {"id": "string",
"balance": "string"
},
"account": {"id": "string",
"ledger": "string"
},
"payment": {"psp": "string"
}
},
"source": {"wallet": {"id": "string",
"balance": "string"
},
"account": {"id": "string",
"ledger": "string"
},
"payment": {"id": "string"
}
}
},
"error": "string",
"terminated": true,
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z"
}
]
}

Get a workflow instance stage history

path Parameters

instanceID required	string Example: xxx The instance id
number required	integer The stage number

Responses

Response samples

200
default

Content type

application/json

{"data": [{"name": "string",
"input": {"GetAccount": {"id": "string",
"ledger": "string"
},
"CreateTransaction": {"ledger": "string",
"data": {"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"
}
}
},
"RevertTransaction": {"ledger": "string",
"id": "string"
},
"StripeTransfer": {"connectorID": "string",
"amount": 100,
"asset": "USD",
"destination": "acct_1Gqj58KZcSIg2N2q",
"waitingValidation": false,
"metadata": {"order_id": "6735"
}
},
"GetPayment": {"id": "string"
},
"ConfirmHold": {"id": "string"
},
"CreditWallet": {"id": "string",
"data": {"amount": {"asset": "USD/2",
"amount": 100
},
"metadata": {"key": ""
},
"sources": [ ]
}
},
"DebitWallet": {"id": "string",
"data": {"amount": {"asset": "USD/2",
"amount": 100
},
"metadata": {"key": ""
},
"pending": true
}
},
"GetWallet": {"id": "string"
},
"VoidHold": {"id": "string"
}
},
"output": {"GetAccount": {"data": {"address": "users:001",
"metadata": {"admin": "true"
},
"volumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"effectiveVolumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
}
}
},
"CreateTransaction": {"data": {"timestamp": "2019-08-24T14:15:22Z",
"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"admin": "true"
},
"id": 0,
"reverted": true
}
},
"RevertTransaction": {"data": {"timestamp": "2019-08-24T14:15:22Z",
"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"admin": "true"
},
"id": 0,
"reverted": true
}
},
"GetPayment": {"data": {"id": "XXX",
"reference": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"provider": "STRIPE",
"type": "PAY-IN",
"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"
}
}
},
"DebitWallet": {"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"walletID": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"description": "string",
"destination": {"type": "string",
"identifier": "string"
}
}
},
"GetWallet": {"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"metadata": {"property1": "string",
"property2": "string"
},
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"balances": {"main": {"assets": {"property1": 0,
"property2": 0
}
}
},
"ledger": "string"
}
}
},
"error": "string",
"terminated": true,
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"lastFailure": "string",
"attempt": 0,
"nextExecution": "2019-08-24T14:15:22Z"
}
]
}

Get server info

Responses

Response samples

200
default

Content type

application/json

{"version": "string"
}

List triggers

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { },
"id": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}
}

Create trigger

Request Body schema: application/json

event required	string
workflowID required	string
filter	string
	object

Responses

Request samples

Payload

Content type

application/json

{"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { }
}

Response samples

201
default

Content type

application/json

{"data": {"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { },
"id": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Read trigger

path Parameters

triggerID

required

string

The trigger id

Responses

Response samples

200
default

Content type

application/json

{"data": {"event": "string",
"workflowID": "string",
"filter": "string",
"vars": { },
"id": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Delete trigger

Read trigger

path Parameters

triggerID

required

string

The trigger id

Responses

Response samples

404
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

List triggers occurrences

path Parameters

triggerID

required

string

The trigger id

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"date": "2019-08-24T14:15:22Z",
"workflowInstanceID": "string",
"triggerID": "string",
"event": { }
}
]
}
}

List registered workflows

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"config": {"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": "string"
}
]
}
}

Create workflow

Create a workflow

Request Body schema: application/json

name	string
required	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
}

Response samples

201
default

Content type

application/json

{"data": {"config": {"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": "string"
}
}

Get a flow by id

path Parameters

flowId

required

string

Example: xxx

The flow id

Responses

Response samples

200
default

Content type

application/json

{"data": {"config": {"name": "string",
"stages": [{"property1": null,
"property2": null
}
]
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": "string"
}
}

Delete a flow by id

path Parameters

flowId

required

string

Example: xxx

The flow id

Responses

Response samples

400
404
default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Run workflow

path Parameters

workflowID

required

string

Example: xxx

The flow id

query Parameters

wait	boolean Wait end of the workflow before return

Request Body schema: application/json

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"property1": "string",
"property2": "string"
}

Response samples

201
default

Content type

application/json

{"data": {"workflowID": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": [{"stage": 0,
"instanceID": "string",
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
],
"terminated": true,
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
}

List instances of a workflow

query Parameters

workflowID	string Example: workflowID=xxx A workflow id
running	boolean Example: running=true Filter running instances

Responses

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"workflowID": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": [{"stage": 0,
"instanceID": "string",
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
],
"terminated": true,
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
]
}
}

Get a workflow instance by id

path Parameters

instanceID

required

string

Example: xxx

The instance id

Responses

Response samples

200
default

Content type

application/json

{"data": {"workflowID": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": [{"stage": 0,
"instanceID": "string",
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
],
"terminated": true,
"terminatedAt": "2019-08-24T14:15:22Z",
"error": "string"
}
}

Send an event to a running workflow

path Parameters

instanceID

required

string

Example: xxx

The instance id

Request Body schema: application/json

name

required

string

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Cancel a running workflow

path Parameters

instanceID

required

string

Example: xxx

The instance id

Responses

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string"
}

Get a workflow instance history by id

path Parameters

instanceID

required

string

Example: xxx

The instance id

Responses

Response samples

200
default

Content type

application/json

{"data": [{"name": "string",
"input": {"amount": {"asset": "string",
"amount": 0
},
"destination": {"wallet": {"id": "string",
"balance": "string"
},
"account": {"id": "string",
"ledger": "string"
},
"payment": {"psp": "string"
}
},
"source": {"wallet": {"id": "string",
"balance": "string"
},
"account": {"id": "string",
"ledger": "string"
},
"payment": {"id": "string"
}
}
},
"error": "string",
"terminated": true,
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z"
}
]
}

Get a workflow instance stage history

path Parameters

instanceID required	string Example: xxx The instance id
number required	integer The stage number

Responses

Response samples

200
default

Content type

application/json

{"data": [{"name": "string",
"input": {"GetAccount": {"id": "string",
"ledger": "string"
},
"CreateTransaction": {"ledger": "string",
"data": {"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"
}
}
},
"StripeTransfer": {"connectorID": "string",
"amount": 100,
"asset": "USD",
"destination": "acct_1Gqj58KZcSIg2N2q",
"waitingValidation": false,
"metadata": {"order_id": "6735"
}
},
"GetPayment": {"id": "string"
},
"ConfirmHold": {"id": "string"
},
"CreditWallet": {"id": "string",
"data": {"amount": {"asset": "USD/2",
"amount": 100
},
"metadata": {"key": ""
},
"sources": [ ]
}
},
"DebitWallet": {"id": "string",
"data": {"amount": {"asset": "USD/2",
"amount": 100
},
"metadata": {"key": ""
},
"pending": true
}
},
"GetWallet": {"id": "string"
},
"VoidHold": {"id": "string"
}
},
"output": {"GetAccount": {"data": {"address": "users:001",
"metadata": {"admin": "true"
},
"volumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
},
"effectiveVolumes": {"USD": {"input": 100,
"output": 10,
"balance": 90
},
"EUR": {"input": 100,
"output": 10,
"balance": 90
}
}
}
},
"CreateTransaction": {"data": [{"timestamp": "2019-08-24T14:15:22Z",
"postings": [{"amount": 100,
"asset": "COIN",
"destination": "users:002",
"source": "users:001"
}
],
"reference": "ref:001",
"metadata": {"admin": "true"
},
"txid": 0
}
]
},
"GetPayment": {"data": {"id": "XXX",
"reference": "string",
"sourceAccountID": "string",
"destinationAccountID": "string",
"connectorID": "string",
"provider": "STRIPE",
"type": "PAY-IN",
"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"
}
}
},
"DebitWallet": {"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"walletID": "string",
"metadata": {"property1": "string",
"property2": "string"
},
"description": "string",
"destination": {"type": "string",
"identifier": "string"
}
}
},
"GetWallet": {"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"metadata": {"property1": "string",
"property2": "string"
},
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"balances": {"main": {"assets": {"property1": 0,
"property2": 0
}
}
},
"ledger": "string"
}
}
},
"error": "string",
"terminated": true,
"startedAt": "2019-08-24T14:15:22Z",
"terminatedAt": "2019-08-24T14:15:22Z",
"lastFailure": "string",
"attempt": 0,
"nextExecution": "2019-08-24T14:15:22Z"
}
]
}

Reconciliation

Get server info

Responses

Response samples

200
default

Content type

application/json

{"version": "string"
}

Create a policy

Request Body schema: application/json
required

name required	string
ledgerName required	string
ledgerQuery required	string
paymentsPoolID required	string

Responses

Request samples

Payload

Content type

application/json

{"name": "XXX",
"ledgerName": "default",
"ledgerQuery": "{\"$match\": {\"metadata[reconciliation]\": \"pool:main\"}}",
"paymentsPoolID": "XXX"
}

Response samples

201
default

Content type

application/json

{"policy": {"id": "XXX",
"name": "XXX",
"createdAt": "2021-01-01T00:00:00.000Z",
"ledgerName": "default",
"ledgerQuery": "{\"$match\": {\"metadata[reconciliation]\": \"pool:main\"}}",
"paymentsPoolID": "XXX"
}
}

List policies

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] 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

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "XXX",
"name": "XXX",
"createdAt": "2021-01-01T00:00:00.000Z",
"ledgerName": "default",
"ledgerQuery": "{\"$match\": {\"metadata[reconciliation]\": \"pool:main\"}}",
"paymentsPoolID": "XXX"
}
]
}
}

Delete a policy

Delete a policy by its id.

path Parameters

policyID

required

string

Example: XXX

The policy ID.

Responses

Response samples

default

Content type

application/json

{"errorCode": "VALIDATION",
"errorMessage": "string",
"details": "string"
}

Get a policy

path Parameters

policyID

required

string

Example: XXX

The policy ID.

Responses

Response samples

200
default

Content type

application/json

{"policy": {"id": "XXX",
"name": "XXX",
"createdAt": "2021-01-01T00:00:00.000Z",
"ledgerName": "default",
"ledgerQuery": "{\"$match\": {\"metadata[reconciliation]\": \"pool:main\"}}",
"paymentsPoolID": "XXX"
}
}

Reconcile using a policy

path Parameters

policyID

required

string

Example: XXX

The policy ID.

Request Body schema: application/json
required

reconciledAtLedger required	string <date-time>
reconciledAtPayments required	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"reconciledAtLedger": "2021-01-01T00:00:00.000Z",
"reconciledAtPayments": "2021-01-01T00:00:00.000Z"
}

Response samples

200
default

Content type

application/json

{"reconciliation": {"id": "XXX",
"policyID": "XXX",
"createdAt": "2021-01-01T00:00:00.000Z",
"reconciledAtLedger": "2021-01-01T00:00:00.000Z",
"reconciledAtPayments": "2021-01-01T00:00:00.000Z",
"status": "COMPLETED",
"paymentsBalances": {"property1": 0,
"property2": 0
},
"ledgerBalances": {"property1": 0,
"property2": 0
},
"driftBalances": {"property1": 0,
"property2": 0
},
"error": "string"
}
}

List reconciliations

query Parameters

pageSize	integer <int64> [ 1 .. 1000 ] 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

Response samples

200
default

Content type

application/json

{"cursor": {"pageSize": 15,
"hasMore": false,
"previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
"next": "",
"data": [{"id": "XXX",
"policyID": "XXX",
"createdAt": "2021-01-01T00:00:00.000Z",
"reconciledAtLedger": "2021-01-01T00:00:00.000Z",
"reconciledAtPayments": "2021-01-01T00:00:00.000Z",
"status": "COMPLETED",
"paymentsBalances": {"property1": 0,
"property2": 0
},
"ledgerBalances": {"property1": 0,
"property2": 0
},
"driftBalances": {"property1": 0,
"property2": 0
},
"error": "string"
}
]
}
}

Get a reconciliation

path Parameters

reconciliationID

required

string

Example: XXX

The reconciliation ID.

Responses

Response samples

200
default

Content type

application/json

{"reconciliation": {"id": "XXX",
"policyID": "XXX",
"createdAt": "2021-01-01T00:00:00.000Z",
"reconciledAtLedger": "2021-01-01T00:00:00.000Z",
"reconciledAtPayments": "2021-01-01T00:00:00.000Z",
"status": "COMPLETED",
"paymentsBalances": {"property1": 0,
"property2": 0
},
"ledgerBalances": {"property1": 0,
"property2": 0
},
"driftBalances": {"property1": 0,
"property2": 0
},
"error": "string"
}
}