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

Initiates a debit transfer from a virtual (sub) account to transfer funds to the parent account and ultimately to the settlement account. This endpoint allows corporate clients to withdraw funds from their virtual accounts for settlement purposes.

Use Case: As a corporate client, I want to debit a sub account to transfer funds to the parent account and ultimately to the settlement account.

Key Features:

• Transfers funds from a virtual account to a main account
• Supports idempotency to prevent duplicate transactions
• Validates account numbers and currency matching
• Supports both JSON and CSV response formats
• Automatic account number validation and matching

Important Notes:

• The virtual account number (debitAccountNumber) is specified in the URL route, not in the request body
• Ensure the virtual account has sufficient funds before making the request

Virtual Account Hierarchy Virtual accounts are sub-accounts linked to a parent account:

Virtual Account (Sub-Account) → Parent Account

When debiting a virtual account, funds flow from the virtual account to the parent account.

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 for a new transaction, the system stores the key and associates it with the transaction results
• If the same idempotency key is received again for the same endpoint/action, 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").

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/{accountNumber}/transfers/debit

Sample Request in JavaScript:

async function debitVirtualAccount() {
  try {
    const accountNumber = "1000000000"; // Virtual account number
    const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${accountNumber}/transfers/debit`, {
      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({
        debitAmount: "1000.00",
        debitAmountCurrency: "USD",
        creditAccountNumber: "1000320567", // Parent/settlement account
        creditAmountCurrency: "USD", // Must match debitAmountCurrency
      })
    });
            
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Debit transfer failed: ${JSON.stringify(errorData)}`);
    }
            
    const data = await response.json();
    console.log('Debit transfer result:', data);
            
    // Example processing of the returned object
    const { id, status, uniqueIdentifier, details, linkedActivities } = data;
    const { debitAmount, valueDate, childTransactionId, creditAmountCurrency, debitAccountNumber, creditAccountNumber } = details;

    // Log the main transfer details
    console.log('Transaction ID:', id);
    console.log('Status:', status);
    console.log('Unique Identifier:', uniqueIdentifier);
    console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);
    console.log('Value Date:', valueDate);
    console.log('Child Transaction ID:', childTransactionId);
    console.log('Credit Amount Currency:', creditAmountCurrency);
    
    // Process debit account information
    console.log('Debit Account Number:', debitAccountNumber.number);
    
    // Process credit account information
    console.log('Credit Account Number:', creditAccountNumber.number);
    
    // Process linked activities
    linkedActivities.forEach(activity => {
      console.log('Linked Activity ID:', activity.id);
      console.log('Linked Activity Transaction Status:', activity.transactionStatus);
      console.log('Linked Activity Status:', activity.status);
      console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);
      const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;
      console.log('Linked Activity Arrangement ID:', arrangementId);
      console.log('Linked Activity Activity ID:', activityId);
      console.log('Linked Activity Product ID:', productId);
      console.log('Linked Activity Currency ID:', currencyId);
      console.log('Linked Activity Effective Date:', effectiveDate);
    });
    
    // Final status logging
    if (status === 'SUCCESS') {
      console.log('The debit transfer was successful.');
    } else {
      console.log('The debit transfer failed:', status);
    }
            
  } catch (error) {
    console.error('Error debiting virtual account:', error);
  }
}

// Execute example
debitVirtualAccount();

Required Permission: withdraw-virtual-account

This endpoint requires the permission claim withdraw-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.

Corporate Client initiates Settlement request to BCB to debit Settlement Account and credit to Counterparty Account. This endpoint allows clients to transfer funds from a settlement account to an internal counterparty account.

Key Features:

• Transfers funds from a settlement account to an internal counterparty account
• Supports idempotency to prevent duplicate transactions
• Validates account numbers and currency matching
• Supports both JSON and CSV response formats
• Automatic settlement account number validation

Important Notes:

• The settlementAccountNumber in the route parameter identifies the source settlement account
• The creditAccountNumber in the request body specifies the destination counterparty account
• Ensure the settlement account has sufficient funds before making the request
• Settlement accounts must be in an active state to process transfers

Settlement Account Structure

Settlement accounts are special accounts used for counterparty transactions:

Settlement Account → Counterparty Account (Internal)

When processing a settlement transfer, funds flow from the settlement account to the counterparty account.

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 for a new transaction, the system stores the key and associates it with the transaction results
• If the same idempotency key is received again for the same endpoint/action, 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").

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/{settlementAccountNumber}/settlements/internal

Sample Request in JavaScript:

