Bulk Creation & Pre-provisioning

The virtual account system supports an unallocated flag during creation, allowing you to bulk pre-provision accounts before they are needed. This feature is designed for high-volume use cases where instant account assignment is critical for the user experience.

Why Pre-provision Accounts?

1. Instant Customer Onboarding

Standard account creation may involve slight delays as systems process the request. By maintaining a pool of pre-created, unallocated accounts, you can instantly assign a virtual account number to a new customer the moment they sign up, without waiting for upstream provider responses.

2. Regulatory Compliance & Clean History

Reallocating used accounts to different customers can create audit and compliance complexities. The pre-provisioning model ensures that every customer receives a fresh account with no prior transaction history, maintaining strict segregation of data and funds.

3. Batch Processing Efficiency

Instead of making individual API calls for every new user in real-time, you can run batch jobs to replenish your pool of unallocated accounts during off-peak hours, ensuring you always have inventory ready for peak demand.

Workflow

The following diagram illustrates how the pre-provisioning and allocation process works:

%%{init: {'theme': 'neutral', 'themeVariables': { 'fontSize': '16px', 'fontFamily': 'arial' }}}%%
sequenceDiagram
    participant User as End Customer
    participant Client as Client System
    participant API as BCB API
    
    note over Client, API: Phase 1: Pre-provisioning (Batch Job)
    Client->>API: POST /v1/virtual-accounts (items: [{unallocated: true}, ...])
    API-->>Client: Returns list of Unallocated Accounts
    Client->>Client: Store accounts in Inventory Pool
    
    note over User, Client: Phase 2: Instant Onboarding
    User->>Client: Sign Up / Request Account
    Client->>Client: Fetch available account from Pool
    Client->>API: PATCH /v1/virtual-accounts/{id} (Set customer details)
    API-->>Client: 200 OK (Account Allocated)
    Client-->>User: Display Account Number immediately

Step 1: Create a Pool of Unallocated Accounts

When your inventory of available accounts runs low, you can create a new batch. For standard operations (1-2 accounts), the normal creation flow is sufficient. For larger volumes, use the unallocated flag.

Endpoint: POST /v1/virtual-accounts

Request: You only need to specify the currency and the unallocated flag within the items array.

{
  "items": [
    {
      "currency": "USD",
      "unallocated": true
    },
    {
      "currency": "USD",
      "unallocated": true
    }
  ]
}

Step 2: Assign (Allocate) an Account

When a new customer needs an account, you select one from your unallocated pool and update its details. This "claims" the account for that specific customer.

Endpoint: PATCH /v1/virtual-accounts/{virtualAccountNumber}

Key Behavior:

• While Unallocated: You can update core identity fields (accountName, accountHolderName, dob, nativeLanguageName) and the clientReference.
• To Allocate: Update the account with the customer's real details (accountName, accountHolderName, etc.). This permanently assigns the account to that customer.
• After Allocation: Once an account is allocated to a customer, only the clientReference can be updated. This ensures the integrity of the account ownership.

Example Allocation Request:

{
  "accountHolderName": "Jane Smith",
  "accountName": "Jane Smith",
  "clientReference": "USER_ID_98765",
  "dob": "1985-05-20",
  "nativeLanguageName": "Jane Smith"
}