Bermuda Commercial Bank RESTful Open Banking API Implementation (v1)

Account Details

Retrieves the account details and balance. This endpoint requires authentication and returns comprehensive information for the specified account. The returned data includes:

• Number: The human-readable account number assigned by the bank.
• Label: A label provided by the account owner.
• Owners: The list of users who own this account.
• Type: The type of account.
• Balance: The account's balance including currency and amount.
• Account Attributes: Additional account information specific to Bermuda Commercial Bank.

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.bcbank.us/v1/accounts

Sample Request in JavaScript:

async function getAccountDetails(accountNumber) {
  try {
    const response = await fetch(`https://api.bcbank.us/v1/accounts/${accountNumber}`, {
      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('Account details:', data);

    // Example processing of the returned object
    const accountId = data.id;
    const accountNumber = data.number;
    const accountBalance = data.balance.amount;
    const accountCurrency = data.balance.currency;
    const accountStatus = data.accountAttributes.find(attr => attr.name === 'STATUS')?.value;
            
    console.log('Account ID:', accountId);
    console.log('Account Number:', accountNumber);
    console.log('Account Balance:', accountBalance);
    console.log('Account Currency:', accountCurrency);
    console.log('Account Status:', accountStatus);
            
    // Process all account attributes
    console.log('Account Attributes:');
    data.accountAttributes.forEach(attribute => {
      console.log(`${attribute.name}: ${attribute.value}`);
    });

    // Additional processing based on account status
    if (accountStatus === 'ACTIVE') {
      console.log('The account is active.');
    } else {
      console.log('The account is not active.');
    }
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
  }
}

// Example usage:
getAccountDetails('YOUR_ACCOUNT_NUMBER');

Required Permission: get-account

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

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/accounts/{accountNumber}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "accountId": "string",
  "cif": "string",
  "accountNumber": "string",
  "status": "string",
  "currency": "string",
  "availableBalance": {
    "currency": "string",
    "amount": "string"
  },
  "accountSubType": "string",
  "accountType": "string",
  "nickname": "string",
  "owners": [
    {
      "displayName": "string",
      "accountHolderType": "string"
    }
  ],
  "accountAttributes": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "openingDate": "string",
  "balanceEffectiveDate": "string",
  "accountRoutings": [
    {
      "scheme": "string",
      "address": "string"
    }
  ]
}

List User Accounts

Retrieves a list of all accounts associated with the authenticated user's profile. This endpoint:

• Uses the customer account number from the authenticated user's session to fetch all associated accounts.
• Requires valid authentication.
• Supports both JSON and CSV response formats based on the Accept header.
• Returns a summary version of account information (AccountSummary) containing only essential fields
• Supports cursor-based pagination for efficient handling of large account lists.

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.bcbank.us/v1/accounts

Sample Request in JavaScript

async function getAllAccountsPaginated() {
  try {
    let allAccounts = [];
    let pageStart = 1;
    let pageToken = null;
    let totalPages = 0;

    do {
      // Build URL with pagination parameters
      let url = 'https://api.bcbank.us/v1/accounts';
      const params = new URLSearchParams();
      
      if (pageStart === 1) {
        // First request: optionally 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 accounts from this page
      if (data.data && data.data.length > 0) {
        allAccounts.push(...data.data);
        console.log(`Collected ${data.data.length} accounts from page ${pageStart}`);
      }

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

    console.log(`Total accounts collected: ${allAccounts.length}`);

    // Process all collected accounts
    allAccounts.forEach((account, index) => {
      console.log(`Account ${index + 1}: ${account.number}`);
      console.log(`Balance: ${account.balance.amount} ${account.balance.currency}`);
    });

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

// Function to get a specific page of accounts
async function getAccountsPage(pageStart, pageToken = null) {
  try {
    // Build URL
    let url = 'https://api.bcbank.us/v1/accounts';
    const params = new URLSearchParams();
    
    if (pageStart === 1) {
      // First request: optionally 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('Accounts page:', data);
    return data;
  } catch (error) {
    console.error('There was a problem with the fetch operation:', error.message);
    throw error;
  }
}

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

Required Permission: get-all-accounts

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

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/accounts' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "accountId": "string",
      "cif": "string",
      "accountNumber": "string",
      "status": "string",
      "currency": "string",
      "availableBalance": {},
      "accountSubType": "string",
      "accountType": "string",
      "nickname": "string",
      "owners": [
        {}
      ],
      "accountAttributes": [
        {}
      ],
      "openingDate": "string",
      "balanceEffectiveDate": "string",
      "accountRoutings": [
        {}
      ]
    }
  ]
}

List payment statuses for an account

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.bcbank.us/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.bcbank.us/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.bcbank.us/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.

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/accounts/{accountNumber}/payments' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "type": "string",
      "externalReference": "string",
      "status": "string",
      "remittanceInformation": "string",
      "transactionId": "string",
      "debitAmount": {
        "currency": {},
        "amount": {}
      },
      "valueDate": "string",
      "creditAmount": {
        "currency": {},
        "amount": {}
      },
      "exchangeRate": 0
    }
  ]
}

ACH Local Payment

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:

Bank Code	Currency	Bank Name
BUTTERFIELD	BMD	Bank of N.T. Butterfield & Sons
HSBC	BMD	HSBC Bermuda
CLARIEN	BMD	Clarien Bank Bermuda
BUTTERFIELD	USD	Bank of N.T. Butterfield & Sons
HSBC	USD	HSBC Bermuda
CLARIEN	USD	Clarien Bank Bermuda

Request basics

• Endpoint: POST https://api.bcbank.us/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).

Idempotency-Key	instructionIdentification	Behaviour
no	no	No protection. Each call creates a new payment.
yes	no	HTTP retries of the same call replay the original response. A new Idempotency-Key creates a new payment.
no	yes	First call is processed normally. Reusing the same business identifier within 24 hours is rejected with 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID. The original success response is not replayed - record it client-side.
yes	yes	Recommended. HTTP retries of the same call replay the original response. A new Idempotency-Key reusing an in-flight instructionIdentification is rejected with 409.

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

Field	Constraint
instructionIdentification	Optional, max 16 characters
debtorAccount.identification	Required, max 36 characters
debitCurrency	Required, exactly 3 characters, USD or BMD only
instructedAmount.amount	Required, max 18 characters, valid decimal (up to 2 decimal places)
instructedAmount.currency	Required, exactly 3 characters, USD or BMD only, must equal debitCurrency
creditorAccount.identification	Required, max 17 characters
creditorAccount.name	Required, max 22 characters
creditorBank.bankCode	Required, 1-100 characters (see Creditor Bank Reference below)
creditorBank.currency	Required, exactly 3 characters, must match debitCurrency
remittanceInformation	Required, 1–2 non-empty lines, each max 35 characters

Minimal Request Example

const res = await fetch('https://api.bcbank.us/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.

Request body application/json

Responses

Created - The ACH local payment was successfully processed.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/payments/ach-local' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "instructionIdentification": "REF-123456",
  "debtorAccount": {
    "identification": 123456789012
  },
  "debitCurrency": "USD",
  "instructedAmount": {
    "currency": "USD",
    "amount": 1500
  },
  "creditorAccount": {
    "identification": 9876543210123,
    "name": "John Doe",
    "additionalInformation": null
  },
  "creditorBank": {
    "bankCode": "HSBC",
    "currency": "USD"
  },
  "remittanceInformation": [
    "Invoice 2026-0001"
  ]
}'

{
  "id": "string",
  "status": "string",
  "transactionStatus": "string",
  "uniqueIdentifier": "string",
  "details": {
    "extReference": "string",
    "instructedAmount": {
      "currency": {},
      "amount": {}
    },
    "debtorAccount": {
      "schemeName": {},
      "identification": {},
      "Name": {}
    },
    "beneficiaryAccount": {
      "schemeName": {},
      "identification": {},
      "Name": {}
    },
    "creditorAccount": {
      "schemeName": {},
      "identification": {},
      "Name": {}
    },
    "settlementDetails": {
      "amountCredited": {},
      "amountDebited": {},
      "valueDate": {},
      "recordStatus": {}
    },
    "chargeDetails": {
      "chargesType": {},
      "chargeAmount": {},
      "chargeAccount": {},
      "chargeAnalysis": {}
    },
    "remittanceInformation": [
      {
        "unstructured": {}
      }
    ],
    "beneficiary": "string",
    "beneficiaryAgent": "string",
    "intermediaryAgent": "string"
  },
  "linkedActivities": [
    {
      "id": "string",
      "transactionStatus": "string",
      "status": "string",
      "uniqueIdentifier": "string",
      "activityDetails": {
        "arrangementId": {},
        "activityId": {},
        "productId": {},
        "currencyId": {},
        "effectiveDate": {}
      }
    }
  ]
}

SWIFT Payment

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.bcbank.us/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).

Idempotency-Key	instructionIdentification	Behaviour
no	no	No protection. Each call creates a new payment.
yes	no	HTTP retries of the same call replay the original response. A new Idempotency-Key creates a new payment.
no	yes	First call is processed normally. Reusing the same business identifier within 24 hours is rejected with 409 PAYMENT_DUPLICATE_INSTRUCTION_ID. The original success response is not replayed - record it client-side.
yes	yes	Recommended. HTTP retries of the same call replay the original response. A new Idempotency-Key reusing an in-flight instructionIdentification is rejected with 409.

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.bcbank.us/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.

Request body application/json

Responses

Created - The payment was successfully processed.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/payments/swift' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "instructionIdentification": "PAY-2024-03-21-001",
  "debtorAccount": {
    "identification": "BM12BCBK00001234567890"
  },
  "instructedAmount": {
    "currency": "USD",
    "amount": 50000
  },
  "debitAmount": null,
  "creditorAccount": {
    "identification": "US12BCBK00001234567890",
    "name": "Global Investment Services Inc",
    "additionalInformation": [
      "350 Fifth Avenue",
      "New York, NY 10118",
      "United States"
    ]
  },
  "creditorAgent": {
    "identification": "CHASUS33",
    "name": "JPMorgan Chase Bank",
    "additionalInformation": [
      "383 Madison Avenue",
      "New York, NY 10179",
      "United States"
    ]
  },
  "intermediaryAgent": {
    "identification": "BCBKBMHM",
    "name": "Bermuda Commercial Bank",
    "additionalInformation": [
      "Victoria Place",
      "31 Victoria Street",
      "Hamilton HM 10, Bermuda"
    ]
  },
  "chargesType": "OUR",
  "remittanceInformation": [
    "Payment for investment management services Q1 2024",
    "Invoice #INV-2024-001",
    "Service Period: Jan-Mar 2024"
  ]
}'

