Bermuda Commercial Bank RESTful Open Banking API Implementation (v1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

{
  "virtualAccountNumber": "1000327642",
  "bicCode": "BPBKBMHMXXX",
  "accountHolderName": "T1 Project Alpha Escrow",
  "accountName": "New Title T2",
  "currency": "USD",
  "balance": {
    "amount": "0",
    "currency": "USD"
  },
  "category": "CMS Sub Acct"
}

async function createVirtualAccounts() {
  try {
    const response = await fetch('https://api.bcb.bm/v1/virtual-accounts', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional
      },
      body: JSON.stringify({
        callbackUrl: 'https://my-callback-url.com', // Optional
        // Optional: custom headers echoed in the completion webhook
        customHeaders: {
          'X-Custom-Header-1': 'CustomValue1',
          'X-Custom-Header-2': 'CustomValue2',
          'X-Custom-Header-3': 'CustomValue3'
        },
        items: [
          {
            currency: 'USD',
            accountHolderName: 'Test Company Ltd',
            accountName: 'Test Virtual Account 001',
            clientReference: 'BATCH-REF-001'
          },
          {
            currency: 'USD',
            accountHolderName: 'Test Company Ltd',
            accountName: 'Test Virtual Account 002',
            clientReference: 'BATCH-REF-002'
          },
          // Example: Pre-create unallocated accounts for later assignment
          {
            currency: 'USD',
            unallocated: true,
            clientReference: 'UNALLOC-001'
          }
        ]
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Virtual account creation failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const batchResponse = await response.json();

    // Display batch job information
    console.log('Batch Job Created:');
    console.log(`  Job ID: ${batchResponse.jobId}`);
    console.log(`  Status: ${batchResponse.status}`);
    console.log(`  Status URL: ${batchResponse.statusUrl}`);
    console.log(`  Result URL: ${batchResponse.resultUrl}`);

    // Store these URLs for monitoring the job
    // Use statusUrl to check progress
    // Use resultUrl to get final outcomes

    return batchResponse;
  } catch (error) {
    console.error('Failed to create virtual accounts:', error.message);
    throw error;
  }
}

// Example usage:

// Create multiple virtual accounts
createVirtualAccounts();

async function getAllVirtualAccounts(currency = null, pageSize = 25, pageStart = 1, pageToken = null) {
  try {
    // Build URL with optional parameters
    let url = 'https://api.bcb.bm/v1/virtual-accounts';
    const params = new URLSearchParams();
    
    if (currency) {
      params.append('currency', currency);
    }
    
    if (pageStart === 1 && !pageToken) {
      // First request only: optionally specify pageSize
      params.append('pageSize', pageSize.toString());
    } else {
      // Subsequent requests: use pageToken + pageStart and do NOT send pageSize again
      params.append('pageToken', pageToken);
      params.append('pageStart', pageStart.toString());
    }
    
    url += '?' + params.toString();

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Virtual accounts retrieval failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const result = await response.json();

    // Access pagination info
    const pagination = result.meta.pagination;
    console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);

    // Process virtual accounts
    result.data.forEach((account, index) => {
      console.log(`Account ${index + 1}:`);
      console.log(`  Virtual Account Number: ${account.virtualAccountNumber}`);
      console.log(`  BIC: ${account.bicCode}`);
      console.log(`  Account Holder: ${account.accountHolderName}`);
      console.log(`  Account Name: ${account.accountName}`);
      console.log(`  Currency: ${account.currency}`);
      console.log(`  Balance: ${account.balance ? account.balance.amount + ' ' + account.balance.currency : 'N/A'}`);
      console.log(`  Category: ${account.category}`);
      
      if (account.clientReference) {
        console.log(`  Client Reference: ${account.clientReference}`);
      }
      
      if (account.effectiveDate) {
        console.log(`  Effective Date: ${account.effectiveDate}`);
      }
      
      if (account.createdAt) {
        console.log(`  Created At: ${account.createdAt}`);
      }
      
      // Log parent/settlement account relationships
      if (account.parentAccount) {
        console.log(`  Parent Account: ${account.parentAccount.accountNumber} (${account.parentAccount.accountName})`);
      }
      if (account.settlementAccount) {
        console.log(`  Settlement Account: ${account.settlementAccount.accountNumber} (${account.settlementAccount.accountName})`);
      }
      
      console.log('---');
    });

    return result;
  } catch (error) {
    console.error('Failed to retrieve virtual accounts:', error.message);
    throw error;
  }
}

// Example usage:

// Get all virtual accounts
getAllVirtualAccounts();

// Get only USD virtual accounts
getAllVirtualAccounts('USD');

// Get first 10 virtual accounts
getAllVirtualAccounts(null, 10);

async function updateVirtualAccount(virtualAccountNumber) {
  try {
    const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountNumber}`, {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        // Note: Only clientReference can be updated after first allocation
        // accountHolderName, accountName, dob, and nativeLanguageName are immutable after first update
        clientReference: 'updated-reference-123'
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      
      // Handle immutable field error
      if (response.status === 409 && errorData.code === 'ACCOUNT_NAMES_IMMUTABLE') {
        console.error('Cannot update immutable fields - already set after first update');
        return;
      }
      
      throw new Error(`Virtual account update failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const result = await response.json();
    const virtualAccount = result.data;
    
    // Log updated details
    console.log('Virtual Account Updated Successfully:');
    console.log(`  Account Number: ${virtualAccount.virtualAccountNumber}`);
    console.log(`  Account Holder: ${virtualAccount.accountHolderName}`);
    console.log(`  Account Name: ${virtualAccount.accountName}`);
    console.log(`  Currency: ${virtualAccount.currency}`);
    console.log(`  Category: ${virtualAccount.category}`);
    
    if (virtualAccount.balance) {
      console.log(`  Balance: ${virtualAccount.balance.amount} ${virtualAccount.balance.currency}`);
    }
    
    if (virtualAccount.clientReference) {
      console.log(`  Client Reference: ${virtualAccount.clientReference}`);
    }
    
    console.log(`  Effective Date: ${virtualAccount.effectiveDate}`);
    console.log(`  Created: ${virtualAccount.createdAt}`);
    
    // Log parent/settlement account info
    if (virtualAccount.parentAccount) {
      console.log(`  Parent Account: ${virtualAccount.parentAccount.accountNumber} (${virtualAccount.parentAccount.accountSubType})`);
    }
    if (virtualAccount.settlementAccount) {
      console.log(`  Settlement Account: ${virtualAccount.settlementAccount.accountNumber} (${virtualAccount.settlementAccount.accountSubType})`);
    }

    return result;
  } catch (err) {
    console.error('Error updating virtual account:', err);
    throw err;
  }
}

// Example usage:
updateVirtualAccount('1000327642');

// Example: Allocating an unallocated account to a customer (ONE-TIME OPERATION)
async function allocateUnallocatedAccount(virtualAccountNumber, customerName, accountTitle, dob, nativeLanguageName) {
  try {
    const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountNumber}`, {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        // All these fields are immutable after this update!
        accountHolderName: customerName,
        accountName: accountTitle,
        dob: dob,                         // Optional - immutable after set
        nativeLanguageName: nativeLanguageName  // Optional - immutable after set
      })
    });

    if (!response.ok) {
      const errorData = await response.json();
      
      // Handle case where account was already allocated
      if (response.status === 409 && errorData.code === 'ACCOUNT_NAMES_IMMUTABLE') {
        throw new Error('Account has already been allocated. Immutable fields cannot be changed after first update.');
      }
      
      throw new Error(`Account allocation failed: ${JSON.stringify(errorData)}`);
    }

    const result = await response.json();
    console.log('Account successfully allocated to:', customerName);
    return result;
  } catch (err) {
    console.error('Error allocating account:', err);
    throw err;
  }
}

// Allocate a pre-created unallocated account (can only be done once!)
allocateUnallocatedAccount('1000327650', 'Acme Corporation', 'Acme Trading Account', '1990-05-15', 'John Smith');