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 domestic same-currency bank transfer over the ACH clearing network. The request carries debtor account, instructed amount, debit currency, creditor account + bank reference, and 1–2 lines of remittance information. JSON and CSV response formats are supported via the Accept header.

Supported Currencies

Only USD and BMD are accepted. debitCurrency and instructedAmount.currency must be identical - cross-currency is not supported on this endpoint.

Settlement and Cut-Off

Transfers settle same-day when submitted before 3:15 PM local AST; later submissions are queued for the next business day. The value/effective date in the response reflects the settlement date.

Creditor Bank Reference

Provide creditorBank with the destination bank bankCode and currency. The API validates this combination against the configured bank reference lookup. If the bankCode and currency combination is not found, the API returns 400 Bad Request with error code BANK_REFERENCE_NOT_FOUND.

The ACH local bank reference lookup contains the following values:

Request basics

• Endpoint: POST https://api.bcb.bm/v1/payments/ach-local
• Authorization: Bearer {token} (required).
• Accept: application/json (default) or text/csv.
• Idempotency-Key: optional UUID v4 header (≤ 255 chars). See below.

Idempotency

The API supports idempotency through the optional Idempotency-Key header. When supplied, the server caches the successful response and replays it on repeat calls.

• If no idempotency key is provided, the request is processed normally (duplicates are possible).
• If a valid UUID key is supplied, the system stores the response of the first 2xx outcome and replays it on subsequent calls with the same key.
• TTL (cache lifetime): the stored response is retained for a limited window (currently on the order of one hour). After expiry the same key is treated as a new request - but instructionIdentification deduplication still applies for 24 hours. Plan client-side retries to land inside the cache window.
• Scope: keys are partitioned by client/user, HTTP method, and request path. The same key on /payments/ach-local and /payments/swift is not shared - each endpoint has its own cache slot.
• Concurrency: if a second request with the same key arrives while the first is still in flight, the second is rejected with 409 Conflict and message "Request is already being processed." Wait and retry.
• Body mismatch: request bodies are not compared on replay. If you reuse a key with a different body, the original cached response is returned - the new body is ignored. Mint a fresh key for any logically different request.
• Non-2xx responses are not cached. A 4xx validation failure or 5xx server error can be retried with the same key and will execute again.

Deduplication

A separate, business-level guard on the instructionIdentification field, applied independently of the Idempotency-Key header:

• Reusing an instructionIdentification for an active ACH local payment is rejected with 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID.
• Use a fresh instructionIdentification for each new payment intent. Reuse it (with the same Idempotency-Key) only when retrying the exact same payment.
• The deduplication window is currently configured as 24 hours from the first accepted request.

How Idempotency-Key and instructionIdentification combine

They are independent mechanisms with different purposes.

• Idempotency-Key (header) is a transport-level retry token. It lets you safely retry the same HTTP call and get the original response replayed.
• instructionIdentification (body) is the business identifier of the payment. It is persisted on the payment record and forwarded downstream. To prevent the same payment intent from being submitted twice, a value that is already in flight or recently accepted is rejected with 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID (window: 24 hours).

Resilience: classifying responses

The dedupe and idempotency layers together cover three distinct failure modes. The status code tells you what to do next:

• 503 DEDUPE_LOCK_UNAVAILABLE - the duplicate-check store could not acquire its lock for instructionIdentification. The payment was not submitted to core banking. Safe to retry after a short backoff with the same instructionIdentification (and the same Idempotency-Key, if you used one). This is not "a duplicate was detected" - it is "we could not verify uniqueness right now."
• 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID - this instructionIdentification was already accepted within the 24-hour window. Do not retry the POST; query payment status to reconcile.
• 5xx, connection timeout, or no response - outcome unknown. Retry with the same Idempotency-Key and same instructionIdentification. The server will either replay the original 201 (if the first attempt landed) or return 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID (also indicating the first attempt landed).

Decision tree in pseudocode:

async function submitAchLocalPayment(paymentRequest, idempotencyKey) {
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    const res = await postPayment(paymentRequest, idempotencyKey);
            
    switch (res.status) {
      case 201:
        return res.body; // success - persist paymentId against instructionIdentification
            
      case 409: // ACH_LOCAL_DUPLICATE_INSTRUCTION_ID - intent already submitted
        // Do NOT retry with a new instructionId. Reconcile via status lookup.
        return await reconcileViaStatusLookup(paymentRequest.instructionIdentification);
            
      case 503: // DEDUPE_LOCK_UNAVAILABLE - NOT submitted, safe to retry as-is
      case 502: case 504: // transient gateway
        await backoff(attempt); continue;
            
      default:
        if (isNetworkError(res)) { // unknown outcome - retry SAME key + SAME instructionId
          await backoff(attempt); continue;
        }
        throw res; // 4xx other - fix request, mint NEW instructionId before retrying
    }
  }
}