{
  "id": "string",
  "status": "string",
  "transactionStatus": "string",
  "uniqueIdentifier": "string",
  "details": {
    "extReference": "string",
    "instructedAmount": {
      "currency": {},
      "amount": {}
    },
    "debtorAccount": {
      "schemeName": {},
      "identification": {},
      "Name": {}
    },
    "beneficiaryAccount": {
      "schemeName": {},
      "identification": {},
      "Name": {}
    },
    "creditorAccount": {
      "schemeName": {},
      "identification": {},
      "Name": {}
    },
    "settlementDetails": {
      "amountCredited": {},
      "amountDebited": {},
      "valueDate": {},
      "recordStatus": {}
    },
    "chargeDetails": {
      "chargesType": {},
      "chargeAmount": {},
      "chargeAccount": {},
      "chargeAnalysis": {}
    },
    "remittanceInformation": [
      {
        "unstructured": {}
      }
    ],
    "beneficiary": "string",
    "beneficiaryAgent": "string",
    "intermediaryAgent": "string"
  },
  "linkedActivities": [
    {
      "id": "string",
      "transactionStatus": "string",
      "status": "string",
      "uniqueIdentifier": "string",
      "activityDetails": {
        "arrangementId": {},
        "activityId": {},
        "productId": {},
        "currencyId": {},
        "effectiveDate": {}
      }
    }
  ]
}

List payment statuses for an account

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.bcbank.us/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.bcbank.us/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.bcbank.us/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.

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/accounts/{accountNumber}/payments' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "type": "string",
      "externalReference": "string",
      "status": "string",
      "remittanceInformation": "string",
      "transactionId": "string",
      "debitAmount": {
        "currency": {},
        "amount": {}
      },
      "valueDate": "string",
      "creditAmount": {
        "currency": {},
        "amount": {}
      },
      "exchangeRate": 0
    }
  ]
}

Get payment status

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.bcbank.us/v1/payments/{paymentId}/status

Sample Request in JavaScript:

async function getPaymentStatus(paymentId) {
  try {
    const response = await fetch(`https://api.bcbank.us/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.

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/payments/{paymentId}/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "type": "string",
  "externalReference": "string",
  "status": "string",
  "remittanceInformation": "string",
  "transactionId": "string",
  "debitAmount": {
    "currency": "string",
    "amount": "string"
  },
  "valueDate": "string",
  "creditAmount": {
    "currency": "string",
    "amount": "string"
  },
  "exchangeRate": 0
}

Create new API client credentials

Creates new API client credentials based on an existing client's permissions and configuration. The new credentials will inherit the same roles and permissions as the specified existing client.

Key Features:

• A new client ID (GUID) is generated automatically
• A cryptographically secure password (22-30 characters) is generated automatically
• A cryptographically secure message signing secret (32 bytes) is generated automatically for HMAC-SHA256 signing
• All roles and direct permissions are copied from the existing client
• The new credentials can have different IP restrictions if specified

Password Security:

• Generated passwords are 22-30 characters long for enhanced security
• Include uppercase letters, lowercase letters, digits, and special characters
• The generated password is only returned once in the response

Message Signing Secret:

• A 32-byte (256-bit) random key (Base64 encoded) is generated for signing API requests
• This key will be used by the system to sign callback responses - notifications, background job webhooks
• The secret is returned only once in the response

Access Control:

• You can only create credentials based on clients you have access to
• New client inherits exact role and permission set from source client
• IP restrictions can be customized or inherited from source client

Base URL:

All API requests use the versioned base URL:

https://api.bcbank.us/v1/credentials

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").

Sample Request in JavaScript:

async function createCredentials() {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch('https://api.bcbank.us/v1/credentials', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        allowedIps: '192.168.1.100,10.0.0.0/24' // Optional: specify IP restrictions, or omit/'*' for all IPs
      })
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('New credentials created:', {
      clientId: data.clientId,
      clientSecret: data.clientSecret, // Save this securely - only shown once!
      messageSigningSecret: data.messageSigningSecret, // Save this securely - only shown once!
      isActive: data.isActive,
      allowedIps: data.allowedIps
    });
    
    // Store new credentials securely
    // WARNING: This is just an example - use secure storage in production
    localStorage.setItem('newClientId', data.clientId);
    localStorage.setItem('newClientSecret', data.clientSecret);
    localStorage.setItem('newMessageSigningSecret', data.messageSigningSecret);
    
  } catch (error) {
    console.error('Error creating credentials:', error);
  }
}

createCredentials();

Required Permission: manage-credentials

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

Request body application/json

Responses

Credentials created successfully

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/credentials' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "allowedIps": "192.168.1.1,192.168.1.2"
}'

{
  "clientId": "a1b2c3d4-e5f6-4789-b012-3456789abcde",
  "clientSecret": "Abc123XyzP9mN7kLAbc123XyzP95",
  "isActive": true,
  "allowedIps": "192.168.1.1,192.168.1.2",
  "messageSigningSecret": "HtYp2oJm5DwQ1xL8bSeRgUkN4vZc3PhYtLwSxV2N9Cs="
}

Rotate the client secret for an existing API client

Rotates (changes) the client secret AND the message signing secret for an existing API client while preserving all other settings. This is useful for credential rotation policies, security incident response, or regular maintenance.

Key Features:

• A new cryptographically secure password (22-30 characters) is generated automatically
• A new cryptographically secure message signing secret (32 bytes) is generated automatically
• The existing client's secrets are immediately replaced with the new ones
• All roles, permissions, and other settings remain unchanged
• The old secrets become invalid immediately after successful rotation
• The new secrets are returned in the response (only shown once)

Password Security:

• Generated passwords are 22-30 characters long for enhanced security
• Include uppercase letters, lowercase letters, digits, and special characters
• The new password is only returned once in the response

Access Control:

• You can only rotate secrets for clients you have access to
• The rotated client retains all existing roles and permissions

Important Security Notes:

• The old secret stops working immediately after successful rotation
• Any applications using the old secret will need to be updated with the new secret
• Store the new secret securely as it won't be shown again

Base URL:

All API requests use the versioned base URL:

https://api.bcbank.us/v1/credentials/{clientId}

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").

Sample Request in JavaScript:

async function rotateClientSecret(clientId) {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}`, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('Client secret rotated successfully:', {
      clientId: data.clientId,
      newClientSecret: data.clientSecret, // Save this securely - only shown once!
      newMessageSigningSecret: data.messageSigningSecret, // Save this securely - only shown once!
      isActive: data.isActive,
      allowedIps: data.allowedIps
    });
    
    // Update stored credentials securely
    // WARNING: This is just an example - use secure storage in production
    localStorage.setItem('clientSecret', data.clientSecret);
    localStorage.setItem('messageSigningSecret', data.messageSigningSecret);
    
    // Important: Update any applications using the old secret
    console.warn('IMPORTANT: Update all applications using this client with the new secret!');
    
  } catch (error) {
    console.error('Error rotating client secret:', error);
  }
}

// Example usage
rotateClientSecret('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

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

Request parameters

Responses

Secret rotated successfully

curl --request PATCH \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "clientId": "string",
  "clientSecret": "string",
  "isActive": true,
  "allowedIps": "string",
  "messageSigningSecret": "string"
}

Disable an existing API client

Disables an existing API client, immediately preventing any further authentication using that client ID and secret. This operation also revokes all active tokens associated with the client.

Key Features:

• Disables the credentials instantly – all authentication requests will fail after this operation
• Revokes all active tokens immediately for enhanced security
• Idempotent: calling the endpoint on an already inactive client returns success

Security Considerations:

• All active tokens are immediately invalidated and removed from the system
• Any applications using the disabled client will lose access immediately
• The client record is preserved for audit and compliance purposes

Access Control:

• You can only disable clients that belong to your organization

Base URL:

All API requests use the versioned base URL:

https://api.bcbank.us/v1/credentials/{clientId}

Sample Request in JavaScript:

async function disableClient(clientId) {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}`, {
      method: 'DELETE',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('Client disabled successfully:', {
      clientId: data.clientId,
      isActive: data.isActive, // Should be false
      allowedIps: data.allowedIps
    });
    
    // Important: Update any applications that were using this client
    console.warn('IMPORTANT: All applications using this client will lose access immediately!');
    
  } catch (error) {
    console.error('Error disabling client:', error);
  }
}

// Example usage
disableClient('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

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

Request parameters

Responses

Client disabled successfully

curl --request DELETE \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "clientId": "a1b2c3d4-e5f6-7890-abcd-123456789def",
  "clientSecret": "",
  "isActive": false,
  "allowedIps": "192.168.1.100,10.0.0.0/24",
  "messageSigningSecret": null
}

Get permissions for an existing API client

Retrieves all permissions assigned to the specified API client. The response provides a comprehensive view of what features the client can access.

Key Features:

• Returns all permissions assigned to the client
• Results are sorted alphabetically by permission key for consistent ordering
• Includes human-readable descriptions for each permission

Access Control:

• You can only view permissions for clients that belong to your organization

Use Cases:

• Audit client access capabilities
• Troubleshoot authentication and authorization issues
• Verify client configuration during security reviews
• Document client permissions for compliance purposes

Base URL:

All API requests use the versioned base URL:

https://api.bcbank.us/v1/credentials/{clientId}/permissions

Sample Request in JavaScript:

async function getClientPermissions(clientId) {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/permissions`, {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const permissions = await response.json();
    console.log('Client permissions:', permissions);
    
    // Display permissions in a user-friendly format
    permissions.forEach(permission => {
      console.log(`- ${permission.key}: ${permission.description || 'No description available'}`);
    });
    
    return permissions;
    
  } catch (error) {
    console.error('Error retrieving client permissions:', error);
  }
}

