# Transactions

## Account Transactions

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

### Sample Request in JavaScript
            
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.bcb.bm/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  {
      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.bcb.bm/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.