# Create Virtual Account

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.
            
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.
            
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 afther 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:

json
{
  "virtualAccountNumber": "1000327642",
  "bicCode": "BPBKBMHMXXX",
  "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.bcb.bm/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
            
javascript
async function createVirtualAccounts() {
  try {
    const response = await fetch('https://api.bcb.bm/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.

Endpoint: POST /v1/virtual-accounts
Version: v1
Security: Authorization, Feature Permissions

## Request fields (application/json):

  - `callbackUrl` (string,null)
    Optional URL to receive asynchronous notifications about the async job processing status.

  - `customHeaders` (object,null)
    Optional custom headers to include in the account creation request. It will be sent back in callbacks.
Max 10 headers, each key max 50 chars, each value max 500 chars

  - `items` (array, required)
    Payload containing the details of virtual accounts to be created in batch.

  - `items.currency` (string, required)
    ISO 4217 currency code for the virtual account (e.g., USD, EUR, BMD).
Must be a supported currency by the bank.

  - `items.accountHolderName` (string,null)
    Human-readable nickname or label for the virtual account.
Used for display purposes and client identification.
Optional when Unallocated is true; otherwise required.

  - `items.accountName` (string,null)
    Official account name as it will appear on statements and official documents.
This is the formal name of the virtual account.
Optional when Unallocated is true; otherwise required.

  - `items.clientReference` (string,null)
    Client-provided reference identifier for tracking and identification purposes.
This reference should be unique within the client's system for easier reconciliation.

  - `items.dob` (string,null)
    Date of birth of the account holder, if applicable.

  - `items.nativeLanguageName` (string,null)
    Native name of the account holder's language, if applicable.

  - `items.unallocated` (boolean, required)
    Indicates whether the virtual account is pre-created for future allocation.
When set to true, the account is created in "for allocation" mode with placeholder
values ("UNALLOCATED") for AccountHolderName and AccountName,
which become optional. This allows clients to bulk-create virtual accounts and later
perform a one-time update to assign them to real end-customers.

## Response 202 fields (application/json):

  - `jobId` (string, required)
    Unique identifier assigned to the batch job.

  - `status` (string, required)
    Current lifecycle state of the batch job (e.g.Pending, InProgress, Completed, CompletedWithErrors, Cancelled).

  - `statusUrl` (string, required)
    Absolute URL that can be polled to retrieve up-to-date job status information.

  - `resultUrl` (string, required)
    Absolute URL to obtain the final per-item results once the job has completed.

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 403 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition

## Response 500 fields (application/json):

  - `error` (string, required)
    Error code or type that identifies the specific error condition

  - `message` (string, required)
    Human-readable error message that describes the error condition