// Example usage
getClientPermissions('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

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

Request parameters

Responses

Permissions retrieved successfully

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/permissions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

[
  {
    "key": "get-account",
    "description": "Allows access to retrieve individual account information"
  },
  {
    "key": "get-all-accounts",
    "description": "Allows access to retrieve all accounts for a customer"
  },
  {
    "key": "get-fx-quote",
    "description": "Allows access to foreign exchange quote endpoints"
  },
  {
    "key": "get-transactions",
    "description": "Allows access to transaction history endpoints"
  },
  {
    "key": "get-payment-status",
    "description": "Allows access to payment status tracking endpoints"
  },
  {
    "key": "make-internal-transfer",
    "description": "Allows execution of internal transfers between accounts"
  },
  {
    "key": "make-payment-swift",
    "description": "Allows execution of SWIFT payment transactions"
  },
  {
    "key": "manage-credentials",
    "description": "Allows management of API client credentials and permissions"
  }
]

Get public key metadata

Returns metadata for the partner RSA keys:

• Indicates whether primary/secondary keys exist
• Provides short fingerprints, algorithms, and last-updated timestamps
• Shows verification status of the secondary key (after proof-of-possession)

Sample Request in JavaScript:

async function getKeyMetadata(clientId) {
  try {
    const token = localStorage.getItem('jwt');
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/keys`, {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const metadata = await response.json();
    console.log('Key metadata:', {
      hasPrimaryKey: metadata.hasPrimaryKey,
      hasSecondaryKey: metadata.hasSecondaryKey,
      primaryKeyFingerprint: metadata.primaryKeyFingerprint,
      secondaryKeyFingerprint: metadata.secondaryKeyFingerprint,
      secondaryKeyVerified: metadata.secondaryKeyVerified
    });
    
    return metadata;
  } catch (error) {
    console.error('Error getting key metadata:', error);
  }
}

getKeyMetadata('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

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

Request parameters

Responses

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/keys' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "hasPrimaryKey": true,
  "hasSecondaryKey": true,
  "primaryKeyFingerprint": "A1B2C3D4E5F60708",
  "secondaryKeyFingerprint": "0F1E2D3C4B5A6978",
  "primaryKeyAlgorithm": "RSA-3072",
  "secondaryKeyAlgorithm": "RSA-3072",
  "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z",
  "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z",
  "secondaryKeyVerified": false,
  "secondaryKeyVerifiedUtc": null
}

Upload secondary public key

Upload a new RSA public key (PEM format) into the secondary slot to stage rotation.

Key Features:

• Accepts RSA public keys (2048-bit minimum recommended)
• Resets verification status when a new key is uploaded
• Secondary key becomes active for signature verification alongside primary

Rotation flow:

1. Upload secondary key (this endpoint)
2. POST challenge → sign locally → POST verify
3. POST promote (makes secondary the primary)
4. (Optional) DELETE secondary if aborting

Sample Request in JavaScript:

async function uploadSecondaryKey(clientId, publicKeyPem) {
  try {
    const token = localStorage.getItem('jwt');
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/keys/secondary`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        publicKeyPem: publicKeyPem
      })
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const metadata = await response.json();
    console.log('Secondary key uploaded:', {
      hasSecondaryKey: metadata.hasSecondaryKey,
      secondaryKeyFingerprint: metadata.secondaryKeyFingerprint,
      secondaryKeyVerified: metadata.secondaryKeyVerified // Will be false until verified
    });
    
    return metadata;
  } catch (error) {
    console.error('Error uploading secondary key:', error);
  }
}

Required Permission: manage-credentials

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

Request parameters

Request body application/json

Responses

curl --request PUT \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/keys/secondary' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAxq1RqYIgYOb7H1uxC5mS\nM8s2Dhrz6sGJYvRq9A0KIf8v0pqm+9B6ZcM+3PEm2rUp7N0CYaUtR32W0bz1gM/b\nd3BFPFdcTnMjYwXomfjAZW9XvsC8t7y7mNLgO2cMYk2fT7k6aQp0yrzmmkCudIsc\nq4drqgG/Kxi4SpwYgYYnZ2hEo6VtV5JpR6TfyxwTXXxoH1WPr5oH7D8fFvG3a7dD\nRZl/vM8UzA2yN6lcn/zoVPQ7xY9qaTYjz4cmOcuQKBgQCQKBgQCQKBgQCQKBgQ\n-----END PUBLIC KEY-----"
}'

{
  "hasPrimaryKey": true,
  "hasSecondaryKey": true,
  "primaryKeyFingerprint": "A1B2C3D4E5F60708",
  "secondaryKeyFingerprint": "0F1E2D3C4B5A6978",
  "primaryKeyAlgorithm": "RSA-3072",
  "secondaryKeyAlgorithm": "RSA-3072",
  "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z",
  "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z",
  "secondaryKeyVerified": false,
  "secondaryKeyVerifiedUtc": null
}

Delete secondary public key

Removes the secondary key from the staging slot. Useful for aborting rotation or correcting mistakes before promotion.

Key Features:

• Clears the secondary key slot
• Idempotent: returns success even if secondary key doesn't exist
• Safe for retries

Sample Request in JavaScript:

async function deleteSecondaryKey(clientId) {
  try {
    const token = localStorage.getItem('jwt');
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/keys/secondary`, {
      method: 'DELETE',
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const metadata = await response.json();
    console.log('Secondary key deleted:', {
      hasSecondaryKey: metadata.hasSecondaryKey // Now false
    });
    
    return metadata;
  } catch (error) {
    console.error('Error deleting secondary key:', error);
  }
}

Required Permission: manage-credentials

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

Request parameters

Responses

curl --request DELETE \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/keys/secondary' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "hasPrimaryKey": true,
  "hasSecondaryKey": true,
  "primaryKeyFingerprint": "A1B2C3D4E5F60708",
  "secondaryKeyFingerprint": "0F1E2D3C4B5A6978",
  "primaryKeyAlgorithm": "RSA-3072",
  "secondaryKeyAlgorithm": "RSA-3072",
  "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z",
  "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z",
  "secondaryKeyVerified": false,
  "secondaryKeyVerifiedUtc": null
}

Promote secondary key to primary

Promotes the current secondary key to primary and clears the secondary slot. Use after validating the new key (optionally after challenge/verify).

Key Features:

• Makes the secondary key the new primary
• Clears the secondary slot
• Previous primary key is replaced

Sample Request in JavaScript:

async function promoteSecondaryKey(clientId) {
  try {
    const token = localStorage.getItem('jwt');
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/keys/promote`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const metadata = await response.json();
    console.log('Secondary key promoted to primary:', {
      hasPrimaryKey: metadata.hasPrimaryKey,
      hasSecondaryKey: metadata.hasSecondaryKey, // Now false
      primaryKeyFingerprint: metadata.primaryKeyFingerprint // Updated
    });
    
    return metadata;
  } catch (error) {
    console.error('Error promoting secondary key:', error);
  }
}

Required Permission: manage-credentials

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

Request parameters

Responses

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/keys/promote' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "hasPrimaryKey": true,
  "hasSecondaryKey": true,
  "primaryKeyFingerprint": "A1B2C3D4E5F60708",
  "secondaryKeyFingerprint": "0F1E2D3C4B5A6978",
  "primaryKeyAlgorithm": "RSA-3072",
  "secondaryKeyAlgorithm": "RSA-3072",
  "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z",
  "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z",
  "secondaryKeyVerified": false,
  "secondaryKeyVerifiedUtc": null
}

Generate secondary key challenge

Returns a time-limited challenge (Base64) that must be signed with the private key corresponding to the secondary public key. Proves ownership before promotion.

Challenge Format:

• Base64 encoding of: {clientId}.{nonce}.{expiry}.{keyFingerprint}
• Sign the decoded raw bytes of this challenge (not the Base64 literal).
• Valid for ~5 minutes
• Bound to the current secondary key (fingerprint included)

Sample Request in JavaScript:

async function requestChallenge(clientId) {
  try {
    const token = localStorage.getItem('jwt');
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/keys/secondary/challenge`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const { challenge, expiresUtc } = await response.json();
    console.log('Challenge received:', { challenge, expiresUtc });
    
    // Sign the challenge with your private key
    const crypto = require('crypto');
    const privateKeyPem = process.env.PRIVATE_KEY;
    
    const sign = crypto.createSign('RSA-SHA256');
    sign.update(Buffer.from(challenge, 'base64'));
    const signature = sign.sign({
      key: privateKeyPem,
      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
      saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST
    }, 'base64');
    
    console.log('Signature created, ready for verification');
    return { challenge, signature };
    
  } catch (error) {
    console.error('Error requesting challenge:', error);
  }
}

Required Permission: manage-credentials

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

Request parameters

Responses

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/keys/secondary/challenge' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "challenge": "Y2xpZW50SWQubm9uY2UuMTcwMDAwMDAwMC5BMTIzRjQ1RjY3OA==",
  "expiresUtc": "2026-01-15T12:05:00.0000000Z"
}

Verify secondary key ownership

Submit the Base64 challenge and its RSA-PSS signature (SHA-256). Important: sign the decoded raw bytes of the challenge, not the Base64 string literal. On success, the secondary key is marked as verified.

Key Features:

• Validates signature using RSA-PSS + SHA-256
• Checks challenge expiry (5-minute window)
• Verifies challenge matches current secondary key
• Sets secondaryKeyVerified: true on success

Sample Request in JavaScript:

async function verifySecondaryKey(clientId, challenge, signature) {
  try {
    const token = localStorage.getItem('jwt');
    
    const response = await fetch(`https://api.bcbank.us/v1/credentials/${clientId}/keys/secondary/verify`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        challenge: challenge,
        signature: signature
      })
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const metadata = await response.json();
    
    if (metadata.secondaryKeyVerified) {
      console.log('✓ Secondary key verified successfully!');
      console.log('You can now promote it to primary or test with production traffic.');
    } else {
      console.error('✗ Verification failed - signature did not match');
    }
    
    return metadata;
  } catch (error) {
    console.error('Error verifying secondary key:', error);
  }
}

// Complete rotation flow example:
// 1. Upload:  await uploadSecondaryKey(clientId, publicKeyPem);
// 2. Challenge: const { challenge, signature } = await requestChallenge(clientId);
// 3. Verify: await verifySecondaryKey(clientId, challenge, signature);
// 4. Promote: await promoteSecondaryKey(clientId);

Required Permission: manage-credentials

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

Request parameters

Request body application/json

Responses

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/credentials/{clientId}/keys/secondary/verify' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "challenge": "Y2xpZW50SWQubm9uY2UuMTcwMDAwMDAwMC5BMTIzRjQ1RjY3OA==",
  "signature": "MEUCIQC0j7Xf7PqJ8n+q2eVY7k1nqM+UogYNDpFQ2a3E7Xy1zwIgFqYY3d3rVfJq8zlfjtqZ5rXwzBkVxH93+zVTe6y8ygE="
}'

{
  "hasPrimaryKey": true,
  "hasSecondaryKey": true,
  "primaryKeyFingerprint": "A1B2C3D4E5F60708",
  "secondaryKeyFingerprint": "0F1E2D3C4B5A6978",
  "primaryKeyAlgorithm": "RSA-3072",
  "secondaryKeyAlgorithm": "RSA-3072",
  "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z",
  "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z",
  "secondaryKeyVerified": false,
  "secondaryKeyVerifiedUtc": null
}

Create a test SWIFT deposit

