API

Introduction

This section describes all the endpoints of the Cash Account Management package. The API flow is shown below:

---

GET Cash Accounts

The GET Cash Accounts endpoint allows you to retrieve the complete list of accounts associated with the authenticated subject. Below is an example request:

GET /api/gbs/banking/v4.0/accounts

The endpoint does not require path or query parameters.

Example response:

{
  "list": [
    {
      "accountId": "14930637",
      "iban": "IT22D3706978430115706240270",
      "abiCode": "37069",
      "cabCode": "78430",
      "countryCode": "IT",
      "internationalCin": "22",
      "nationalCin": "D",
      "account": "115706240270",
      "alias": "Company main account",
      "productName": "Generic company cash account",
      "holderName": "ACME Inc.",
      "activatedDate": "2008-12-25",
      "currency": "EUR"
    }
  ]
}

Field	Type	Description
accountId	String	Unique account identifier; required for other endpoints.
iban	String	Full IBAN of the account.
abiCode	String	ABI code of the bank.
cabCode	String	Branch CAB code.
countryCode	String	Country code of the account (e.g., IT).
internationalCin	String	International CIN of the IBAN.
nationalCin	String	National CIN of the IBAN.
account	String	Account number (substring of the IBAN).
alias	String	Account alias, if present.
productName	String	Commercial name of the product linked to the account.
holderName	String	Full name of the account holder(s).
activatedDate	Date	Account activation date.
currency	String	Native currency of the account (e.g., EUR).

---

GET Cash Account

The GET Cash Account endpoint returns the complete details of a single account, identified by accountId.

GET /api/gbs/banking/v4.0/accounts/{accountId}

Type	Name	Req	Description
Path	accountId	Yes	Unique account identifier obtained via GET Cash Accounts

The response has the same structure as the previous endpoint, but in this case a single element is returned.

---

GET Cash Account Balance

The GET Cash Account Balance endpoint allows you to obtain the updated balance of the specified account, both accounting and available. It is essential for financial monitoring functions, account dashboards, and reconciliation processes.

Endpoint to invoke:

GET /api/gbs/banking/v4.0/accounts/{accountId}/balance

Type	Name	Req	Description
Path	accountId	Yes	Unique account identifier

Example response:

{
  "balance": 15234.55,
  "availableBalance": 14980.10,
  "currency": "EUR",
  "date": "2024-01-15"
}

Field	Type	Description
balance	Number	Accounting balance of the account
availableBalance	Number	Effectively available balance
currency	String	Currency
date	Date	Reference date of the balance

---

GET Cash Account Transactions

Returns the list of transactions related to the selected account. Used to reconstruct movements, generate account statements, perform analyses, or perform reconciliation.

Request:

GET /api/gbs/banking/v4.0/accounts/{accountId}/transactions?fromAccountingDate=YYYY-MM-DD&toAccountingDate=YYYY-MM-DD

Type	Name	Req	Description
Path	accountId	Yes	Unique account identifier
Query	fromAccountingDate	Yes	Start date (inclusive) of the search period
Query	toAccountingDate	Yes	End date (inclusive) of the search period
Query	order	No	Sorting of transactions
Query	maxRecords	No	Maximum number of transactions to include

Example response:

{
  "list": [
    {
      "transactionId": "123456789",
      "operationDate": "2024-02-01",
      "valueDate": "2024-02-01",
      "amount": -150.00,
      "currency": "EUR",
      "description": "Wire transfer outgoing",
      "type": "DEBIT"
    }
  ]
}

Field	Type	Description
transactionId	String	Unique transaction identifier
operationDate	Date	Operation date
valueDate	Date	Value date
amount	Number	Transaction amount
currency	String	Currency
description	String	Transaction description
type	String	Transaction type (DEBIT/CREDIT)

---

GET Cash Account Reserved Entries

Returns the list of reserved entries for the account: amounts recorded but not yet available, such as future charges or pending authorizations.

Endpoint to invoke:

GET /api/gbs/banking/v4.0/accounts/{accountId}/reserved-entries

Type	Name	Req	Description
Path	accountId	Yes	Account identifier

Example response:

{
  "list": [
    {
      "reservedEntryId": "69451812",
      "creationDate": "2017-03-08",
      "dueDate": "2017-03-08",
      "amount": -10.01,
      "currency": "EUR",
      "description": "Mobile carrier phone charge."
    }
  ]
}

Field	Type	Description
reservedEntryId	String	Reserved entry identifier
creationDate	Date	Entry creation date
dueDate	Date	Expected expiry date
amount	Number	Blocked amount
currency	String	Currency
description	String	Reason for the blocked amount