# Transaction ID Uniqueness Guide

The Bermuda Commercial Bank Open Banking API uses **globally unique transaction IDs** that provide consistent identification across all banking operations and account views.

## 🔑 Core Principles

### Global Uniqueness

- **Transaction IDs are unique across the entire banking system**
- Each transaction ID represents a single banking operation, regardless of how many accounts are affected
- No two different banking operations will ever share the same transaction ID
- Transaction IDs remain consistent across all API endpoints and account views


### Cross-Account Consistency

- **The same transaction ID appears on all accounts involved in a transaction**
- Internal transfers will show the same transaction ID on both the source and destination accounts
- External transfers will show the same transaction ID on the customer's account and in system records


## 💸 Internal Transfer Behavior

### Shared Transaction IDs

When an internal transfer occurs between two accounts:

1. **Both accounts receive the same transaction ID**
2. **The debit entry** appears on the source account with a negative amount
3. **The credit entry** appears on the destination account with a positive amount
4. **Transaction types differ**: One shows as "Debit" and the other as "Credit"
5. **All other transaction details remain identical** (description, reference, timestamp, etc.)


### Example: Internal Transfer


```json
// Source Account (Account A) - Debit Entry
{
  "id": "TXN-2024-001234567",
  "thisAccount": {
    "number": "1000123456"
  },
  "otherAccount": {
    "number": "1000789012"
  },
  "details": {
    "type": "Debit",
    "description": "Internal Transfer",
    "value": {
      "amount": -500.00,
      "currency": "BMD"
    },
    "posted": "2024-01-15T10:30:00Z"
  }
}

// Destination Account (Account B) - Credit Entry
{
  "id": "TXN-2024-001234567",  // Same transaction ID
  "thisAccount": {
    "number": "1000789012"
  },
  "otherAccount": {
    "number": "1000123456"
  },
  "details": {
    "type": "Credit",
    "description": "Internal Transfer",
    "value": {
      "amount": 500.00,        // Positive amount
      "currency": "BMD"
    },
    "posted": "2024-01-15T10:30:00Z"
  }
}
```

## 💰 Fee and Charge Handling

### Multiple Entries, Same Transaction ID

When fees or charges apply to a transaction, multiple entries may appear with the same transaction ID:

1. **Primary transaction entry** (the main debit/credit)
2. **Fee entry** (bank charges, processing fees, etc.)
3. **All entries share the same transaction ID**
4. **Each entry has different amounts and descriptions**


### Example: Transaction with Fee


```json
// Primary Transaction Entry
{
  "id": "TXN-2024-001234568",
  "details": {
    "type": "Debit",
    "description": "Wire Transfer to External Bank",
    "value": {
      "amount": -1000.00,
      "currency": "BMD"
    }
  }
}

// Fee Entry (Same Transaction ID)
{
  "id": "TXN-2024-001234568",  // Same transaction ID
  "details": {
    "type": "Debit",
    "description": "Wire Transfer Fee",
    "value": {
      "amount": -25.00,         // Separate fee amount
      "currency": "BMD"
    }
  }
}
```