Creates a SWIFT deposit in the system using test-environment data and returns the created deposit details. This endpoint is available only in non-production environments and is intended for integration testing, validation of payload formatting, and pre-production workflow checks.

Although the route contains the word simulate, the request creates a deposit record in the system. If there is a matching and active deposit notification subscription, the created deposit may also trigger a deposit notification workflow.

Content Negotiation

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

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

Headers

• Authorization: Bearer {token}
• Idempotency-Key: {uuid} (optional, but recommended for safe retries)

Validation Rules / Constraints

• creditAccountNumber is required and must not exceed 36 characters.
• instructedAmount.currency is required and must be a 3-letter ISO currency code.
• instructedAmount.amount is required and must be a valid decimal number with up to 2 decimal places.
• externalAccountNumber is required and must not exceed 34 characters.
• orderingBank is required and must not exceed 35 characters.
• orderingCustomer must contain between 1 and 4 lines, each up to 35 characters.
• remittanceInformation must contain at least 1 line, up to 4 lines total, each up to 35 characters.

Request / Response Signing

This endpoint uses request signature verification and response signing. Clients should sign requests according to their configured signing method, and should verify the signature on the response when response signing is enabled for their API credentials.

Base URL

All API requests use the versioned base URL:

https://api.bcbank.us/v1/test-deposits/swift/simulate
        

Sample Request in JavaScript

async function simulateDeposit(token, idempotencyKey) {
  const response = await fetch('https://api.bcbank.us/v1/test-deposits/swift/simulate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      creditAccountNumber: '1000078766',
      instructedAmount: {
        currency: 'USD',
        amount: '5000.00'
      },
      externalAccountNumber: 'GB29NWBK60161331926819',
      orderingBank: 'DEUTDEFF',
      orderingCustomer: [
        'Global Trading Corp',
        '100 Finance Street',
        'London, EC2V 8AB'
      ],
      remittanceInformation: [
        'Invoice INV-2024-0042',
        'Q1 advisory fees'
      ]
    })
  });
            
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Deposit simulation failed');
  }
            
  return await response.json();
}

Required Permission: simulate-deposit

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

Request body application/json

Responses

OK - The test deposit was created successfully.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/test-deposits/swift/simulate' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "creditAccountNumber": 1000078766,
  "instructedAmount": {
    "currency": "USD",
    "amount": 5000
  },
  "externalAccountNumber": "GB29NWBK60161331926819",
  "orderingBank": "DEUTDEFF",
  "orderingCustomer": [
    "Global Trading Corp",
    "100 Finance Street",
    "London, EC2V 8AB"
  ],
  "remittanceInformation": [
    "Invoice INV-2024-0042",
    "Q1 advisory fees"
  ]
}'

{
  "id": "DEP-SIM-20240321-001",
  "status": "success",
  "transactionStatus": "SIMULATED",
  "uniqueIdentifier": "dep-sim-uid-001",
  "details": {
    "amountCredited": {
      "currency": "USD",
      "amount": 5000
    },
    "amountDebited": {
      "currency": "USD",
      "amount": 5000
    },
    "orderingBank": "DEUTDEFF",
    "debitCurrency": "USD",
    "creditAccountNumber": 1000078766,
    "instructedAmount": {
      "currency": "USD",
      "amount": 5000
    },
    "externalAccountNumber": "GB29NWBK60161331926819",
    "orderingCustomer": [
      {
        "unstructured": "Global Trading Corp"
      },
      {
        "unstructured": "100 Finance Street"
      },
      {
        "unstructured": "London, EC2V 8AB"
      }
    ],
    "remittanceInformation": [
      {
        "unstructured": "Invoice INV-2024-0042"
      },
      {
        "unstructured": "Q1 advisory fees"
      }
    ]
  },
  "linkedActivities": [
    {
      "id": "ACT-DEP-SIM-001",
      "transactionStatus": "SIMULATED",
      "status": "SUCCESS",
      "uniqueIdentifier": "act-dep-sim-001",
      "activityDetails": {
        "arrangementId": "arr-123456",
        "activityId": "act-123456",
        "productId": "swift-deposit-simulation",
        "currencyId": "USD",
        "effectiveDate": "2024-03-21"
      }
    }
  ]
}

Get FX Quote

Retrieves a foreign exchange quote for converting between currencies (for the requested pair and amount). The same quote will be automatically applied by the system to any internal transfer or payment involving two different currencies, provided it is used within its expiry time.

High-Value Exchange Requests (> 100 000 BMD)

If the requested exchange amount exceeds 100 000 BMD, the system will not return an automatic quote in the GET /v1/fx-quotes response.
Instead, the request is routed for manual processing by our treasury desk to secure the most competitive rate available.

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.bcbank.us/v1/fx-quotes

Validation Rules

• Currencies must be valid three-letter ISO 4217 codes
• Unit currency and currency of transfer must be different
• Instructed amount must be a valid decimal number with up to 2 decimal places

Sample Request in JavaScript:

// Get FX quote for converting 100 USD to EUR
const getFxQuote = async (unitCurrency, currencyOfTransfer, instructedAmount) => {
  try {
    const response = await fetch(
      'https://api.bcbank.us/v1/fx-quotes?' + 
      new URLSearchParams({
        unitCurrency: unitCurrency,
        currencyOfTransfer: currencyOfTransfer,
        instructedAmount: instructedAmount
      }), {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
    });

    // Check if the response is ok (status in the range 200-299)
    if (!response.ok) {
      // Parse error response
      const errorData = await response.json();
      throw new Error(`Error ${response.status}: ${errorData.error} - ${errorData.message}`);
    }

    // Parse successful response
    const quote = await response.json();
    
    // Log the complete quote details
    console.log('FX Quote Details:');
    console.log(`Source Currency: ${quote.sourceCurrency.currency}`);
    console.log(`Source Amount: ${quote.sourceCurrency.amount}`);
    console.log(`Target Currency: ${quote.targetCurrency.currency}`);
    console.log(`Target Amount: ${quote.targetCurrency.amount}`);
    console.log(`Exchange Rate: ${quote.exchangeRate}`);
    console.log(`Quote Expires: ${new Date(quote.expiryDateTime).toLocaleString()}`);

    // Return the processed quote
    return {
      ...quote,
      // Add formatted values for display
      formattedSourceAmount: new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: quote.sourceCurrency.currency
      }).format(quote.sourceCurrency.amount),
      formattedTargetAmount: new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: quote.targetCurrency.currency
      }).format(quote.targetCurrency.amount)
    };
  } catch (error) {
    // Handle different types of errors
    if (error.name === 'TypeError') {
      console.error('Network error:', error.message);
    } else {
      console.error('API error:', error.message);
    }
    throw error; // Re-throw to let caller handle it
  }
};
            
// Example usage with error handling:
try {
  const quote = await getFxQuote('USD', 'EUR', '100.00');
  console.log('Formatted Quote:', quote.formattedSourceAmount, '→', quote.formattedTargetAmount);
} catch (error) {
  console.error('Failed to get FX quote:', error.message);
}

Required Permission: get-fx-quote

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

Request parameters

Responses

OK - The request was successful. Returns the FX quote details

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/fx-quotes' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "sourceCurrency": {
    "currency": "string",
    "amount": "string"
  },
  "targetCurrency": {
    "currency": "string",
    "amount": "string"
  },
  "expiryDateTime": "string",
  "exchangeRate": 0
}

Internal Transfer

Initiates an internal funds transfer between two accounts within the institution. The request must include source and destination account details, along with the amount and currency to be transferred. Optionally, clients may provide a transaction reference and remittance information describing the purpose of the payment.

• debitAccountNumber: The account number from which funds will be debited.
• debitAmountCurrency: The currency code for the debit amount. Must match the credit account currency.
• creditAccountNumber: The account number to be credited.
• creditAmountCurrency: The currency code for the credit amount. Must match the debit account currency.
• debitAmount: The amount to be transferred.
• endToEndIdentification: (Optional) A unique reference provided by the client to identify the transaction end-to-end.
• remittanceInformation: (Optional) Free-text remittance information describing the purpose of the transaction.

Important Notes:

• Transfers between accounts with different currencies are not allowed. The debit and credit account currencies must match.
• Ensure all inputs are validated and the source account has sufficient funds before making the request.

High-Value Exchange Requests (> 100 000 BMD)

If the requested exchange amount exceeds 100 000 BMD, the POST /v1/transfers/internal endpoint will not return an immediate confirmation. Instead, the request is routed for manual processing by our treasury desk to secure the most competitive rate available.

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.bcbank.us/v1/internal-transfers
        

Sample Request in JavaScript:

