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

Corporate Client initiates External Withdrawal request to BCB to debit Virtual Account and credit to External Beneficiary Account. This endpoint allows clients to withdraw funds from a virtual account to an external beneficiary account.

Key Features:

• Withdraws funds from a virtual account to an external beneficiary account
• Supports idempotency to prevent duplicate transactions
• Supports both JSON and CSV response formats
• Automatic virtual account number validation
• Includes comprehensive beneficiary and ordering customer information for external transfers
• Supports both the existing same-currency payload and the additive cross-currency FX payload

Supported Request Formats

Use one of the following request shapes:

Existing format - same-currency:

{
  "debitCurrency": "USD",
  "creditAmount": {
    "currency": "USD",
    "amount": 2500
  }
}

Additive format - cross-currency FX:

{
  "debitAmount": {
    "currency": "USD",
    "amount": 2500
  },
  "creditAmount": {
    "currency": "HKD"
  }
}

Cross-Currency FX

• Provide debitAmount (currency and amount) when you want the debit side to be authoritative.

• Provide only creditAmount.currency in that case; the bank assigns the exchange rate and final credited amount before forwarding to the beneficiary.

• If debitAmount is omitted, the existing debitCurrency + creditAmount (currency + amount) format applies with no change to current behaviour.

• debitCurrency is not deprecated and remains fully supported.

• Both payload formats are accepted and return a successful response.

Important Notes:

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

Virtual Account Withdrawal Structure

Virtual account withdrawals transfer funds from virtual accounts to external beneficiary accounts:

Virtual Account → External Beneficiary Account

When processing an external withdrawal transfer, funds flow from the virtual account to the external beneficiary account.

External Transfer Requirements

External transfers require additional information for regulatory compliance:

• debitCurrency: Currency to debit from the virtual account (e.g., "USD")
• creditAmount: Amount and currency to credit externally (e.g., { amount: "2500.00", currency: "USD" })
• debtor: Ordering customer name or reference (required, max 35 characters)
• debtorAgent: Ordering bank/agent identifier (free text, max 35 characters) - Optional
• creditorAccount.identification: External beneficiary account identifier (required, max 35 characters)
• creditorAccount.name / additionalInformation: Beneficiary name and auxiliary details (optional)
• 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/{virtualAccountId}/withdrawals/external

Sample Request in JavaScript (Existing same-currency format):

async function processExternalWithdrawal() {
  try {
    const virtualAccountId = "1000320575";
    const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountId}/withdrawals/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: {
          currency: "USD",
          amount: "2500.00"
        },
        debtor: "John Smith Corporation",
        debtorAgent: "CHASUS33XXX",
        creditorAccount: {
          identification: "GB29NWBK60161331926819",
          name: "Acme Manufacturing Ltd",
          additionalInformation: [
            "123 Business Street",
            "London, UK SW1A 1AA"
          ]
        },
        chargesType: "OUR",
        creditorAgent: {
          identification: "NWBKGB2L",
          name: "NatWest Bank",
          additionalInformation: [
            "250 Bishopsgate",
            "London, UK EC2M 4AA"
          ]
        },
        intermediaryAgent: {
          identification: "CHASUS33",
          name: "JPMorgan Chase Bank",
          additionalInformation: [
            "383 Madison Avenue",
            "New York, NY 10017"
          ]
        },
        remittanceInformation: [
          "Withdrawal from Virtual Account VA-2024-001",
          "Transfer to external beneficiary account",
          "Reference: WD-2024-789456"
        ]
      })
    });

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

    const data = await response.json();
    console.log('External withdrawal 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 (virtual account)
    console.log('Debit Account Number:', debitAccountNumber.number);

    // Process credit account information (external beneficiary account)
    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 external withdrawal was successful.');
    } else {
      console.log('The external withdrawal failed:', status);
    }
  } catch (error) {
    console.error('Error processing external withdrawal:', error);
  }
}

// Example usage:
processExternalWithdrawal();

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 External Withdrawal request to BCB to debit Virtual Account and credit to External Beneficiary Account. This endpoint allows clients to withdraw funds from a virtual account to an external beneficiary account.

V2 difference: The debtor field is a structured object ({ name, additionalInformation[] }) instead of the v1 plain string. All other fields, behaviour, response shape, idempotency, and content negotiation are identical to v1.

Key Features:

