# Accounts

## Account Details

 - [GET /v1/accounts/{accountNumber}](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/accounts/accounts_get.md): 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.bcb.bm/v1/accounts

### Sample Request in JavaScript:

javascript
async function getAccountDetails(accountNumber) {
  try {
    const response = await fetch(https://api.bcb.bm/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.

## List User Accounts

 - [GET /v1/accounts](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/accounts/accounts_getall.md): 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.bcb.bm/v1/accounts

### Sample Request in JavaScript

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.bcb.bm/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  {
      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.bcb.bm/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.

## List payment statuses for an account

 - [GET /v1/accounts/{accountNumber}/payments](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/accounts/transactionstatus_getaccounttransactionstatuses.md): Retrieves status information for all payments associated with a specific account. This endpoint:
            
- Provides comprehensive payment status details including type, status, transaction ID, external reference, remittance information, amounts, value date, and exchange rate.
- Supports both JSON and CSV response formats based on the Accept header.
- Supports cursor-based pagination for efficient handling of large payment status datasets.

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

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/accounts/{accountNumber}/payments

### Sample Request in JavaScript

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

    do {
      // Build URL with pagination parameters
      let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
      const params = new URLSearchParams();
      
      if (pageStart === 1) {
        // First request: specify pageSize
        params.append('pageSize', '100');
      } else {
        // Subsequent requests: use pageToken and pageStart
        params.append('pageToken', pageToken);
        params.append('pageStart', pageStart.toString());
      }
      
      if (params.toString()) {
        url += '?' + params.toString();
      }

      const response = await fetch(url, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(Error: ${errorData.message || 'Unknown error'});
      }

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

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

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

      pageStart++;
    } while (pageStart  {
      console.log(Payment ${index + 1}:, payment.transactionId);
      console.log('Type:', payment.type);
      console.log('Status:', payment.status);
      console.log('External Reference:', payment.externalReference);
      console.log('Remittance Information:', payment.remittanceInformation);
      console.log('Value Date:', payment.valueDate);
      console.log('Debit Amount:', ${payment.debitAmount.amount} ${payment.debitAmount.currency});
      if (payment.creditAmount && payment.creditAmount.amount) {
        console.log('Credit Amount:', ${payment.creditAmount.amount} ${payment.creditAmount.currency});
      }
      console.log('-------------------');
    });

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

// Alternative: Get single page of payment statuses
async function getPaymentStatusesPage(accountNumber, pageStart = 1, pageToken = null) {
  try {
    let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
    const params = new URLSearchParams();
    
    if (pageStart === 1 && !pageToken) {
      params.append('pageSize', '50'); // Custom page size
    } else {
      params.append('pageToken', pageToken);
      params.append('pageStart', pageStart.toString());
    }
    
    if (params.toString()) {
      url += '?' + params.toString();
    }

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Error: ${errorData.message || 'Unknown error'});
    }

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

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


Required Permission: get-payment-status

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

## List payment statuses for an account

 - [GET /v1/accounts/{accountNumber}/payments](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/payments/transactionstatus_getaccounttransactionstatuses.md): Retrieves status information for all payments associated with a specific account. This endpoint:
            
- Provides comprehensive payment status details including type, status, transaction ID, external reference, remittance information, amounts, value date, and exchange rate.
- Supports both JSON and CSV response formats based on the Accept header.
- Supports cursor-based pagination for efficient handling of large payment status datasets.

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

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/accounts/{accountNumber}/payments

### Sample Request in JavaScript

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

    do {
      // Build URL with pagination parameters
      let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
      const params = new URLSearchParams();
      
      if (pageStart === 1) {
        // First request: specify pageSize
        params.append('pageSize', '100');
      } else {
        // Subsequent requests: use pageToken and pageStart
        params.append('pageToken', pageToken);
        params.append('pageStart', pageStart.toString());
      }
      
      if (params.toString()) {
        url += '?' + params.toString();
      }

      const response = await fetch(url, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(Error: ${errorData.message || 'Unknown error'});
      }

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

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

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

      pageStart++;
    } while (pageStart  {
      console.log(Payment ${index + 1}:, payment.transactionId);
      console.log('Type:', payment.type);
      console.log('Status:', payment.status);
      console.log('External Reference:', payment.externalReference);
      console.log('Remittance Information:', payment.remittanceInformation);
      console.log('Value Date:', payment.valueDate);
      console.log('Debit Amount:', ${payment.debitAmount.amount} ${payment.debitAmount.currency});
      if (payment.creditAmount && payment.creditAmount.amount) {
        console.log('Credit Amount:', ${payment.creditAmount.amount} ${payment.creditAmount.currency});
      }
      console.log('-------------------');
    });

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

// Alternative: Get single page of payment statuses
async function getPaymentStatusesPage(accountNumber, pageStart = 1, pageToken = null) {
  try {
    let url = https://api.bcb.bm/v1/accounts/${accountNumber}/payments;
    const params = new URLSearchParams();
    
    if (pageStart === 1 && !pageToken) {
      params.append('pageSize', '50'); // Custom page size
    } else {
      params.append('pageToken', pageToken);
      params.append('pageStart', pageStart.toString());
    }
    
    if (params.toString()) {
      url += '?' + params.toString();
    }

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Error: ${errorData.message || 'Unknown error'});
    }

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

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


Required Permission: get-payment-status

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