async function executeInternalTransfer() {
  try {
    const response = await fetch('https://api.bcbank.us/v1/internal-transfers', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional: UUID format required if provided
      },
      body: JSON.stringify({
        debitAccountNumber: "12345678901234567890123456",
        debitAmountCurrency: "USD",
        creditAccountNumber: "98765432109876543210987654",
        creditAmountCurrency: "USD", // Must match debitAmountCurrency
        debitAmount: "100.00",
        endToEndIdentification: "REF-INV-20250417-001", // Optional external transaction reference
        remittanceInformationUnstructured: "Payment for invoice #12345" // Optional payment description
      })
    });
            
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Transfer failed: ${JSON.stringify(errorData)}`);
    }
            
    const data = await response.json();
    console.log('Transfer result:', data);
            
    // Example processing of the returned object
    const { id, status, uniqueIdentifier, internalTransferDetails, linkedActivities } = data;
    const { amountCredited, creditAmountCurrency, debitAmount, amountDebited, chargeAmount, valueDate, chargeAnalysisReceiver, chargeAnalysisSender, debitAccountNumber, creditAccountNumber, chargeAccountNumber } = internalTransferDetails;

    // Log the main transfer details.
    console.log('Transaction ID:', id);
    console.log('Status:', status);
    console.log('Unique Identifier:', uniqueIdentifier);
    console.log('Amount Credited:', amountCredited.amount, amountCredited.currency);
    console.log('Credit Amount Currency:', creditAmountCurrency);
    console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);
    console.log('Amount Debited:', amountDebited.amount, amountDebited.currency);
    console.log('Charge Amount:', chargeAmount.amount, chargeAmount.currency);
    console.log('Value Date:', valueDate);
    console.log('Charge Analysis Receiver:', chargeAnalysisReceiver);
    console.log('Charge Analysis Sender:', chargeAnalysisSender);
            
    // Process debit account information.
    console.log('Debit Account Number:', debitAccountNumber.number);
    if (debitAccountNumber.accountRoutings) {
      debitAccountNumber.accountRoutings.forEach(routing => {
        console.log('Debit Account Routing Scheme:', routing.scheme);
        console.log('Debit Account Routing Address:', routing.address);
      });
    }
            
    // Process credit account information.
    console.log('Credit Account Number:', creditAccountNumber.number);
    if (creditAccountNumber.accountRoutings) {
      creditAccountNumber.accountRoutings.forEach(routing => {
        console.log('Credit Account Routing Scheme:', routing.scheme);
        console.log('Credit Account Routing Address:', routing.address);
      });
    }
            
    // Process charge account information.
    console.log('Charge Account Number:', chargeAccountNumber.number);
    if (chargeAccountNumber.accountRoutings) {
      chargeAccountNumber.accountRoutings.forEach(routing => {
        console.log('Charge Account Routing Scheme:', routing.scheme);
        console.log('Charge Account Routing Address:', routing.address);
      });
    }
            
    // 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 transfer was successful.');
    } else {
      console.log('The transfer failed:', status);
    }
  } catch (error) {
    console.error('Error executing internal transfer:', error);
  }
}
            
executeInternalTransfer();

Required Permission: internal-transfer

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

Request body application/json

Responses

The transfer was created successfully.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/internal-transfers' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "endToEndIdentification": "REF-INV-20250417-001",
  "remittanceInformation": "Payment for invoice #12345",
  "debitAccountNumber": 987654321098765,
  "debitAmountCurrency": "USD",
  "creditAccountNumber": 123456789012345,
  "creditAmountCurrency": "USD",
  "debitAmount": 100
}'

{
  "id": "string",
  "status": "string",
  "uniqueIdentifier": "string",
  "internalTransferDetails": {
    "amountCredited": {
      "currency": {},
      "amount": {}
    },
    "creditAmountCurrency": "string",
    "debitAmount": {
      "currency": {},
      "amount": {}
    },
    "amountDebited": {
      "currency": {},
      "amount": {}
    },
    "chargeAmount": {
      "currency": {},
      "amount": {}
    },
    "valueDate": "string",
    "chargeAnalysisReceiver": "string",
    "chargeAnalysisSender": "string",
    "debitAccountNumber": {
      "number": {},
      "accountRoutings": {}
    },
    "creditAccountNumber": {
      "number": {},
      "accountRoutings": {}
    },
    "chargeAccountNumber": {
      "number": {},
      "accountRoutings": {}
    }
  },
  "linkedActivities": [
    {
      "id": "string",
      "transactionStatus": "string",
      "status": "string",
      "uniqueIdentifier": "string",
      "activityDetails": {
        "arrangementId": {},
        "activityId": {},
        "productId": {},
        "currencyId": {},
        "effectiveDate": {}
      }
    }
  ]
}

List Investment Orders

Retrieves the customer's orders, newest first with a deterministic tie-break.

Filtering

Optional portfolioCode is exact and case-sensitive (maximum 50 characters). Optional clientReference is exact after trimming (maximum 100 characters before trimming). Optional status selects the current public status, including PendingCancellation. Failed can include a partially executed order whose remaining quantity was cancelled while its fills await settlement. Executed quantity and average price remain in the response; the order can later become Completed. fromDate and toDate are independent inclusive UTC bounds on createdAt. When both are supplied, fromDate must not exceed toDate and the span must not exceed one calendar year. An unknown or non-owned portfolio returns an empty list; an unknown customer returns 404.

Pagination

This endpoint uses numeric pagination.

• First page: Omit pageStart or pass 1. It is a 1-based page number; 0 is invalid.
• Page size: pageSize defaults to 100; the allowed range is 1–1000.
• Next page: Increase pageStart by 1 and send the same pageSize and filters.
• Page token: Do not send pageToken; it is unsupported. meta.pagination.page_token is empty.
• Response: meta.pagination.page_start is the current page number, meta.pagination.page_size is the page size, and meta.pagination.total_size is the total number of matching orders, including orders omitted because they cannot be represented in the response.
• Last page: Using the response metadata, stop when page_start * page_size >= total_size. A short or empty page does not necessarily mean the end because some orders may be omitted from the response.
• Beyond the last page: Returns 200 OK with an empty data array.
• Ordering: Newest creation time first, then highest OMS order ID for orders with the same creation time. Pages are read separately; concurrent changes can shift results between pages.

Content Negotiation

Use Accept: application/json (default) or Accept: text/csv.

Base URL

GET https://api.bcbank.us/v1/investments/orders

Sample Request in JavaScript

const response = await fetch('https://api.bcbank.us/v1/investments/orders?pageStart=1&pageSize=25', {
  headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Accept': 'application/json' }
});
const orders = await response.json();

Required Permission: read-investments

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

Request parameters

Responses

OK - The order page was retrieved.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/investments/orders' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "orderReference": "string",
      "clientReference": "string",
      "portfolioCode": "string",
      "accountNumber": "string",
      "security": {
        "isin": "string",
        "symbol": "string",
        "name": "string"
      },
      "side": "Buy",
      "orderType": "Market",
      "quantity": 0,
      "limitPrice": 0,
      "timeInForce": "Day",
      "status": "Accepted",
      "filledQuantity": 0,
      "averagePrice": 0,
      "createdAt": "string",
      "updatedAt": "string",
      "rejectionReason": {
        "code": "RejectedByApprover",
        "message": {}
      }
    }
  ]
}

Place Investment Order

Submits a buy or sell order for a security identified by ISIN, using the authenticated customer's portfolio and account. Send a JSON request to POST /v1/investments/orders.

Order Instructions

• portfolioCode and accountNumber are required and must not exceed 50 characters each. They must identify an active portfolio and account belonging to the customer; the account must belong to the portfolio.
• security.isin is required and must be a valid 12-character ISIN. The security must be tradable.
• Supply side explicitly as Buy or Sell, and orderType as Market or Limit.
• quantity must be positive and satisfy the security's trading rules.
• For a Limit order, limitPrice is required and must be positive. For a Market order, omit it or send null.
• Supply timeInForce explicitly as Day, GoodTillCancelled, ImmediateOrCancel, or FillOrKill.

Client Reference

clientReference is an optional client-supplied reference for tracking and reconciliation.

• It may be omitted or null. Empty or whitespace-only values are stored as null.
• The supplied value must not exceed 100 characters, including surrounding whitespace; longer values return 400 Bad Request.
• Surrounding whitespace is trimmed. Casing and internal characters are preserved.
• It is fixed at creation and returned in the acceptance and order-detail responses when present.
• Duplicates are allowed. Reusing a client reference does not prevent another order from being created.

Acceptance and Tracking

202 Accepted means the order was persisted and the required funds or securities were reserved. Acceptance does not guarantee execution; approval or further processing may still be required. The JSON response contains the server-generated UUID orderReference, the stored clientReference when present, the current status, and createdAt. Follow the Location response header to retrieve the order and poll its current status. orderReference identifies one order; clientReference is customer-provided correlation metadata.

Idempotency

The Idempotency-Key header is optional. Use a nonblank key of at most 256 characters to enable replay. While a successful response remains cached, reusing the key on this endpoint in the same caller scope returns that response and its Location header. Replay is keyed by the header, not by the request body or clientReference; use a new key for every new order, including orders with identical instructions. If the same keyed request is still being processed, the endpoint may return 409 Conflict. A timeout does not establish whether the order was created. clientReference alone does not make a retry idempotent.

Required Permission: create-investments

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

Request parameters

Request body application/json

Responses

Accepted - The order was accepted for processing; the response includes its references, status, and creation time.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/investments/orders' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientReference": "string",
  "portfolioCode": "string",
  "accountNumber": "string",
  "security": {
    "isin": "string"
  },
  "side": "Buy",
  "orderType": "Market",
  "quantity": 0,
  "limitPrice": 0,
  "timeInForce": "Day"
}'

{
  "orderReference": "0198f0a3-7c4e-7d21-9c30-6f0b1d2e3a44",
  "clientReference": "Mobile-AbC-001",
  "status": "Accepted",
  "createdAt": "2026-09-01T12:30:00.0000000+02:00"
}

Cancel Investment Order

Requests cancellation of an Accepted, PendingApproval, Working, or PartiallyFilled order. Partial fills remain part of the order. The request has no body.

Response and Polling

202 Accepted returns the current order and a Location pointing to its GET route. Acceptance does not guarantee cancellation. Poll Location while the status is PendingCancellation. It can resolve to Cancelled, another terminal state, or a working state after cancellation rejection. A racing execution can make the 202 response already terminal. Persistent uncertainty requires support. Repeating while pending returns current state without another cancellation attempt. Already-cancelled orders return 202; other terminal states at the initial check return 409 ORDER_NOT_CANCELLABLE. A rejected request returns 400 ORDER_CANCEL_REJECTED; temporarily unavailable cancellation returns 503.

Cancellation after a partial fill

Cancelling the remainder does not undo executed fills. For example, if 3 of 10 shares execute at 100 and the remaining 7 are cancelled, the response retains filledQuantity: 3 and averagePrice: 100. The order can report Failed while those fills await settlement, then Completed after settlement. Failed does not necessarily mean that nothing executed, and a successful cancellation does not always produce Cancelled.

Idempotency

The optional Idempotency-Key is a nonblank key of at most 256 characters. Reusing it replays the original response and Location; use GET to retrieve the latest state. An identical request still in progress can return 409.

Base URL

POST https://api.bcbank.us/v1/investments/orders/{orderReference}/cancel

Sample Request in JavaScript

const response = await fetch(`https://api.bcbank.us/v1/investments/orders/${orderReference}/cancel`, {
  method: 'POST', headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Idempotency-Key': crypto.randomUUID() }
});

Required Permission: create-investments

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

Request parameters

Responses

Accepted - The cancellation request was accepted.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/investments/orders/{orderReference}/cancel' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "orderReference": "string",
  "clientReference": "string",
  "portfolioCode": "string",
  "accountNumber": "string",
  "security": {
    "isin": "string",
    "symbol": "string",
    "name": "string"
  },
  "side": "Buy",
  "orderType": "Market",
  "quantity": 0,
  "limitPrice": 0,
  "timeInForce": "Day",
  "status": "Accepted",
  "filledQuantity": 0,
  "averagePrice": 0,
  "createdAt": "string",
  "updatedAt": "string",
  "rejectionReason": {
    "code": "RejectedByApprover",
    "message": "string"
  }
}

List Investment Positions

Retrieves a paginated list of investment positions associated with the authenticated customer. Each item represents one security position in one portfolio.

Filtering

• portfolioCode is optional, case-insensitive, and must not exceed 50 characters.
• If portfolioCode is omitted, the endpoint returns positions from all associated portfolios.
• If the customer exists but no positions match, the endpoint returns 200 OK with an empty data array.
• If the investment customer does not exist, the endpoint returns 404 Not Found.

