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

// 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

// 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"
    }
  }
}