When to rotate instructionIdentification

// NEW payment intent (user clicks "Send" again, new business event)
const intent = {
  instructionIdentification: uuid(),
  idempotencyKey: uuid()
};
            
// RETRY of the SAME intent (5xx, 503 DEDUPE_LOCK_UNAVAILABLE, timeout)
//   -> keep BOTH values stable; the server will replay or short-circuit safely
retry(intent);
            
// After 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID
//   -> do NOT POST again; query status to reconcile
await getPaymentStatus(intent.instructionIdentification);

Idempotency-Key lifecycle (client-side checklist)

• Mint the key before the HTTP call and persist it alongside the payment intent so a process restart or retry can still find it.
• Reuse it for every retry of the same intent; treat it as "spent" only after a terminal (2xx or non-retryable 4xx) response.
• Plan retries to land inside the cache window (~1 hour). Beyond that, instructionIdentification (24 h) is your remaining guard.

Validation Rules

Minimal Request Example

const res = await fetch('https://api.bcb.bm/v1/payments/ach-local', {
  method: 'POST',
  headers: {
    'Authorization':   `Bearer ${token}`,
    'Content-Type':    'application/json',
    'Accept':          'application/json',
    'Idempotency-Key': idempotencyKey, // UUID v4, per payment intent
  },
  body: JSON.stringify(paymentRequest), // shape: see request schema below
});

The full request and response schemas, including field types and a worked example, are rendered below from the API contract.

Required Permission: payment-ach

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

Initiates an international wire transfer over the SWIFT network. The request carries source and destination account information, payment amount and currency, beneficiary details, and remittance/reference information. Both JSON and CSV response formats are supported via the Accept header.

Cross-Currency FX

For cross-currency payments you may supply the debit amount instead of the instructed amount (additive format):

• Send debitAmount (currency + amount) as the exact amount to be debited.
• Send instructedAmount with currency only (amount omitted); the bank assigns the exchange rate and computes the credited amount.
• Do not send both debitAmount.amount and instructedAmount.amount.
• If debitAmount is omitted, instructedAmount (currency + amount) is used as the standard same-currency behaviour.

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.

Request basics

• Endpoint: POST https://api.bcb.bm/v1/payments/swift
• Authorization: Bearer {token}.
• Accept: application/json (default) or text/csv.
• Idempotency-Key: optional UUID v4 header (≤ 255 chars). See below.

Idempotency

The API supports idempotency through the optional Idempotency-Key header. When supplied, the server caches the successful response and replays it on repeat calls.

• If no idempotency key is provided, the request is processed normally (duplicates are possible).
• If a valid UUID key is supplied, the system stores the response of the first 2xx outcome and replays it on subsequent calls with the same key.
• TTL (cache lifetime): the stored response is retained for a limited window (currently on the order of one hour). After expiry the same key is treated as a new request - but instructionIdentification deduplication still applies for 24 hours. Plan client-side retries to land inside the cache window.
• Scope: keys are partitioned by client/user, HTTP method, and request path. The same key on /payments/swift and /payments/ach-local is not shared - each endpoint has its own cache slot.
• Concurrency: if a second request with the same key arrives while the first is still in flight, the second is rejected with 409 Conflict and message "Request is already being processed." Wait and retry.
• Body mismatch: request bodies are not compared on replay. If you reuse a key with a different body, the original cached response is returned - the new body is ignored. Mint a fresh key for any logically different request.
• Non-2xx responses are not cached. A 4xx validation failure or 5xx server error can be retried with the same key and will execute again.

Deduplication

A separate, business-level guard on the instructionIdentification field, applied independently of the Idempotency-Key header:

• Reusing an instructionIdentification for an active payment is rejected with 409 PAYMENT_DUPLICATE_INSTRUCTION_ID.
• Use a fresh instructionIdentification for each new payment intent. Reuse it (with the same Idempotency-Key) only when retrying the exact same payment.
• The deduplication window is currently configured as 24 hours from the first accepted request.

How Idempotency-Key and instructionIdentification combine

They are independent mechanisms with different purposes.

• Idempotency-Key (header) is a transport-level retry token. It lets you safely retry the same HTTP call and get the original response replayed.
• instructionIdentification (body) is the business identifier of the payment. It is persisted on the payment record and forwarded downstream. To prevent the same payment intent from being submitted twice, a value that is already in flight or recently accepted is rejected with 409 PAYMENT_DUPLICATE_INSTRUCTION_ID (window: 24 hours).

Resilience: classifying responses

The dedupe and idempotency layers together cover three distinct failure modes. The status code tells you what to do next:

