API Flows

Click the diagram to open the interactive version, with zoom and clickable API links.

Example of credit API Flow

Read the diagram with these rules

• Every approved VAS money movement must respect the Settlement -> Parent -> Sub hierarchy.
• A create call is asynchronous. You must wait for the background job result before treating the account as created.
• GET /v1/virtual-accounts returns Settlement, Parent, and Sub accounts together.
• clientReference is updated with PATCH /v1/virtual-accounts/{virtualAccountNumber}.

Allowed vs prohibited flows

Concrete valid requests

Valid: create a virtual account and read the result from the job

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"
      }
    ]
  }'

Then:

• poll GET /v1/jobs/{jobId}
• read GET /v1/jobs/{jobId}/results
• extract the created virtualAccountNumber from resultJson

Valid: update only clientReference

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"
  }'

Concrete invalid requests

Invalid: internal transfer from one virtual account directly to another

curl -X POST "https://api-uat.bcbank.us/v1/internal-transfers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "debitAccountNumber": "1000428667",
    "debitAmountCurrency": "USD",
    "creditAccountNumber": "1000432675",
    "creditAmountCurrency": "USD",
    "debitAmount": "100.00"
  }'

Why it is invalid:

• both accounts are sub accounts
• same currency is not enough
• Sub -> Sub is not a permitted VAS flow

Invalid: assuming the create request is complete when the API returns 202 Pending

The create response only confirms the job was accepted. The account is not ready until the background job completes and the item result succeeds.