Bank Accounts

Bank accounts represent the company's accounts at financial institutions. Each bank account is linked to a GL account in the chart of accounts, ensuring that all bank transactions are automatically reflected in the general ledger. Bank accounts are also linked to a currency and can be associated with multiple company branches.

Purpose

• Register and manage the company's bank accounts
• Link each bank account to a GL account for automatic ledger integration
• Track bank account details: IBAN, SWIFT code, account number
• Associate bank accounts with a specific currency
• Assign bank accounts to one or more company branches (multi-branch support)
• Serve as the foundation for checks management, account transfers, and bank reconciliation

Entity Attributes

Bank Account

Field	Type	Description
id	bigint	Primary key
company_id	bigint	FK to companies
bank_name	string	English bank name
bank_name_ar	string?	Arabic bank name
account_number	string	Bank account number
iban	string?	International Bank Account Number
swift_code	string?	SWIFT/BIC code
currency_id	bigint?	FK to currencies
account_id	bigint	FK to accounts (linked GL account)
is_active	boolean	Whether the bank account is active
created_at	timestamp	Creation timestamp
updated_at	timestamp	Last update timestamp
deleted_at	timestamp?	Soft-delete timestamp

Bank Account Branch (Pivot)

Field	Type	Description
bank_account_id	bigint	FK to bank_accounts
branch_id	bigint	FK to branches
is_primary	boolean	Whether this is the primary branch

Relationships

API Endpoints

Method	Path	Description
GET	/api/accounting/bank-accounts	List bank accounts (paginated)
POST	/api/accounting/bank-accounts	Create a new bank account
GET	/api/accounting/bank-accounts/{id}	Get a single bank account
PUT	/api/accounting/bank-accounts/{id}	Update a bank account
DELETE	/api/accounting/bank-accounts/{id}	Soft-delete a bank account

Request/Response Examples

Create Bank Account

Request POST /api/accounting/bank-accounts

curl

curl -X POST https://moon-erp.test/api/accounting/bank-accounts \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "bank_name": "National Bank of Kuwait",
    "bank_name_ar": "بنك الكويت الوطني",
    "account_number": "0012345678",
    "iban": "KW81CBKU0000000000001234560101",
    "swift_code": "NBOKKWKW",
    "currency_id": 1,
    "account_id": 4,
    "branch_ids": [1, 2],
    "is_active": true
  }'

Dart

final response = await http.post(
  Uri.parse('https://moon-erp.test/api/accounting/bank-accounts'),
  headers: {
    'Authorization': 'Bearer $token',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: jsonEncode({
    'bank_name': 'National Bank of Kuwait',
    'bank_name_ar': 'بنك الكويت الوطني',
    'account_number': '0012345678',
    'iban': 'KW81CBKU0000000000001234560101',
    'swift_code': 'NBOKKWKW',
    'currency_id': 1,
    'account_id': 4,
    'branch_ids': [1, 2],
    'is_active': true,
  }),
);

Request Fields:

Field	Type	Required	Description
bank_name	string	Yes	English bank name
bank_name_ar	string	No	Arabic bank name
account_number	string	Yes	Bank account number
iban	string	No	International Bank Account Number
swift_code	string	No	SWIFT/BIC code
currency_id	integer	No	FK to currencies
account_id	integer	No	FK to accounts. If omitted, auto-created under 1102.
branch_ids	integer[]	No	Array of branch IDs. First element is the primary branch.
is_active	boolean	No	Defaults to true

Response 201 Created

{
  "data": {
    "id": 1,
    "company_id": 1,
    "bank_name": "National Bank of Kuwait",
    "bank_name_ar": "بنك الكويت الوطني",
    "account_number": "0012345678",
    "iban": "KW81CBKU0000000000001234560101",
    "swift_code": "NBOKKWKW",
    "currency_id": 1,
    "currency": {
      "id": 1,
      "code": "KWD",
      "name": "دينار كويتي",
      "symbol": "د.ك"
    },
    "account_id": 4,
    "account": {
      "id": 4,
      "code": "1102",
      "name": "Cash at Bank",
      "name_ar": "النقدية بالبنك"
    },
    "branches": [
      { "id": 1, "name": "Main Branch", "name_ar": "الفرع الرئيسي" },
      { "id": 2, "name": "South Branch", "name_ar": "الفرع الجنوبي" }
    ],
    "is_active": true,
    "created_at": "2026-02-16T12:00:00.000000Z",
    "updated_at": "2026-02-16T12:00:00.000000Z"
  }
}

List Bank Accounts

Request GET /api/accounting/bank-accounts

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "bank_name": "بنك الكويت الوطني",
      "account_number": "0012345678",
      "iban": "KW81CBKU0000000000001234560101",
      "swift_code": "NBOKKWKW",
      "currency": { "code": "KWD", "symbol": "د.ك" },
      "account": { "code": "1102", "name": "النقدية بالبنك" },
      "branches": [
        { "id": 1, "name": "الفرع الرئيسي" }
      ],
      "is_active": true
    },
    {
      "id": 2,
      "bank_name": "البنك الأهلي المصري",
      "account_number": "9876543210",
      "currency": { "code": "EGP", "symbol": "ج.م" },
      "account": { "code": "1102", "name": "النقدية بالبنك" },
      "branches": [],
      "is_active": true
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 2 }
}

Update Bank Account Branches

Request PUT /api/accounting/bank-accounts/1

{
  "branch_ids": [2, 3]
}

Replaces all existing branch assignments. First element (2) becomes the primary branch. Send an empty array to remove all branch assignments.

Business Rules

1. GL account required -- Every bank account must be linked to a detail-level GL account (typically under "Cash at Bank" or a sub-account). If account_id is omitted, a sub-account is auto-created under code 1102.
2. One GL account per bank -- Each bank account should link to a unique GL account to maintain clear audit trails. Multiple bank accounts should not share the same GL account.
3. Currency assignment -- The currency assigned to a bank account determines the currency of checks issued/received and bank reconciliation for that account.
4. Multi-branch support -- Bank accounts can be assigned to multiple branches via branch_ids. The first element in the array is the primary branch. An empty array means the bank account is accessible from all branches.
5. Branch sync -- When updating branch_ids, the provided array replaces all existing branch assignments (sync, not merge).
6. Cannot delete active accounts -- Bank accounts with associated checks, transfers, or reconciliations cannot be deleted.
7. Active status -- Only active bank accounts can be used for new checks and transfers.

How Bank Accounts Connect to Other Features