• 503 DEDUPE_LOCK_UNAVAILABLE - the duplicate-check store could not acquire its lock for instructionIdentification. The payment was not submitted to core banking. Safe to retry after a short backoff with the same instructionIdentification (and the same Idempotency-Key, if you used one). This is not "a duplicate was detected" - it is "we could not verify uniqueness right now."
• 409 PAYMENT_DUPLICATE_INSTRUCTION_ID - this instructionIdentification was already accepted within the 24-hour window. Do not retry the POST; query payment status to reconcile.
• 5xx, connection timeout, or no response - outcome unknown. Retry with the same Idempotency-Key and same instructionIdentification. The server will either replay the original 201 (if the first attempt landed) or return 409 PAYMENT_DUPLICATE_INSTRUCTION_ID (also indicating the first attempt landed).

Decision tree in pseudocode:

async function submitPayment(paymentRequest, idempotencyKey) {
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    const res = await postPayment(paymentRequest, idempotencyKey);
            
    switch (res.status) {
      case 201:
        return res.body; // success - persist paymentId against instructionIdentification
            
      case 409: // PAYMENT_DUPLICATE_INSTRUCTION_ID - intent already submitted
        // Do NOT retry with a new instructionId. Reconcile via status lookup.
        return await reconcileViaStatusLookup(paymentRequest.instructionIdentification);
            
      case 503: // DEDUPE_LOCK_UNAVAILABLE - NOT submitted, safe to retry as-is
      case 502: case 504: // transient gateway
        await backoff(attempt); continue;
            
      default:
        if (isNetworkError(res)) { // unknown outcome - retry SAME key + SAME instructionId
          await backoff(attempt); continue;
        }
        throw res; // 4xx other - fix request, mint NEW instructionId before retrying
    }
  }
}

When to rotate instructionIdentification

// NEW payment intent (user clicks "Send" again, new business event)
const intent = {
  instructionIdentification: uuid(),
  idempotencyKey: uuid()
};
            
// RETRY of the SAME intent (5xx, 503 DEDUPE_LOCK_UNAVAILABLE, timeout)
//   -> keep BOTH values stable; the server will replay or short-circuit safely
retry(intent);
            
// After 409 PAYMENT_DUPLICATE_INSTRUCTION_ID
//   -> do NOT POST again; query status to reconcile
await getPaymentStatus(intent.instructionIdentification);

Idempotency-Key lifecycle (client-side checklist)

• Mint the key before the HTTP call and persist it alongside the payment intent so a process restart or retry can still find it.
• Reuse it for every retry of the same intent; treat it as "spent" only after a terminal (2xx or non-retryable 4xx) response.
• Plan retries to land inside the cache window (~1 hour). Beyond that, instructionIdentification (24 h) is your remaining guard.

Minimal Request Example

const res = await fetch('https://api.bcb.bm/v1/payments/swift', {
  method: 'POST',
  headers: {
    'Authorization':   `Bearer ${token}`,
    'Content-Type':    'application/json',
    'Accept':          'application/json',
    'Idempotency-Key': idempotencyKey, // UUID v4, per payment intent
  },
  body: JSON.stringify(paymentRequest), // shape: see request schema below
});

The full request and response schemas, including field types and a worked example, are rendered below from the API contract.

Required Permission: payment-swift

This endpoint requires the permission claim payment-swift 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 status information for all payments associated with a specific account. This endpoint:

• Provides comprehensive payment status details including type, status, transaction ID, external reference, remittance information, amounts, value date, and exchange rate.
• Supports both JSON and CSV response formats based on the Accept header.
• Supports cursor-based pagination for efficient handling of large payment status datasets.

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/accounts/{accountNumber}/payments

Sample Request in JavaScript

