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

Retrieves the total balance across all virtual accounts. This endpoint:

• Returns a single object { currency, amount } (one record)
• Supports both JSON and CSV response formats based on the Accept header
• Pagination: This endpoint does not accept pagination parameters

Sample Response (JSON)

{
  "currency": "USD",
  "amount": "6755.67"
}

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/virtual-accounts/balances/total

Sample Request in JavaScript

async function getVirtualAccountBalancesTotal() {
  const response = await fetch('https://api.bcb.bm/v1/virtual-accounts/balances/total', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Accept': 'application/json'
    }
  });
            
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Failed to retrieve total balance: ${JSON.stringify(errorData)}`);
  }
            
  const result = await response.json();
  console.log(result.data?.amount, result.data?.currency);
  return result;
}

Required Permission: get-virtual-account-transactions

This endpoint requires the permission claim get-virtual-account-transactions to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

Creates one or more virtual (sub) accounts for a corporate client. Virtual accounts allow funds to be segregated and tracked independently while remaining linked to a single settlement account.

Required Request Properties

• items: Array of virtual account creation requests (minimum 1, maximum 1000)
  • currency: ISO-4217 currency code for the virtual account (e.g., USD, BMD)
  • accountHolderName: Human-readable label for the virtual account (required unless unallocated is true). Immutable after first update.
  • accountName: Official account title that will appear on statements (required unless unallocated is true). Immutable after first update.

Optional Request Properties

• unallocated: When set to true, creates the account in "for allocation" mode with placeholder values ("UNALLOCATED") for accountHolderName and accountName. This allows bulk pre-creation of virtual accounts for later assignment to end-customers via a one-time PATCH update.
• dob: Date of birth of the account holder, if applicable. Immutable after first update.
• nativeLanguageName: Native name of the account holder's language, if applicable (max 255 characters). Immutable after first update.
• callbackUrl: URL to receive notifications when the batch job completes (optional)
• clientReference: External reference provided by the client to aid reconciliation (max 35 characters) - per item
• customHeaders: Object of string key/value pairs to be echoed back in the completion callback. Limits: up to 10 headers; each key ≤ 50 characters; each value ≤ 500 characters.

Unallocated Accounts

Operationally, clients often need to pre-create many virtual accounts to allocate later. The unallocated flag enables a safe "for allocation" mode:

• Creates accounts with generic placeholder values: "UNALLOCATED" for accountHolderName and accountName
• When unallocated is true, the accountHolderName and accountName fields become optional
• Allows a one-time update via PATCH when the account is assigned to a real end-customer
• Important: The following fields are immutable after the first update: accountHolderName, accountName, dob, and nativeLanguageName

Asynchronous Processing

Virtual account creation requests are processed asynchronously to ensure optimal performance and reliability:

• Immediate Response: You receive a job ID and status URLs immediately upon submission
• Status Monitoring: Use the provided status URL to monitor job progress
• Result Retrieval: Use the provided result URL to fetch final outcomes when complete
• Callback Notifications: Optionally provide a callback URL for automatic notifications afther job completes

Message Signing

Callback notifications are signed. When your client configuration enables response signing, callbacks use the asymmetric option (RSA-PSS + SHA-256) and include Bcb-Signature, Bcb-Timestamp, Bcb-Nonce, and Bcb-Signature-Version (e.g., rsa-v1). If asymmetry is not configured, callbacks use the HMAC option with your Message Signing Secret and no Bcb-Signature-Version header. See the Message Signing guide for verification steps.

Virtual Account Structure

Each successfully created virtual account will contain the following properties:

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

Job Status Tracking

The response includes URLs for monitoring your batch job:

• Status URL: Poll this URL to check job progress and completion status
• Result URL: Access this URL to retrieve detailed results for each virtual account
• Job ID: Unique identifier for tracking your batch job

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/virtual-accounts

Idempotency

The API supports idempotency through the optional Idempotency-Key header:

• If no idempotency key is provided, the request is processed normally (duplicates are possible)
• If a valid UUID idempotency key is provided, the system stores the key and associates it with the batch job
• If the same idempotency key is received again, the system returns the previously stored response
• Idempotency keys are user-specific - different users with the same keys don't share cached responses
• The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")

Sample Request in JavaScript

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();

Required Permission: create-virtual-account

This endpoint requires the permission claim create-virtual-account to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

Retrieves all virtual accounts for the authenticated corporate client. This endpoint:

• Returns a paginated list of virtual accounts for the client
• Response contains the client’s real (non-virtual) accounts as well:
• Settlement Account – the primary clearing account used for cash movements. Account category: "CMS Settlement".
• Parent Account – the parent account under which all virtual accounts are organised. Account category: "CMS Parent Cate".
• Virtual accounts have the category "CMS Sub Acct".
• Supports optional currency filtering to return only accounts in a specific currency
• Supports pagination for efficient handling of large account datasets

Filtering

Use the optional currency query parameter to filter results:

• Must be a valid 3-letter ISO currency code (e.g., USD, BMD, EUR)
• If omitted, accounts in all currencies are returned

Pagination

This endpoint uses cursor-based pagination with server-side result-set management:

• First Request: Optionally specify pageSize (default: 100, max: 1000). The server creates a cursor and returns a pageToken.
• Subsequent Requests: Use the pageToken from previous responses with pageStart to navigate pages.
• Page Token: Contains encoded pagination context including pageSize, so don't specify pageSize in subsequent requests.
• Total Pages: Calculate using Math.ceil(total_size / page_size) from the response metadata.

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/virtual-accounts

Sample Request in JavaScript

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);

Required Permission: get-virtual-accounts

This endpoint requires the permission claim get-virtual-accounts to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.