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.
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.
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.
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.
The following diagram illustrates how the pre-provisioning and allocation process works:
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
}
]
}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 theclientReference. - 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
clientReferencecan 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"
}