Pagination

This endpoint uses numeric pagination.

• First page: Omit pageStart or pass 1. It is a 1-based page number; 0 is invalid.
• Page size: pageSize defaults to 100; the allowed range is 1–1000.
• Next page: Increase pageStart by 1 and send the same pageSize and filters.
• Page token: This endpoint does not use pageToken. meta.pagination.page_token is empty.
• Response: meta.pagination.page_start is the current page number, meta.pagination.page_size is the page size, and meta.pagination.total_size is the total number of matching positions.
• Last page: Using the response metadata, stop when page_start * page_size >= total_size.
• Beyond the last page: Returns 200 OK with an empty data array.
• Ordering: Portfolio code, then security ISIN, then symbol. Pages are read separately; concurrent changes can shift results between pages.

Content Negotiation

Clients must use the HTTP Accept header to select the 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.bcbank.us/v1/investments/positions
        

Sample Request in JavaScript

const url = new URL('https://api.bcbank.us/v1/investments/positions');
url.searchParams.set('portfolioCode', 'PTF-001');
url.searchParams.set('pageStart', '1');
url.searchParams.set('pageSize', '25');
            
const response = await fetch(url, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Accept': 'application/json'
  }
});
            
if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}
            
const positions = await response.json();

Required Permission: read-investments

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

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/investments/positions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "portfolio": {
        "code": {},
        "name": {}
      },
      "security": {
        "isin": {},
        "symbol": {},
        "name": {},
        "assetClass": "Shares",
        "exchange": {},
        "priceConvention": "PerUnit"
      },
      "quantity": 0,
      "availableQuantity": 0,
      "unsettledBuyQuantity": 0,
      "unsettledSellQuantity": 0,
      "blockedQuantity": 0,
      "costBasis": 0,
      "averageCost": 0,
      "marketPrice": 0,
      "marketValue": 0,
      "priceChange": 0,
      "priceChangePercentage": 0,
      "unrealizedProfitLoss": 0,
      "unrealizedProfitLossPercentage": 0,
      "currency": "string",
      "priceAsOf": "string"
    }
  ]
}

List Investment Trades

Retrieves a paginated list of settled investment trades associated with the authenticated customer. Each item represents one completed purchase or sale.

Trade reference and dates

• transactionReference is the reference assigned to the trade.
• tradeDate is the execution date and settlementDate is the settlement date. Both use YYYY-MM-DD format without a time component.
• transactionDate is the recorded transaction date and time in UTC, for example 2026-08-24T10:30:00+00:00. Fractional seconds are preserved when present.
• Unavailable dates are null in JSON and omitted from CSV. transactionDate is not inferred from createdAt when unavailable.

Filtering

• portfolioCode is required, case-insensitive, and must not exceed 50 characters.
• If the portfolio does not exist, is not associated with the customer, or has no trades, the endpoint returns 200 OK with an empty data array.
• If the investment customer does not exist, the endpoint returns 404 Not Found.

Pagination

This endpoint uses cursor pagination.

• First page: Omit pageStart or pass 1. It is a 1-based page number; 0 is invalid. Omit pageToken on the first request.
• Page size: pageSize defaults to 100; the allowed range is 1–1000. Set it on the first request.
• Next page: Increase pageStart by 1, send the returned meta.pagination.page_token as pageToken unchanged, keep the same filters, and omit pageSize; the token carries the page size.
• Page token: pageToken must not exceed 100 characters.
• Response: meta.pagination.page_start is the current page number, meta.pagination.page_size is the page size, and meta.pagination.total_size is the total number of trades in the portfolio.
• Last page: Using the response metadata, stop when page_start * page_size >= total_size.

Content Negotiation

Clients must use the HTTP Accept header to select the 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.bcbank.us/v1/investments/trades
        

Sample Request in JavaScript

const url = new URL('https://api.bcbank.us/v1/investments/trades');
url.searchParams.set('portfolioCode', '2000592-1');
url.searchParams.set('pageStart', '1');
url.searchParams.set('pageSize', '25');
            
const response = await fetch(url, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Accept': 'application/json'
  }
});
            
if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}
            
const trades = await response.json();

Required Permission: read-investments

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

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/investments/trades' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "transactionReference": "string",
      "portfolio": {
        "code": {},
        "name": {}
      },
      "account": {
        "number": {},
        "name": {}
      },
      "security": {
        "isin": {},
        "symbol": {},
        "name": {},
        "assetClass": "Shares",
        "exchange": {},
        "priceConvention": "PerUnit"
      },
      "side": "Buy",
      "quantity": 0,
      "price": 0,
      "total": 0,
      "currency": "string",
      "commission": 0,
      "handlingFee": 0,
      "status": "Settled",
      "createdAt": "string",
      "tradeDate": "string",
      "settlementDate": "string",
      "transactionDate": "string"
    }
  ]
}

Get Investment Order

Retrieves one order owned by the authenticated customer using GET /v1/investments/orders/{orderReference}. Use the UUID returned by placement or follow the Location header from the acceptance response.

References and Response

The response includes the order instructions, security, aggregate fill quantity and average price, current status, and creation and update times. clientReference contains the normalized reference supplied at creation, when present; orders created without one have no client reference. This route accepts the server-generated orderReference UUID. Use the list-orders endpoint to filter by clientReference.

Status Values

• Accepted: accepted for processing; execution has not yet been acknowledged.
• PendingApproval: awaiting approval before further processing.
• Working: acknowledged for execution, with no fills reported yet.
• PartiallyFilled: part of the requested quantity has been executed.
• PendingCancellation: a cancellation request is unresolved; cancellation is not guaranteed.
• Filled: the requested quantity has been executed; final processing may still be pending.
• Completed: execution and final processing have completed.
• Cancelled: the remaining order has been cancelled; any reported fills remain part of the order.
• Rejected: the order was rejected. rejectionReason provides a public code and message.
• Failed: the order's state cannot be represented by another public status. This includes a partially executed order whose remainder was cancelled while its fills await settlement.

Cancelling the remainder does not undo fills. For example, 3 of 10 shares execute at 100 and the remaining 7 are cancelled: filledQuantity remains 3 and averagePrice remains 100. The order can report Failed while those fills await settlement, then Completed after settlement.

A successful GET returns 200 OK even when the order status is Rejected or Failed. Unknown references and orders outside the customer's scope return 404 Not Found.

Required Permission: read-investments

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

Request parameters

Responses

OK - The order details were retrieved.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/investments/orders/{orderReference}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "orderReference": "string",
  "clientReference": "string",
  "portfolioCode": "string",
  "accountNumber": "string",
  "security": {
    "isin": "string",
    "symbol": "string",
    "name": "string"
  },
  "side": "Buy",
  "orderType": "Market",
  "quantity": 0,
  "limitPrice": 0,
  "timeInForce": "Day",
  "status": "Accepted",
  "filledQuantity": 0,
  "averagePrice": 0,
  "createdAt": "string",
  "updatedAt": "string",
  "rejectionReason": {
    "code": "RejectedByApprover",
    "message": "string"
  }
}

Gets the bank's current signing public key.

Gets the bank’s current signing public key in JWKS format. Returns a JWKS containing one RSA key with fields:

• kid: rsa-{keyVersion}
• kty: RSA
• alg: PS256
• use: sig
• n/e: base64url-encoded modulus and exponent This endpoint requires OpenBankApi authorization; no private key material is exposed.

Responses

JWKS payload with the active signing key.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/.well-known/jwks.json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "PS256",
      "kid": "rsa-v1",
      "n": "u8Jx7zV9KkWlZqS5qZ1e8E6-hwFkZl0ob8BZqC5JxW0SP-L9c7szw1Zcrw1xwqXkDFFG8sUiDqJcVQnI-AVS4fRNn2drXr6IJuE5i2jxEwHkJq9e-3KifxHbK7WfG5A0yXspwxvzI8vEOwUlTta_yYB5kAEV1kZkH6yN2V_2Q7vJz0ZfM_kqfC1M3G2aCQ6U7gCgN_Qmfrj7q6kP2zR9a7vSg9QZyYxBrS_ImV1LhNWDKqHeX5vKQ1CW6m6Qd4y9P7Q",
      "e": "AQAB"
    }
  ]
}

Generate Token

Generates a JWT access token based on provided client credentials. Use this POST endpoint to authenticate using your clientId and clientSecret and receive a JWT token.

Token Validity: 40 minutes from the time of issuance.

Endpoint: https://api.bcbank.us/auth/token

Required Headers:

• Content-Type: application/json
• Accept: application/json

Sample Request in JavaScript:

async function getToken() {
  try {
    const response = await fetch('https://api.bcbank.us/auth/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        clientId: 'your-client-id',
        clientSecret: 'your-client-secret'
      })
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('JWT Token:', data.token);
    // Store token securely
    localStorage.setItem('jwt', data.token);
  } catch (error) {
    console.error('Fetch error:', error);
  }
}

getToken();

Request body application/json

Responses

Token generated successfully.

curl --request POST \
  --url 'https://api-uat.bcbank.us/auth/token' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientId": "your-client-id-here",
  "clientSecret": "your-client-secret-here"
}'

{
  "token": "string",
  "expiration": "string"
}

Account Transactions

Retrieves transaction details for the specified account and date range. This endpoint:

• Validates the provided date parameters. The accepted date formats are yyyy-MM-dd or yyyyMMdd.
• Maximum date range is one year.
• Supports both JSON and CSV response formats based on the Accept header.
• Supports cursor-based pagination for efficient handling of large transaction datasets.

Transaction ID Uniqueness

Important: Transaction IDs are globally unique across the entire banking system. For internal transfers, the same transaction ID appears on both accounts (debit and credit entries) with only the transaction type differing. When fees apply, multiple entries may share the same transaction ID.

📖 For detailed information about transaction ID behavior, see: https://developers.bcbank.us/guides/transaction-id-uniqueness-guide

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.bcbank.us/v1/accounts/{accountNumber}/transactions

Sample Request in JavaScript