async function processInternalSettlement() {
  try {
    const settlementAccountNumber = "1000320559";
    const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${settlementAccountNumber}/settlements/internal`, {
      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({
        debitCurrency: "USD",
        creditAmount: {
          amount: "1000.00",
          currency: "USD"
        },
        creditAccountNumber: "1000076925"
      })
    });

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

    const data = await response.json();
    console.log('Internal settlement result:', data);

    // Example processing of the returned object
    const { id, status, uniqueIdentifier, details, linkedActivities } = data;
    const { creditAmount, debitAmountCurrency, debitAccountNumber, creditAccountNumber, valueDate } = details;

    // Log the main transfer details
    console.log('Transaction ID:', id);
    console.log('Status:', status);
    console.log('Unique Identifier:', uniqueIdentifier);
    console.log('Credit Amount:', creditAmount.amount, creditAmount.currency);
    console.log('Debit Amount Currency:', debitAmountCurrency);
    console.log('Value Date:', valueDate);

    // Process debit account information (settlement account)
    console.log('Debit Account Number:', debitAccountNumber.number);

    // Process credit account information (counterparty account)
    console.log('Credit Account Number:', creditAccountNumber.number);

    // Final status logging
    if (status === 'success') {
      console.log('The internal settlement was successful.');
    } else {
      console.log('The internal settlement failed:', status);
    }
  } catch (error) {
    console.error('Error processing internal settlement:', error);
  }
}

processInternalSettlement();

Required Permission: counter-party-settlement-transaction

This endpoint requires the permission claim counter-party-settlement-transaction 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.

Corporate Client initiates External Settlement request to BCB to debit Settlement Account and credit to External Counterparty Account. This endpoint allows clients to transfer funds from a settlement account to an external counterparty account.

Key Features:

• Transfers funds from a settlement account to an external counterparty account
• Supports idempotency to prevent duplicate transactions
• Supports both JSON and CSV response formats
• Automatic settlement account number validation
• Includes beneficiary and ordering customer information for external transfers

Important Notes:

• The settlementAccountNumber in the route parameter identifies the source settlement account
• The request body specifies the destination external counterparty account via creditorAccount.identification
• Ensure the settlement account has sufficient funds before making the request
• Settlement accounts must be in an active state to process transfers
• External transfers require additional beneficiary information for compliance

Settlement Account Structure

Settlement accounts are special accounts used for counterparty transactions:

Settlement Account → External Counterparty Account

When processing an external settlement transfer, funds flow from the settlement account to the external counterparty account.

External Transfer Requirements

External transfers require additional information for regulatory compliance:

• debitCurrency: Currency to debit from the settlement account (e.g., "USD")
• creditAmount: Amount and currency to credit externally (e.g., { amount: "19", currency: "GBP" })
• debtor: Ordering customer information (e.g., company name or reference)
• debtorAgent: Ordering bank/agent identifier (free text)
• creditorAccount.identification: External beneficiary account identifier
• creditorAccount.name / additionalInformation: Beneficiary name and auxiliary details
• chargesType: Who bears charges (e.g., OUR, BEN, SHA)
• creditorAgent: Beneficiary bank info (identification, name, additionalInformation)
• intermediaryAgent (optional): Intermediary bank info (identification, name, additionalInformation)
• remittanceInformation (optional): Unstructured remittance lines

Creditor Agent (Beneficiary Bank)

• If creditorAgent.identification (BIC/bank identifier) is provided, creditorAgent.name and creditorAgent.additionalInformation are optional and may be omitted.
• If creditorAgent.identification is not provided, supply creditorAgent.name and creditorAgent.additionalInformation to identify the beneficiary bank.

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 for a new transaction, the system stores the key and associates it with the transaction results
• If the same idempotency key is received again for the same endpoint/action, 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").

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/{settlementAccountNumber}/settlements/external

Sample Request in JavaScript:

async function processExternalSettlement() {
  try {
    const settlementAccountNumber = "1000320559";
    const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${settlementAccountNumber}/settlements/external`, {
      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({
        debitCurrency: "USD",
        creditAmount: {
          amount: "19",
          currency: "GBP"
        },
        debtor: "ACME GLOBAL TRADING INC.",
        debtorAgent: "FIRST ATLANTIC BANK",
        creditorAccount: {
          identification: "GB29NWBK60161331926819",
          name: "OMEGA INTERNATIONAL LTD.",
          additionalInformation: ["LONDON", "GB"]
        },
        chargesType: "OUR",
        creditorAgent: {
          identification: "//ZZ123456789",
          name: "OMEGA BANK",
          additionalInformation: ["LONDON", "UK"]
        },
        intermediaryAgent: {
          identification: "INTL",
          name: "EURO CLEAR BANK",
          additionalInformation: ["BRUSSELS", "BE"]
        },
        remittanceInformation: ["INVOICE 2025-00042"]
      })
    });

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

    const data = await response.json();
    console.log('External settlement result:', data);

    // Example processing of the returned object
    const { id, status, uniqueIdentifier, details, linkedActivities } = data;
    const { creditAmount, debitAmountCurrency, debitAccountNumber, creditAccountNumber, valueDate } = details;

    // Log the main transfer details
    console.log('Transaction ID:', id);
    console.log('Status:', status);
    console.log('Unique Identifier:', uniqueIdentifier);
    console.log('Credit Amount:', creditAmount.amount, creditAmount.currency);
    console.log('Debit Amount Currency:', debitAmountCurrency);
    console.log('Value Date:', valueDate);

    // Process debit account information (settlement account)
    console.log('Debit Account Number:', debitAccountNumber.number);

    // Process credit account information (external counterparty account)
    console.log('Credit Account Number:', creditAccountNumber.number);

    // Final status logging
    if (status === 'success') {
      console.log('The external settlement was successful.');
    } else {
      console.log('The external settlement failed:', status);
    }
  } catch (error) {
    console.error('Error processing external settlement:', error);
  }
}

processExternalSettlement();

Required Permission: counter-party-settlement-transaction

This endpoint requires the permission claim counter-party-settlement-transaction 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.