# First Successful VAS Integration in UAT

Use this guide to get from credentials to a working virtual account in UAT without relying on the portal UI.

## What success looks like

By the end of this guide you should be able to:

- create a virtual account with `POST /v1/virtual-accounts`
- monitor the background job with `GET /v1/jobs/{jobId}`
- read the final result from `GET /v1/jobs/{jobId}/results`
- identify the account categories returned by `GET /v1/virtual-accounts`
- update `clientReference` with `PATCH /v1/virtual-accounts/{virtualAccountNumber}`


## 1. Confirm your UAT prerequisites

- Base URL: `https://api-uat.bcb.bm`
- You need valid UAT credentials and a token from [`/auth/token`](/guides/authentication).
- Your client must be enabled for Virtual Accounts.
- The currency you want to use must already have both of these provisioned for your client:
  - a Settlement Account
  - a Parent Account


If either account is missing for that currency, the create request may still be accepted as a background job, but the item result will fail with a `400` and an error such as:


```json
{
  "error": "BAD_REQUEST",
  "message": "Unfortunately, your virtual account could not be created / updated due to a technical issue. Please verify all provided information is correct.; No parent account with matching currency found"
}
```

If this happens, contact your Relationship Manager or [api@bcb.bm](mailto:api@bcb.bm) and ask for VAS provisioning in that currency.

## 2. Verify the currency is provisioned

The quickest API check is to list VAS accounts for the currency you want to use:


```bash
curl -X GET "https://api-uat.bcb.bm/v1/virtual-accounts?currency=USD&pageSize=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

The response can contain three account categories:

| Category | Meaning |
|  --- | --- |
| `CMS Settlement` | External-facing settlement account for that currency |
| `CMS Parent Cate` | Parent account for that currency |
| `CMS Sub Acct` | Actual virtual accounts / sub accounts |


If you do not see both `CMS Settlement` and `CMS Parent Cate` for the requested currency, do not continue with account creation yet.

## 3. Create the virtual account

`POST /v1/virtual-accounts` is asynchronous. A `202 Accepted` response means the request has been queued, not completed.


```bash
curl -X POST "https://api-uat.bcb.bm/v1/virtual-accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      {
        "currency": "USD",
        "accountHolderName": "Jane Smith",
        "accountName": "Jane Smith",
        "clientReference": "USER-12345"
      }
    ]
  }'
```

Expected response:


```json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "Pending",
  "statusUrl": "https://api-uat.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001",
  "resultUrl": "https://api-uat.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results"
}
```

## 4. Poll the job status

Use the `jobId` or `statusUrl` from the create response.


```bash
curl -X GET "https://api-uat.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Typical lifecycle:

- `Pending`: queued and waiting to be processed
- `InProgress`: actively being processed
- `Completed`: all items succeeded
- `CompletedWithErrors`: the job finished, but one or more items failed


`Pending` is a normal intermediate state in UAT. Do not treat it as a failure by itself.

## 5. Read the final job results

Once the job is complete, retrieve the per-item results:


```bash
curl -X GET "https://api-uat.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results?pageStart=1&pageSize=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Each result item gives you the final outcome for the submitted account:

- `status`: item processing status
- `httpStatus`: HTTP result for that item
- `error`: failure reason, if any
- `resultJson`: the created virtual account details on success


Use `resultJson` as the source of truth for the created `virtualAccountNumber` and `bicCode`.

## 6. List accounts and identify the categories

After a successful create, list VAS accounts again:


```bash
curl -X GET "https://api-uat.bcb.bm/v1/virtual-accounts?currency=USD&pageSize=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Important: this endpoint returns more than just sub accounts.

- `CMS Settlement` is your settlement account
- `CMS Parent Cate` is your parent account
- `CMS Sub Acct` are the virtual accounts you created


If you are building a customer-facing list, filter for `category === "CMS Sub Acct"` in your application.

## 7. Update `clientReference`

You can update `clientReference` after the account has been created and allocated.


```bash
curl -X PATCH "https://api-uat.bcb.bm/v1/virtual-accounts/1000327642" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "clientReference": "USER-12345-PRIMARY"
  }'
```

Use this when you need to map the virtual account to your own user or wallet identifier.

## 8. Verify downstream activity

Once the account exists, these are the most useful verification endpoints:

- `GET /v1/virtual-accounts/{virtualAccountNumber}`
- `GET /v1/virtual-accounts/{virtualAccountNumber}/transactions`
- `GET /v1/virtual-accounts/{virtualAccountNumber}/deposits`


If the portal UI and API disagree in UAT, treat the API as the source of truth and verify state directly through these endpoints.

## Next steps

- Read the [API Flows guide](/guides/virtual-accounts/1-1-diagram) before implementing money movement.
- Read the [Troubleshooting guide](/guides/virtual-accounts/12-troubleshooting) for common `400` and job-state issues.
- Read the [UAT limitations guide](/guides/virtual-accounts/13-uat-limitations-known-issues) for sandbox-specific behavior.