async function getAllTransactionsPaginated(accountNumber, fromDate, toDate) {
  try {
    let allTransactions = [];
    let pageStart = 1;
    let pageToken = null;
    let totalPages = 0;

    do {
      // Build URL with pagination parameters
      let url = `https://api.bcbank.us/v1/accounts/${accountNumber}/transactions`;
      const params = new URLSearchParams();
      
      // Always include date range
      params.append('fromDate', fromDate);
      params.append('toDate', toDate);
      
      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());
      }
      
      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 transactions from this page
      if (data.data && data.data.length > 0) {
        allTransactions.push(...data.data);
        console.log(`Collected ${data.data.length} transactions from page ${pageStart}`);
      }

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

    console.log(`Total transactions collected: ${allTransactions.length}`);

    // Process all collected transactions
    allTransactions.forEach((transaction, index) => {
      console.log(`Transaction ${index + 1}:`, transaction.id);
      console.log('Account Number:', transaction.thisAccount.number);
      console.log('Other Account Number:', transaction.otherAccount.number);
      console.log('Type:', transaction.details.type);
      console.log('Description:', transaction.details.description);
      console.log('Posted Date:', transaction.details.posted);
      console.log('Amount:', transaction.details.value.amount);
      console.log('Currency:', transaction.details.value.currency);
      console.log('Narrative:', transaction.metadata.narrative);
      
      if (transaction.transactionAttributes && transaction.transactionAttributes.length > 0) {
        transaction.transactionAttributes.forEach(attribute => {
          console.log(`${attribute.name}: ${attribute.value}`);
        });
      }
    });

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

// Alternative: Get single page of transactions
async function getTransactionsPage(accountNumber, fromDate, toDate, pageStart = 1, pageToken = null) {
  try {
    let url = `https://api.bcbank.us/v1/accounts/${accountNumber}/transactions`;
    const params = new URLSearchParams();
    
    // Always include date range
    params.append('fromDate', fromDate);
    params.append('toDate', toDate);
    
    if (pageStart === 1 && !pageToken) {
      params.append('pageSize', '250'); // Custom page size
    } else {
      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(`Error: ${errorData.message || 'Unknown error'}`);
    }

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

// Example usage:
getAllTransactionsPaginated('1234567890', '2023-01-25', '2023-02-25'); // Retrieves all transactions across multiple pages
// OR
getTransactionsPage('1234567890', '2023-01-25', '2023-02-25', 1).then(firstPage => {
  console.log('First page:', firstPage);
  // Use firstPage.meta.pagination.page_token for subsequent requests
});

Required Permission: get-transactions

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

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/accounts/{accountNumber}/transactions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "id": "string",
      "thisAccount": {
        "number": {},
        "accountRoutings": {}
      },
      "otherAccount": {
        "number": {},
        "accountRoutings": {}
      },
      "details": {
        "type": {},
        "description": {},
        "posted": {},
        "completed": {},
        "newBalance": {},
        "value": {}
      },
      "metadata": {
        "narrative": {}
      },
      "transactionAttributes": [
        {
          "name": {},
          "value": {}
        }
      ]
    }
  ]
}

Get Virtual Account Balances

Retrieves balances for a provided list of virtual account numbers. This endpoint:

• Accepts a JSON payload with one or more accountNumbers
• Returns a JSON envelope with meta and data fields
• Supports both JSON and CSV response formats based on the Accept header
• Pagination: This endpoint does not accept pagination parameters

Required Request Properties

• accountNumbers: Array of virtual account numbers (minimum 1, maximum 1000)

Response shape

• data is an array of { accountNumber, balance { currency, amount } }

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.bcbank.us/v1/virtual-accounts/balances
        

Sample Request in JavaScript

async function getVirtualAccountBalances(accountNumbers) {
  const response = await fetch('https://api.bcbank.us/v1/virtual-accounts/balances', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({ accountNumbers })
  });
            
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Failed to retrieve balances: ${JSON.stringify(errorData)}`);
  }
            
  const result = await response.json();
  // result.data is an array of balances
  result.data.forEach(item => {
    console.log(item.accountNumber, item.balance?.amount, item.balance?.currency);
  });
  return result;
}
            
// Example usage:
getVirtualAccountBalances(['1000331038', '1000331062']);

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.

Request body application/json

Responses

OK - The request was successful.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/virtual-accounts/balances' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "accountNumbers": [
    1000331038,
    1000331062
  ]
}'

{
  "meta": {
    "pagination": {
      "page_start": 0,
      "page_token": null,
      "total_size": 0,
      "page_size": 0
    }
  },
  "data": [
    {
      "accountNumber": 1000331038,
      "balance": {
        "currency": "USD",
        "amount": 192.98
      }
    },
    {
      "accountNumber": 1000331062,
      "balance": {
        "currency": "USD",
        "amount": 0
      }
    }
  ]
}

Get Virtual Account Balances Total

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.bcbank.us/v1/virtual-accounts/balances/total
        

Sample Request in JavaScript

async function getVirtualAccountBalancesTotal() {
  const response = await fetch('https://api.bcbank.us/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.

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/virtual-accounts/balances/total' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

Create Virtual Accounts

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.

Migration notice: v1 is being retained for backward compatibility only and is planned to be discontinued in the future. New integrations should use POST /v2/virtual-accounts and existing consumers should plan their migration to v2.

Schema scope: v1 supports currency, accountHolderName, accountName, optional dob, optional nativeLanguageName, optional unallocated, and optional clientReference. Use v2 when you need nationality, taxIdentificationNumber, or countryOfResidence at create time.

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.
  • Allowed characters (accountHolderName, accountName): A-Z, a-z, 0-9, space, and ! " # $ % & ' ( ) + , - . / [ \ ]. Common symbols such as * _ @ : ; ? { } are not allowed.

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 after the 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",
  "bicCodeFx": "BEOEBMH2",
  "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.bcbank.us/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.bcbank.us/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.

Request body application/json

Responses

Accepted - Virtual account creation job has been queued for processing.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v1/virtual-accounts' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "callbackUrl": "https://my-callback-url.com",
  "customHeaders": {
    "X-Custom-Header-1": "Custom Value 1",
    "X-Custom-Header-2": "Custom Value 2"
  },
  "items": [
    {
      "currency": "USD",
      "accountHolderName": null,
      "accountName": null,
      "clientReference": "BATCH-UNALLOC-001",
      "dob": null,
      "nativeLanguageName": null,
      "unallocated": true
    },
    {
      "currency": "USD",
      "accountHolderName": "Test Company Ltd",
      "accountName": "Test Virtual Account 001",
      "clientReference": "BATCH-REF-001",
      "dob": "1990-01-01T00:00:00.0000000",
      "nativeLanguageName": "Native Name",
      "unallocated": false
    },
    {
      "currency": "USD",
      "accountHolderName": "Test Company Ltd",
      "accountName": "Test Virtual Account 002",
      "clientReference": "BATCH-REF-002",
      "dob": null,
      "nativeLanguageName": null,
      "unallocated": false
    },
    {
      "currency": "USD",
      "accountHolderName": "Test Company Ltd",
      "accountName": "Test Virtual Account 003",
      "clientReference": "BATCH-REF-003",
      "dob": null,
      "nativeLanguageName": null,
      "unallocated": false
    }
  ]
}'

{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "Pending",
  "statusUrl": "https://api.bcbank.us/v1/jobs/550e8400-e29b-41d4-a716-446655440001",
  "resultUrl": "https://api.bcbank.us/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results"
}

Get All Virtual Accounts

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.bcbank.us/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.bcbank.us/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(`  BIC (FX): ${account.bicCodeFx}`);
      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.

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/virtual-accounts' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "meta": {
    "pagination": {
      "page_start": {},
      "page_token": {},
      "total_size": {},
      "page_size": {}
    }
  },
  "data": [
    {
      "virtualAccountNumber": "string",
      "bicCode": "string",
      "bicCodeFx": "string",
      "accountHolderName": "string",
      "accountName": "string",
      "currency": "string",
      "balance": {
        "currency": {},
        "amount": {}
      },
      "category": "string",
      "clientReference": "string",
      "dob": "string",
      "nationality": "string",
      "taxIdentificationNumber": "string",
      "countryOfResidence": "string",
      "nativeLanguageName": "string",
      "unallocated": true
    }
  ]
}

Update Virtual Account

Updates an existing virtual (sub) account for a corporate client. Only the fields provided in the request body will be updated.

Migration notice: v1 is being retained for backward compatibility only and is planned to be discontinued in the future. New integrations should use PATCH /v2/virtual-accounts/{virtualAccountNumber} and existing consumers should plan their migration to v2.

Updatable Properties

• accountHolderName: Human-readable label for the virtual account. Immutable after first update – can only be changed once from the "UNALLOCATED" state.
• accountName: Official account title that will appear on statements. Immutable after first update – can only be changed once from the "UNALLOCATED" state.
• Allowed characters (accountHolderName, accountName): A-Z, a-z, 0-9, space, and ! " # $ % & ' ( ) + , - . / [ \ ]. Common symbols such as * _ @ : ; ? { } are not allowed.
• dob: Date of birth of the account holder. Immutable after first update – can only be set once.
• nativeLanguageName: Native name of the account holder's language (max 255 characters). Immutable after first update – can only be set once.
• clientReference: External reference provided by the client to aid reconciliation (max 35 characters). This field can be updated multiple times.

Schema scope: v1 supports accountHolderName, accountName, dob, nativeLanguageName, and clientReference. Use v2 when you need nationality, taxIdentificationNumber, or countryOfResidence.

Allocating Unallocated Accounts

For virtual accounts created with unallocated: true, use this endpoint to perform a one-time assignment to a real end-customer:

• Update accountHolderName, accountName, dob, and nativeLanguageName from their initial/placeholder values to the actual customer details
• Important: This is a one-time operation. Once these fields are set, they become immutable:
  • accountHolderName and accountName can only be changed from "UNALLOCATED" state
  • dob and nativeLanguageName can only be set once (if not provided during creation)
• Attempting to update immutable fields after the first update will result in a 409 Conflict error with code ACCOUNT_NAMES_IMMUTABLE
• Only clientReference can be updated after allocation

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.bcbank.us/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 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").

Sample Request (JavaScript)

async function updateVirtualAccount(virtualAccountNumber) {
  try {
    const response = await fetch(`https://api.bcbank.us/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.bcbank.us/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');

Required Permission: update-virtual-account

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

Request parameters

Request body application/json

object

Responses

Virtual account updated successfully.

curl --request PATCH \
  --url 'https://api-uat.bcbank.us/v1/virtual-accounts/{virtualAccountNumber}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "accountHolderName": "Updated Project Alpha Escrow",
  "accountName": "Updated Project Alpha Virtual Account",
  "clientReference": "ref-1234567890",
  "dob": "1990-05-15T00:00:00.0000000",
  "nativeLanguageName": "Native Name"
}'

