# Partner Bank Account

## Overview

Partner Bank Accounts are child entities of a Business Partner that store the banking details required to execute financial transactions with that partner. Each record captures identifying information for a single bank account: bank name, account holder name, account number, routing number, IBAN, SWIFT/BIC, and the transaction currency. A partner may hold multiple bank accounts, and one account per partner may be designated as the default to streamline payment processing.

Bank account records can be created and maintained regardless of the partner's current lifecycle state (DRAFT, ACTIVE, or INACTIVE), allowing finance teams to prepare payment details in advance and retain them after a partner is deactivated.

## Business Purpose

Accurate bank account data is a prerequisite for both accounts payable (paying suppliers) and accounts receivable (collecting from customers). Maintaining this data on the partner record ensures downstream payment and collection workflows always have a reliable, auditable source:

- **Accounts payable**: Supplier bank details are referenced when generating payment runs, wire transfers, or ACH batches for purchase invoices
- **Accounts receivable**: Customer bank details support direct debit collection and refund processing
- **Multi-account flexibility**: Partners operating across multiple currencies or banking jurisdictions can have separate accounts per bank or currency
- **Default designation**: Finance teams can mark one account as default to reduce manual selection during routine payment processing
- **Regional field coverage**: The model supports both account-number/routing-number conventions (US/Canada) and IBAN/SWIFT conventions (Europe and international), enabling global counterparty management
- **Currency association**: Each bank account references a Currency from the primitives module, clarifying which denomination the account handles

## Process Flow

The following diagram shows how a bank account is added to a partner and how the default designation is managed:

```mermaid
flowchart TD
    A[Select Business Partner] --> B[Add Bank Account]
    B --> C[Enter Bank Details\nbankName, accountHolderName,\naccountNumber / IBAN,\nroutingNumber / SWIFT/BIC,\ncurrency]
    C --> D{First account\nfor this partner?}
    D -->|Yes| E[Auto-designate as default]
    D -->|No| F[Save as non-default]
    E --> G[Bank Account Saved]
    F --> G
    G --> H{Change default?}
    H -->|Yes| I[Mark account as default\nPrevious default is unset]
    H -->|No| J[No further action]
    I --> K[Default Updated]
```

## Scenario Patterns

- **New supplier payment setup**: A procurement team onboards a new vendor. Before the first purchase order is issued, the AP team adds the supplier's EUR bank account (IBAN + SWIFT/BIC) and it is automatically designated as the default. Payment runs will reference this account.
- **US domestic vendor with routing**: A US-based supplier provides an ABA routing number and checking account number instead of an IBAN. Finance adds the account using `routingNumber` and `accountNumber` fields, omitting IBAN and SWIFT/BIC.
- **Multi-currency supplier**: An international supplier invoices in both USD and EUR. Two bank accounts are added — one per currency — each referencing the appropriate Currency from the primitives module. The USD account is marked as the default for domestic transactions.
- **Customer direct debit**: A customer agreement includes a direct debit mandate. The AR team records the customer's bank account so that collection runs can reference it without re-entering details each cycle.
- **Updating the default account**: A supplier notifies the company of a new primary bank account. The finance team adds the new account and marks it as default; the previous default account is retained for reference and audit but is no longer automatically selected.
- **Inactive partner retention**: A vendor is deactivated following contract expiry. Their bank accounts remain in the system for audit and potential reactivation, but the partner cannot be referenced in new payment runs while INACTIVE.

## Test Cases

- A bank account can be added to a partner in DRAFT, ACTIVE, or INACTIVE state
- The first bank account added to a partner is automatically designated as the default
- A partner can have more than one bank account
- Marking a bank account as default unsets the default flag on all other accounts for that partner
- At most one bank account per partner can be designated as default at any time
- `bankName` is required and must be non-empty
- `accountHolderName` is required and must be non-empty
- At least one of `accountNumber` or `iban` must be provided; both may be provided simultaneously
- `routingNumber` is optional and applicable for domestic (ACH/wire) routing conventions
- `swiftBic` is optional and applicable for international transfers
- `currency` must reference a valid, existing Currency from the primitives module
- Removing a bank account that is currently designated as the default does not automatically promote another account; the partner has no default until one is explicitly designated
- Bank accounts are isolated per partner; accounts belonging to one partner are not visible on another

## Reference Links

- [SAP Business Partner Bank Details](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f325a3e3a5514e85aab72db8bab710c8/4b2011bb2d6b3e41e10000000a42189c.html)
- [Odoo Partner Bank Accounts (res.partner.bank)](https://www.odoo.com/documentation/19.0/applications/accounting/payments/pay.html)
- [Oracle Supplier Bank Accounts](https://docs.oracle.com/en/cloud/saas/financials/24b/fappp/manage-supplier-bank-accounts.html)
- [ISO 9362 SWIFT/BIC Standard](https://www.iso.org/standard/60390.html)
- [ISO 13616 IBAN Standard](https://www.iso.org/standard/81090.html)