async function getAllPaymentStatusesPaginated(accountNumber) {
  try {
    let allPaymentStatuses = [];
    let pageStart = 1;
    let pageToken = null;
    let totalPages = 0;

    do {
      // Build URL with pagination parameters
      let url = `https://api.bcb.bm/v1/accounts/${accountNumber}/payments`;
      const params = new URLSearchParams();
      
      if (pageStart === 1) {
        // First request: specify pageSize
        params.append('pageSize', '100');
      } else {
        // Subsequent requests: use pageToken and pageStart
        params.append('pageToken', pageToken);
        params.append('pageStart', pageStart.toString());
      }
      
      if (params.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(`Error: ${errorData.message || 'Unknown error'}`);
      }

      const data = await response.json();
      console.log(`Page ${pageStart} data:`, data);

      // Store pagination info from first request
      if (pageStart === 1 && data.meta && data.meta.pagination) {
        pageToken = data.meta.pagination.page_token;
        totalPages = Math.ceil(data.meta.pagination.total_size / data.meta.pagination.page_size);
        console.log(`Total pages: ${totalPages}, Page token: ${pageToken}`);
      }

      // Collect payment statuses from this page
      if (data.data && data.data.length > 0) {
        allPaymentStatuses.push(...data.data);
        console.log(`Collected ${data.data.length} payment statuses from page ${pageStart}`);
      }

      pageStart++;
    } while (pageStart <= totalPages);

    console.log(`Total payment statuses collected: ${allPaymentStatuses.length}`);

    // Process all collected payment statuses
    allPaymentStatuses.forEach((payment, index) => {
      console.log(`Payment ${index + 1}:`, payment.transactionId);
      console.log('Type:', payment.type);
      console.log('Status:', payment.status);
      console.log('External Reference:', payment.externalReference);
      console.log('Remittance Information:', payment.remittanceInformation);
      console.log('Value Date:', payment.valueDate);
      console.log('Debit Amount:', `${payment.debitAmount.amount} ${payment.debitAmount.currency}`);
      if (payment.creditAmount && payment.creditAmount.amount) {
        console.log('Credit Amount:', `${payment.creditAmount.amount} ${payment.creditAmount.currency}`);
      }
      console.log('-------------------');
    });

    return allPaymentStatuses;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

// Alternative: Get single page of payment statuses
async function getPaymentStatusesPage(accountNumber, pageStart = 1, pageToken = null) {
  try {
    let url = `https://api.bcb.bm/v1/accounts/${accountNumber}/payments`;
    const params = new URLSearchParams();
    
    if (pageStart === 1 && !pageToken) {
      params.append('pageSize', '50'); // Custom page size
    } else {
      params.append('pageToken', pageToken);
      params.append('pageStart', pageStart.toString());
    }
    
    if (params.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(`Error: ${errorData.message || 'Unknown error'}`);
    }

    const data = await response.json();
    console.log('Payment statuses page:', data);
    return data;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

// Example usage:
getAllPaymentStatusesPaginated('123456789'); // Retrieves all payment statuses across multiple pages
// OR
getPaymentStatusesPage('123456789', 1).then(firstPage => {
  console.log('First page:', firstPage);
  // Use firstPage.meta.pagination.page_token for subsequent requests
});

Required Permission: get-payment-status

This endpoint requires the permission claim get-payment-status 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 detailed status information for a specific payment identified by its payment ID (also known as transaction ID). This endpoint provides comprehensive status details including:

• Type: The type of payment (e.g., "Outward Swift Payment MT103 API")
• Status: Current status of the payment (e.g., "Pending", "Completed", "Reversed")
• TransactionId: Unique payment identifier (or Transaction Id)
• ExternalReference: External reference number for the payment
• RemittanceInformation: Free-text information about the purpose of the payment
• DebitAmount: The amount debited from the account, including currency code
• CreditAmount: The amount credited to the account, including currency code
• ValueDate: The date when the payment was/will be processed
• ExchangeRate: The exchange rate applied to the payment

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/payments/{paymentId}/status

Sample Request in JavaScript:

async function getPaymentStatus(paymentId) {
  try {
    const response = await fetch(`https://api.bcb.bm/v1/payments/${paymentId}/status`, {
      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(`Error: ${errorData.message || 'Unknown error'}`);
    }

    const paymentStatus = await response.json();
    console.log('Payment Status Details:');
    console.log('Payment ID:', paymentStatus.transactionId);
    console.log('Type:', paymentStatus.type);
    console.log('Status:', paymentStatus.status);
    console.log('External Reference:', paymentStatus.externalReference);
    console.log('Remittance Information:', paymentStatus.remittanceInformation);
    console.log('Value Date:', paymentStatus.valueDate);
    console.log('Debit Amount:', `${paymentStatus.debitAmount.amount} ${paymentStatus.debitAmount.currency}`);
    
    if (paymentStatus.creditAmount && paymentStatus.creditAmount.amount) {
      console.log('Credit Amount:', `${paymentStatus.creditAmount.amount} ${paymentStatus.creditAmount.currency}`);
    }
    
    // Implement business logic based on payment status
    if (paymentStatus.status === 'Completed') {
      console.log('Payment has been successfully completed.');
    } else if (paymentStatus.status === 'Pending') {
      console.log('Payment is still being processed.');
    } else if (paymentStatus.status === 'Failed') {
      console.log('Payment failed. Please check the details or contact support.');
    }
  } catch (error) {
    console.error('There was a problem retrieving the payment status:', error.message);
  }
}

// Example usage:
getPaymentStatus('PAY-001-2023');

Required Permission: get-payment-status

This endpoint requires the permission claim get-payment-status 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.