• Withdraws funds from a virtual account to an external beneficiary account
• Supports idempotency to prevent duplicate transactions
• Supports both JSON and CSV response formats
• Automatic virtual account number validation
• Includes comprehensive beneficiary and ordering customer information for external transfers
• Supports both the existing same-currency payload and the additive cross-currency FX payload
• V2: Structured debtor with name and up to 3 address lines

Structured Debtor (V2)

The debtor field must be an object containing the ordering customer name and optional address lines:

{
  "debtor": {
    "name": "John Smith Corporation",
    "additionalInformation": [
      "123 Business Street",
      "London, UK SW1A 1AA"
    ]
  }
}

• debtor.name: Required, max 35 characters
• debtor.additionalInformation: Optional, up to 3 lines, each max 35 characters

Supported Request Formats

Use one of the following request shapes:

Existing format - same-currency:

{
  "debitCurrency": "USD",
  "creditAmount": {
    "currency": "USD",
    "amount": 2500
  }
}

Additive format - cross-currency FX:

{
  "debitAmount": {
    "currency": "USD",
    "amount": 2500
  },
  "creditAmount": {
    "currency": "HKD"
  }
}

Cross-Currency FX

• Provide debitAmount (currency and amount) when you want the debit side to be authoritative.

• Provide only creditAmount.currency in that case; the bank assigns the exchange rate and final credited amount before forwarding to the beneficiary.

• If debitAmount is omitted, the existing debitCurrency + creditAmount (currency + amount) format applies with no change to current behaviour.

• debitCurrency is not deprecated and remains fully supported.

• Both payload formats are accepted and return a successful response.

Important Notes:

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

Virtual Account Withdrawal Structure

Virtual account withdrawals transfer funds from virtual accounts to external beneficiary accounts:

Virtual Account → External Beneficiary Account

When processing an external withdrawal transfer, funds flow from the virtual account to the external beneficiary account.

External Transfer Requirements

External transfers require additional information for regulatory compliance:

• debitCurrency: Currency to debit from the virtual account (e.g., "USD")
• creditAmount: Amount and currency to credit externally (e.g., { amount: "2500.00", currency: "USD" })
• debtor: Ordering customer information as { name, additionalInformation[] } (V2: structured object; V1 uses a plain string)
• debtor.additionalInformation: Up to 3 lines, each max 35 characters
• debtorAgent: Ordering bank/agent identifier (free text, max 35 characters) - Optional
• creditorAccount.identification: External beneficiary account identifier (required, max 35 characters)
• creditorAccount.name / additionalInformation: Beneficiary name and auxiliary details (optional)
• 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/v2/virtual-accounts/{virtualAccountId}/withdrawals/external

Sample Request in JavaScript (Cross-currency FX format):

async function processExternalWithdrawalV2() {
  try {
    const virtualAccountId = "1000320575";
    const response = await fetch(`https://api.bcb.bm/v2/virtual-accounts/${virtualAccountId}/withdrawals/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({
        debitAmount: {
          currency: "USD",
          amount: "2500.00"
        },
        creditAmount: {
          currency: "HKD"
        },
        debtor: {
          name: "John Smith Corporation",
          additionalInformation: [
            "123 Business Street",
            "London, UK SW1A 1AA"
          ]
        },
        debtorAgent: "CHASUS33XXX",
        creditorAccount: {
          identification: "GB29NWBK60161331926819",
          name: "Acme Manufacturing Ltd",
          additionalInformation: [
            "123 Business Street",
            "London, UK SW1A 1AA"
          ]
        },
        chargesType: "OUR",
        creditorAgent: {
          identification: "NWBKGB2L",
          name: "NatWest Bank",
          additionalInformation: [
            "250 Bishopsgate",
            "London, UK EC2M 4AA"
          ]
        },
        intermediaryAgent: {
          identification: "CHASUS33",
          name: "JPMorgan Chase Bank",
          additionalInformation: [
            "383 Madison Avenue",
            "New York, NY 10017"
          ]
        },
        remittanceInformation: [
          "Withdrawal from Virtual Account VA-2024-001",
          "Transfer to external beneficiary account",
          "Reference: WD-2024-789456"
        ]
      })
    });

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

    const data = await response.json();
    console.log('External withdrawal 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 (virtual account)
    console.log('Debit Account Number:', debitAccountNumber.number);

    // Process credit account information (external beneficiary account)
    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 external withdrawal was successful.');
    } else {
      console.log('The external withdrawal failed:', status);
    }
  } catch (error) {
    console.error('Error processing external withdrawal:', error);
  }
}

// Example usage:
processExternalWithdrawalV2();

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.