# Internal Transfers

## Internal Transfer

 - [POST /v1/internal-transfers](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/internal-transfers/internaltransfers_post.md): 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.bcb.bm/v1/internal-transfers
            
### Sample Request in JavaScript:
            
javascript
async function executeInternalTransfer() {
  try {
    const response = await fetch('https://api.bcb.bm/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.