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.bcbank.us
• You need valid UAT credentials and a token from /auth/token.
• 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:

{
  "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 [email protected] 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:

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

The response can contain three account categories:

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.

curl -X POST "https://api-uat.bcbank.us/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:

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

4. Poll the job status

Use the jobId or statusUrl from the create response.

curl -X GET "https://api-uat.bcbank.us/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:

curl -X GET "https://api-uat.bcbank.us/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:

curl -X GET "https://api-uat.bcbank.us/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.

curl -X PATCH "https://api-uat.bcbank.us/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 before implementing money movement.
• Read the Troubleshooting guide for common 400 and job-state issues.
• Read the UAT limitations guide for sandbox-specific behavior.