{
  "virtualAccountNumber": "string",
  "bicCode": "string",
  "bicCodeFx": "string",
  "accountHolderName": "string",
  "accountName": "string",
  "currency": "string",
  "balance": {
    "currency": "string",
    "amount": "string"
  },
  "category": "string",
  "clientReference": "string",
  "dob": "string",
  "nationality": "string",
  "taxIdentificationNumber": "string",
  "countryOfResidence": "string",
  "nativeLanguageName": "string",
  "unallocated": true,
  "effectiveDate": "string",
  "createdAt": "string",
  "parentAccount": {
    "accountId": "string",
    "cif": "string",
    "accountNumber": "string",
    "status": "string",
    "currency": "string",
    "availableBalance": {},
    "accountSubType": "string",
    "accountType": "string",
    "nickname": "string",
    "owners": [
      {}
    ],
    "accountAttributes": [
      {}
    ]
  },
  "settlementAccount": {
    "accountId": "string",
    "cif": "string",
    "accountNumber": "string",
    "status": "string",
    "currency": "string",
    "availableBalance": {},
    "accountSubType": "string",
    "accountType": "string",
    "nickname": "string",
    "owners": [
      {}
    ],
    "accountAttributes": [
      {}
    ]
  }
}

Get Virtual Account Details

Retrieves comprehensive information about a specific virtual account, including all its sub-accounts, parent account details, and settlement account information. This endpoint:

• Returns the virtual account details as a single object
• Includes parent account information (the account this virtual account is derived from)
• Provides settlement account details (the account used for settlement operations)

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.bcbank.us/v1/virtual-accounts/{accountNumber}

Sample Request in JavaScript

async function getVirtualAccountDetails(accountNumber) {
  try {
    const url = `https://api.bcbank.us/v1/virtual-accounts/${encodeURIComponent(accountNumber)}`;

    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 account details retrieval failed: ${JSON.stringify(errorData)}`);
    }

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

    // Get the virtual account details (single object, not an array)
    const virtualAccount = result.data;
    console.log('Virtual Account Details:');
    console.log(`  Account Number: ${virtualAccount.virtualAccountNumber}`);
    console.log(`  BIC: ${virtualAccount.bicCode}`);
    console.log(`  BIC (FX): ${virtualAccount.bicCodeFx}`);
    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}`);
    }
    
    console.log(`  Effective Date: ${virtualAccount.effectiveDate}`);
    console.log(`  Created: ${virtualAccount.createdAt}`);
    
    if (virtualAccount.clientReference) {
      console.log(`  Client Reference: ${virtualAccount.clientReference}`);
    }
    
    // Log parent account details
    if (virtualAccount.parentAccount) {
      console.log('  Parent Account:');
      console.log(`    Account Number: ${virtualAccount.parentAccount.accountNumber}`);
      console.log(`    Account ID: ${virtualAccount.parentAccount.accountId}`);
      console.log(`    CIF: ${virtualAccount.parentAccount.cif}`);
      console.log(`    Currency: ${virtualAccount.parentAccount.currency}`);
      console.log(`    Sub Type: ${virtualAccount.parentAccount.accountSubType}`);
      console.log(`    Status: ${virtualAccount.parentAccount.status}`);
      if (virtualAccount.parentAccount.availableBalance) {
        console.log(`    Available Balance: ${virtualAccount.parentAccount.availableBalance.amount} ${virtualAccount.parentAccount.availableBalance.currency}`);
      }
      if (virtualAccount.parentAccount.owners && virtualAccount.parentAccount.owners.length > 0) {
        console.log(`    Owner: ${virtualAccount.parentAccount.owners[0].displayName} (${virtualAccount.parentAccount.owners[0].accountHolderType})`);
      }
    }
    
    // Log settlement account details
    if (virtualAccount.settlementAccount) {
      console.log('  Settlement Account:');
      console.log(`    Account Number: ${virtualAccount.settlementAccount.accountNumber}`);
      console.log(`    Account ID: ${virtualAccount.settlementAccount.accountId}`);
      console.log(`    CIF: ${virtualAccount.settlementAccount.cif}`);
      console.log(`    Currency: ${virtualAccount.settlementAccount.currency}`);
      console.log(`    Sub Type: ${virtualAccount.settlementAccount.accountSubType}`);
      console.log(`    Status: ${virtualAccount.settlementAccount.status}`);
      if (virtualAccount.settlementAccount.availableBalance) {
        console.log(`    Available Balance: ${virtualAccount.settlementAccount.availableBalance.amount} ${virtualAccount.settlementAccount.availableBalance.currency}`);
      }
      if (virtualAccount.settlementAccount.owners && virtualAccount.settlementAccount.owners.length > 0) {
        console.log(`    Owner: ${virtualAccount.settlementAccount.owners[0].displayName} (${virtualAccount.settlementAccount.owners[0].accountHolderType})`);
      }
    }

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

// Example usage:

// Get details for a specific virtual account
getVirtualAccountDetails('1000326808');

Required Permission: get-a-virtual-account

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

Request parameters

Responses

OK - The request was successful.

curl --request GET \
  --url 'https://api-uat.bcbank.us/v1/virtual-accounts/{virtualAccountNumber}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "virtualAccountNumber": "string",
  "bicCode": "string",
  "bicCodeFx": "string",
  "accountHolderName": "string",
  "accountName": "string",
  "currency": "string",
  "balance": {
    "currency": "string",
    "amount": "string"
  },
  "category": "string",
  "clientReference": "string",
  "dob": "string",
  "nationality": "string",
  "taxIdentificationNumber": "string",
  "countryOfResidence": "string",
  "nativeLanguageName": "string",
  "unallocated": true,
  "effectiveDate": "string",
  "createdAt": "string",
  "parentAccount": {
    "accountId": "string",
    "cif": "string",
    "accountNumber": "string",
    "status": "string",
    "currency": "string",
    "availableBalance": {},
    "accountSubType": "string",
    "accountType": "string",
    "nickname": "string",
    "owners": [
      {}
    ],
    "accountAttributes": [
      {}
    ]
  },
  "settlementAccount": {
    "accountId": "string",
    "cif": "string",
    "accountNumber": "string",
    "status": "string",
    "currency": "string",
    "availableBalance": {},
    "accountSubType": "string",
    "accountType": "string",
    "nickname": "string",
    "owners": [
      {}
    ],
    "accountAttributes": [
      {}
    ]
  }
}

Create Virtual Accounts (V2)

Creates one or more virtual (sub) accounts using the v2 request schema.

V2 difference: v2 introduces an accountHolderType discriminator (Individual | Business) and moves the holder-specific KYC fields into nested individual / business objects. Only the block matching accountHolderType may be supplied. Holder fields are required only for allocated accounts (unallocated = false). clientReference, callback handling, and batch job semantics behave the same as v1.

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: Full legal name of the holder (required unless unallocated is true). Immutable after first update.
  • accountName: Account name that appears on statements (required unless unallocated is true). Immutable after first update.
  • Allowed characters (accountHolderName, accountName, address fields): A-Z, a-z, 0-9, space, and ! " # $ % & ' ( ) + , - . / [ \ ]. Common symbols such as * _ @ : ; ? { } are not allowed.
  • accountHolderType: Individual or Business. When omitted, the original v2 rule applies (individual.dob + individual.nationality required when allocated).
  • For Individual (allocated): individual.dob (ISO 8601 date, in the past and at least 18 years ago) and individual.nationality (ISO 3166-1 alpha-2) are required. Immutable after first update.
  • For Business (allocated): business.registeredAddress is required with addressLine1, city, postalCode, and country (ISO 3166-1 alpha-2). business.dateOfIncorporation and business.countryOfIncorporation are optional (sole traders / partnerships are not incorporated).

Optional Request Properties

• taxIdentificationNumber: Optional customer tax identifier (max 30 characters)
• countryOfResidence: Optional ISO 3166-1 alpha-2 country code
• individual.nativeLanguageName: Native name of the account holder's language, if applicable (max 255 characters). Immutable after first update.
• business.dateOfIncorporation / business.countryOfIncorporation: Optional even for a Business; immutable after first update when set.
• business.registeredAddress.addressLine2: Optional (max 70 characters). addressLine1/addressLine2 max 70; city/postalCode max 35.
• unallocated: When set to true, creates the account in "for allocation" mode and defers the mandatory v2 holder fields until the one-time allocation PATCH.
• 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

When unallocated is true, the batch can pre-create accounts for later assignment. The mandatory v2 holder fields (per accountHolderType) are enforced when the account is allocated via PATCH rather than during creation.

Asynchronous Processing

This endpoint queues a background job and immediately returns job tracking URLs.

Message Signing

Callback notifications are signed using the same rules and headers as v1.

Job Status Tracking

The response includes a job ID plus status and result URLs for monitoring completion.

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.bcbank.us/v2/virtual-accounts
        

Idempotency

Idempotency behaviour is identical to v1.

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.

Request body application/json

Responses

Accepted - Virtual account creation job has been queued for processing.

curl --request POST \
  --url 'https://api-uat.bcbank.us/v2/virtual-accounts' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "callbackUrl": "https://my-callback-url.com",
  "customHeaders": {
    "X-Custom-Header-1": "Custom Value 1",
    "X-Custom-Header-2": "Custom Value 2"
  },
  "items": [
    {
      "currency": "USD",
      "unallocated": true,
      "clientReference": "BATCH-UNALLOC-V2-001"
    },
    {
      "currency": "USD",
      "accountHolderName": "Jonathan Michael Adebayo-Okoro",
      "accountName": "Adebayo Trading",
      "clientReference": "BATCH-V2-IND-001",
      "taxIdentificationNumber": "TIN-001",
      "countryOfResidence": "BM",
      "accountHolderType": "Individual",
      "individual": {
        "dob": "1985-04-23",
        "nationality": "HK",
        "nativeLanguageName": "Native Name"
      },
      "unallocated": false
    },
    {
      "currency": "USD",
      "accountHolderName": "Titan Logistics Holdings Ltd",
      "accountName": "Titan",
      "clientReference": "BATCH-V2-BUS-001",
      "taxIdentificationNumber": "98-7654321",
      "accountHolderType": "Business",
      "business": {
        "dateOfIncorporation": "2014-09-30",
        "countryOfIncorporation": "BM",
        "registeredAddress": {
          "addressLine1": "44 Front Street",
          "addressLine2": "Suite 300",
          "city": "Hamilton",
          "postalCode": "HM 12",
          "country": "BM"
        }
      },
      "unallocated": false
    }
  ]
}'

{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "Pending",
  "statusUrl": "https://api.bcbank.us/v1/jobs/550e8400-e29b-41d4-a716-446655440001",
  "resultUrl": "https://api.bcbank.us/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results"
}

Get All Virtual Accounts (V2)

Identical to the v1 list endpoint, but returns the v2 read schema: holder KYC is nested under accountHolderType + individual / business (with business.registeredAddress). taxIdentificationNumber and countryOfResidence remain at the top level.

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.

Request parameters

Responses

OK - The request was successful.