**API versions** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=en)

# Banking

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

## Operations

## GET /banking/accounts

List stored bank accounts and balance snapshots

`list_banking_accounts`

Requires explicitly granted banking:read. Reads only persisted Open Banking bank/statement records of the authenticated organisation and current legal associations; Stripe Treasury merchant accounts, payouts and accounting livrets are separate and excluded. Campaign-restricted keys are refused. No provider request, refresh, sync, expiry update, reconciliation or financial mutation occurs; shared authentication may record key usage. amountMajor is a signed decimal string in MAJOR currency units (12.34 eur means EUR 12.34), never minor units; do not divide by 100. Missing/invalid amounts, currencies, timestamps and pointage remain null/UNKNOWN, never invented zero or today's date. Stored balance snapshots may be stale even when connection.state is CONNECTED; observedAt is the last stored sync timestamp, not a live observation or freshness guarantee. booked is the source closingBooked balance (historical sync.soldePredicted); expected is its expected balance (sync.soldeFixed). EXPIRED is derived without writing. Connection success, a balance, a recorded COMPLETED donation or pointed=true never proves the settlement of a particular payment. No credentials, complete IBAN, provider account IDs, raw snapshots, payment links or private errors are exposed. Unknown query parameters and non-empty bodies are rejected. Lists by local UUID ascending. Filters by assoc only; each balance carries its own recorded currency. Currency is not inferred from association metadata. Continue using nextCursor; malformed or duplicated historical account identities return 409.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "banking:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "assoc",
  "in": "query",
  "required": false,
  "description": "Legal association ID from list_associations; MAIN denotes the primary association, not a bank or budget account. No foreign or historical alias is admitted.",
  "schema": {
    "type": "string",
    "pattern": "^(MAIN|[0-9a-fA-F-]{36})$"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "description": "Page size, 1 to 200, default 50.",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "required": false,
  "description": "Opaque nextCursor, reused unchanged with the same organisation, bank and filters. Concurrent reads do not form a snapshot.",
  "schema": {
    "type": "string",
    "maxLength": 2048
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Admitted stored observations with explicit partial coverage and unknown values.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingAccountsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_ASSOCIATION, INVALID_CURRENCY, INVALID_DATE, INVALID_LIMIT, INVALID_CURSOR, INVALID_QUERY_PARAMETER, INVALID_BUDGET_TARGET, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: the object or association is absent, foreign or outside the admitted context.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY or BUDGET_CATALOG_LIMIT: stored identity/ownership cannot be admitted safely, or the bounded catalogue is too large. Do not bypass through an internal route.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No provider or financial write was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "banking:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /banking/accounts/{id}

Read a stored bank account and balance snapshots

`get_banking_account`

Requires explicitly granted banking:read. Reads only persisted Open Banking bank/statement records of the authenticated organisation and current legal associations; Stripe Treasury merchant accounts, payouts and accounting livrets are separate and excluded. Campaign-restricted keys are refused. No provider request, refresh, sync, expiry update, reconciliation or financial mutation occurs; shared authentication may record key usage. amountMajor is a signed decimal string in MAJOR currency units (12.34 eur means EUR 12.34), never minor units; do not divide by 100. Missing/invalid amounts, currencies, timestamps and pointage remain null/UNKNOWN, never invented zero or today's date. Stored balance snapshots may be stale even when connection.state is CONNECTED; observedAt is the last stored sync timestamp, not a live observation or freshness guarantee. booked is the source closingBooked balance (historical sync.soldePredicted); expected is its expected balance (sync.soldeFixed). EXPIRED is derived without writing. Connection success, a balance, a recorded COMPLETED donation or pointed=true never proves the settlement of a particular payment. No credentials, complete IBAN, provider account IDs, raw snapshots, payment links or private errors are exposed. Unknown query parameters and non-empty bodies are rejected. Accepts exactly one local UUID. Absent and foreign accounts share 404; a provider reference is not authority. No query parameter is accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "banking:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Local bank-account UUID returned by list_banking_accounts. Provider account references and Stripe account keys are not accepted.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Admitted stored observations with explicit partial coverage and unknown values.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingAccountResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_ASSOCIATION, INVALID_CURRENCY, INVALID_DATE, INVALID_LIMIT, INVALID_CURSOR, INVALID_QUERY_PARAMETER, INVALID_BUDGET_TARGET, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: the object or association is absent, foreign or outside the admitted context.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY or BUDGET_CATALOG_LIMIT: stored identity/ownership cannot be admitted safely, or the bounded catalogue is too large. Do not bypass through an internal route.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No provider or financial write was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "banking:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /banking/accounts/{id}/transactions

List stored bank statement debits and credits

`list_banking_transactions`

Requires explicitly granted banking:read. Reads only persisted Open Banking bank/statement records of the authenticated organisation and current legal associations; Stripe Treasury merchant accounts, payouts and accounting livrets are separate and excluded. Campaign-restricted keys are refused. No provider request, refresh, sync, expiry update, reconciliation or financial mutation occurs; shared authentication may record key usage. amountMajor is a signed decimal string in MAJOR currency units (12.34 eur means EUR 12.34), never minor units; do not divide by 100. Missing/invalid amounts, currencies, timestamps and pointage remain null/UNKNOWN, never invented zero or today's date. Stored balance snapshots may be stale even when connection.state is CONNECTED; observedAt is the last stored sync timestamp, not a live observation or freshness guarantee. booked is the source closingBooked balance (historical sync.soldePredicted); expected is its expected balance (sync.soldeFixed). EXPIRED is derived without writing. Connection success, a balance, a recorded COMPLETED donation or pointed=true never proves the settlement of a particular payment. No credentials, complete IBAN, provider account IDs, raw snapshots, payment links or private errors are exposed. Unknown query parameters and non-empty bodies are rejected. First authorises the current bank account, then reads only its statement rows. Positive amountMajor is a credit and negative is a debit. id is the opaque statement transaction reference, scoped to this bank. bookedAt/valueAt are stored BSON dates normalised to UTC, often local midnight, not precise transaction instants. Filters from/to are inclusive stored booking instants in UTC; currency is the original statement currency. Sorts by valid bookedAt descending then opaque id descending, invalid dates last. pointed is only the stored bank pointage flag, not a verified payment/payout match. No reconciliation link or candidate is hydrated or returned. Missing/ambiguous or duplicate transaction references return 409 rather than inventing pagination.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "banking:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Local bank-account UUID returned by list_banking_accounts. Provider account references and Stripe account keys are not accepted.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "currency",
  "in": "query",
  "required": false,
  "description": "Optional exact lowercase three-letter statement currency. No conversion or organisation-currency fallback.",
  "schema": {
    "type": "string",
    "pattern": "^[a-z]{3}$"
  }
}
```

```json
{
  "name": "from",
  "in": "query",
  "required": false,
  "description": "Inclusive stored booking instant, exact UTC YYYY-MM-DDTHH:mm:ss.sssZ.",
  "schema": {
    "type": "string",
    "format": "date-time"
  }
}
```

```json
{
  "name": "to",
  "in": "query",
  "required": false,
  "description": "Inclusive stored booking instant, exact UTC YYYY-MM-DDTHH:mm:ss.sssZ; must not precede from.",
  "schema": {
    "type": "string",
    "format": "date-time"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "description": "Page size, 1 to 200, default 50.",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "required": false,
  "description": "Opaque nextCursor, reused unchanged with the same organisation, bank and filters. Concurrent reads do not form a snapshot.",
  "schema": {
    "type": "string",
    "maxLength": 2048
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Admitted stored observations with explicit partial coverage and unknown values.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingTransactionsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_ASSOCIATION, INVALID_CURRENCY, INVALID_DATE, INVALID_LIMIT, INVALID_CURSOR, INVALID_QUERY_PARAMETER, INVALID_BUDGET_TARGET, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: the object or association is absent, foreign or outside the admitted context.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY or BUDGET_CATALOG_LIMIT: stored identity/ownership cannot be admitted safely, or the bounded catalogue is too large. Do not bypass through an internal route.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No provider or financial write was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "banking:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## Schemas

```json
{
  "components": {
    "schemas": {
      "BankingAccountsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BankingAccount"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/BankingPage"
          },
          "coverage": {
            "$ref": "#/components/schemas/BankingCoverage"
          }
        }
      },
      "BankingAccount": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "assoc",
          "label",
          "accountSuffix",
          "connection",
          "balances"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "assoc": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "accountSuffix": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Za-z0-9]{4}$"
          },
          "connection": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "state",
              "expiresAt"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "CONNECTED",
                  "DISCONNECTED",
                  "EXPIRED",
                  "UNKNOWN"
                ]
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "balances": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "observedAt",
              "booked",
              "expected"
            ],
            "properties": {
              "observedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "booked": {
                "$ref": "#/components/schemas/BankingMoney"
              },
              "expected": {
                "$ref": "#/components/schemas/BankingMoney"
              }
            }
          }
        }
      },
      "BankingMoney": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amountMajor",
          "currency",
          "availability"
        ],
        "properties": {
          "amountMajor": {
            "type": "string",
            "nullable": true,
            "pattern": "^-?\\d+(?:\\.\\d+)?$",
            "description": "Signed decimal string in MAJOR units of currency: 12.34 eur means EUR 12.34. Never divide by 100. Invalid or missing amounts remain null; zero is returned only when explicitly recorded."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$"
          },
          "availability": {
            "type": "string",
            "enum": [
              "RECORDED",
              "UNKNOWN"
            ]
          }
        }
      },
      "BankingPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "count",
          "hasMore",
          "nextCursor"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 200
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "maxLength": 2048
          }
        }
      },
      "BankingCoverage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "complete",
          "limitations"
        ],
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "STORED_OPEN_BANKING"
            ]
          },
          "complete": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "NO_PROVIDER_REFRESH",
                "STRIPE_TREASURY_EXCLUDED",
                "NO_SETTLEMENT_PROOF"
              ]
            }
          }
        }
      },
      "BankingReadError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "BankingAccountResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/BankingAccount"
          },
          "coverage": {
            "$ref": "#/components/schemas/BankingCoverage"
          }
        }
      },
      "BankingTransactionsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BankingTransaction"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/BankingPage"
          },
          "coverage": {
            "$ref": "#/components/schemas/BankingCoverage"
          }
        }
      },
      "BankingTransaction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "bankId",
          "amountMajor",
          "currency",
          "availability",
          "label",
          "bookedAt",
          "valueAt",
          "pointed"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "bankId": {
            "type": "string",
            "format": "uuid"
          },
          "amountMajor": {
            "type": "string",
            "nullable": true,
            "pattern": "^-?\\d+(?:\\.\\d+)?$",
            "description": "Signed decimal string in MAJOR units of currency: 12.34 eur means EUR 12.34. Never divide by 100. Invalid or missing amounts remain null; zero is returned only when explicitly recorded."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$"
          },
          "availability": {
            "type": "string",
            "enum": [
              "RECORDED",
              "UNKNOWN"
            ]
          },
          "label": {
            "type": "string",
            "nullable": true,
            "maxLength": 4000
          },
          "bookedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "valueAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "pointed": {
            "type": "boolean",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
