{ "x-generator": "NSwag v14.6.3.0 (NJsonSchema v11.5.2.0 (Newtonsoft.Json v13.0.0.0))", "openapi": "3.0.0", "info": { "title": "Bermuda Commercial Bank RESTful Open Banking API Implementation", "description": "The Bermuda Commercial Bank (BCB) RESTful Open Banking API provides secure, programmatic access to BCB's banking services, enabling developers to integrate financial services into their applications.\n\n### Key Features\n- Account details retrieval\n- Internal transfers\n- Payments (Swift)\n- Virtual Accounts\n- Transaction information access\n- Robust security and compliance\n- Comprehensive documentation\n### Available Environments\n**UAT Environment**\n\n**URL:** https://api-uat.bcb.bm\n\n**Purpose:** Testing and integration\n\n**Production Environment**\n\n**URL:** https://api.bcb.bm\n\n**Purpose:** Live production use\n\n", "contact": { "name": "Bermuda Commercial Bank Limited, 34 Bermudiana Road, Hamilton HM 11, Bermuda", "url": "https://www.bcb.bm", "email": "enquiries@bcb.bm" }, "version": "v1" }, "servers": [ { "url": "https://api-uat.bcb.bm", "description": "UAT Environment - Used for testing and integration purposes" }, { "url": "https://api.bcb.bm", "description": "Production Environment - Live environment for production use" } ], "paths": { "/v1/accounts/{accountNumber}": { "get": { "tags": [ "Accounts" ], "summary": "Account Details", "description": "Retrieves the account details and balance. This endpoint requires authentication and returns comprehensive information for the specified account. The returned data includes:\n\n- **Number**: The human-readable account number assigned by the bank.\n- **Label**: A label provided by the account owner.\n- **Owners**: The list of users who own this account.\n- **Type**: The type of account.\n- **Balance**: The account's balance including currency and amount.\n- **Account Attributes**: Additional account information specific to Bermuda Commercial Bank.\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default).\n- Set `Accept: text/csv` for CSV responses.\nIf the Accept header is omitted, `application/json` is assumed.\n \n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/accounts\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function getAccountDetails(accountNumber) {\n try {\n const response = await fetch(`https://api.bcb.bm/v1/accounts/${accountNumber}`, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log('Account details:', data);\n\n // Example processing of the returned object\n const accountId = data.id;\n const accountNumber = data.number;\n const accountBalance = data.balance.amount;\n const accountCurrency = data.balance.currency;\n const accountStatus = data.accountAttributes.find(attr => attr.name === 'STATUS')?.value;\n \n console.log('Account ID:', accountId);\n console.log('Account Number:', accountNumber);\n console.log('Account Balance:', accountBalance);\n console.log('Account Currency:', accountCurrency);\n console.log('Account Status:', accountStatus);\n \n // Process all account attributes\n console.log('Account Attributes:');\n data.accountAttributes.forEach(attribute => {\n console.log(`${attribute.name}: ${attribute.value}`);\n });\n\n // Additional processing based on account status\n if (accountStatus === 'ACTIVE') {\n console.log('The account is active.');\n } else {\n console.log('The account is not active.');\n }\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n }\n}\n\n// Example usage:\ngetAccountDetails('YOUR_ACCOUNT_NUMBER');\n```\n\n**Required Permission:** `get-account`\n\nThis endpoint requires the permission claim `get-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Accounts_Get", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "The human-readable account number assigned by the bank.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "examples": { "Json": { "value": { "openingDate": "2023-01-01T00:00:00.0000000Z", "balanceEffectiveDate": "2023-12-31T00:00:00.0000000Z", "accountRoutings": [ { "scheme": "AccountNumber", "address": 1000078766 } ], "accountId": "1000078766-3000032", "cif": 3000032, "currency": "USD", "accountSubType": "BCB.CURRENT.ACCOUNT.C", "accountNumber": 1000078766, "status": "Active", "availableBalance": { "currency": "USD", "amount": 1000 }, "accountType": "Personal", "nickname": "CURRENT.ACCOUNTS", "owners": [ { "displayName": "John Doe", "accountHolderType": "Primary" }, { "displayName": "Jane Doe", "accountHolderType": "Joint" } ], "accountAttributes": [ { "name": "BANK_ID", "value": "BPBKBMHM" }, { "name": "JOINT_CIF", "value": 3000033 }, { "name": "CREDIT_INTEREST_RATE", "value": 2.5 }, { "name": "DEBIT_INTEREST_RATE", "value": 0 }, { "name": "DEBIT_ACCRUED_INTEREST", "value": 0 }, { "name": "CREDIT_ACCRUED_INTEREST", "value": 0 }, { "name": "ACCRUAL_INTEREST", "value": 0 } ] } }, "Csv": { "value": [ "\"account_id\",\"cif\",\"account_number\",\"status\",\"currency\",\"available_balance_currency\",\"available_balance_amount\",\"account_sub_type\",\"account_type\",\"nickname\",\"opening_date\",\"balance_effective_date\",\"account_routings_0_scheme\",\"account_routings_0_address\",\"owners_0_display_name\",\"owners_0_account_holder_type\",\"owners_1_display_name\",\"owners_1_account_holder_type\",\"account_attributes_0_name\",\"account_attributes_0_value\",\"account_attributes_1_name\",\"account_attributes_1_value\",\"account_attributes_2_name\",\"account_attributes_2_value\",\"account_attributes_3_name\",\"account_attributes_3_value\",\"account_attributes_4_name\",\"account_attributes_4_value\",\"account_attributes_5_name\",\"account_attributes_5_value\",\"account_attributes_6_name\",\"account_attributes_6_value\"", "\"1000078766-3000032\",\"3000032\",\"1000078766\",\"Active\",\"USD\",\"USD\",\"1000.00\",\"BCB.CURRENT.ACCOUNT.C\",\"Personal\",\"CURRENT.ACCOUNTS\",\"2023-01-01T00:00:00Z\",\"2023-12-31T00:00:00Z\",\"AccountNumber\",\"1000078766\",\"John Doe\",\"Primary\",\"Jane Doe\",\"Joint\",\"BANK_ID\",\"BPBKBMHM\",\"JOINT_CIF\",\"3000033\",\"CREDIT_INTEREST_RATE\",\"2.5\",\"DEBIT_INTEREST_RATE\",\"0\",\"DEBIT_ACCRUED_INTEREST\",\"0\",\"CREDIT_ACCRUED_INTEREST\",\"0\",\"ACCRUAL_INTEREST\",\"0\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - The account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-account" ] }, { "Authorization": [] } ] } }, "/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List User Accounts", "description": "Retrieves a list of all accounts associated with the authenticated user's profile. This endpoint:\n\n- Uses the customer account number from the authenticated user's session to fetch all associated accounts.\n- Requires valid authentication.\n- Supports both JSON and CSV response formats based on the Accept header.\n- Returns a summary version of account information (AccountSummary) containing only essential fields\n- **Supports cursor-based pagination** for efficient handling of large account lists.\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including `pageSize`, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default).\n- Set `Accept: text/csv` for CSV responses.\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/accounts\n\n### Sample Request in JavaScript\n\n```javascript\nasync function getAllAccountsPaginated() {\n try {\n let allAccounts = [];\n let pageStart = 1;\n let pageToken = null;\n let totalPages = 0;\n\n do {\n // Build URL with pagination parameters\n let url = 'https://api.bcb.bm/v1/accounts';\n const params = new URLSearchParams();\n \n if (pageStart === 1) {\n // First request: optionally specify pageSize\n params.append('pageSize', '100');\n } else {\n // Subsequent requests: use pageToken and pageStart\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n if (params.toString()) {\n url += '?' + params.toString();\n }\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log(`Page ${pageStart} data:`, data);\n\n // Store pagination info from first request\n if (pageStart === 1 && data.meta && data.meta.pagination) {\n pageToken = data.meta.pagination.page_token;\n totalPages = Math.ceil(data.meta.pagination.total_size / data.meta.pagination.page_size);\n console.log(`Total pages: ${totalPages}, Page token: ${pageToken}`);\n }\n\n // Collect accounts from this page\n if (data.data && data.data.length > 0) {\n allAccounts.push(...data.data);\n console.log(`Collected ${data.data.length} accounts from page ${pageStart}`);\n }\n\n pageStart++;\n } while (pageStart <= totalPages);\n\n console.log(`Total accounts collected: ${allAccounts.length}`);\n\n // Process all collected accounts\n allAccounts.forEach((account, index) => {\n console.log(`Account ${index + 1}: ${account.number}`);\n console.log(`Balance: ${account.balance.amount} ${account.balance.currency}`);\n });\n\n return allAccounts;\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n throw error;\n }\n}\n\n// Function to get a specific page of accounts\nasync function getAccountsPage(pageStart, pageToken = null) {\n try {\n // Build URL\n let url = 'https://api.bcb.bm/v1/accounts';\n const params = new URLSearchParams();\n \n if (pageStart === 1) {\n // First request: optionally specify pageSize\n params.append('pageSize', '100');\n } else {\n // Subsequent requests: use pageToken and pageStart\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n if (params.toString()) {\n url += '?' + params.toString();\n }\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log('Accounts page:', data);\n return data;\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n throw error;\n }\n}\n\n// Example usage:\ngetAllAccountsPaginated(); // Retrieves all accounts across multiple pages\n// OR\ngetAccountsPage(1).then(firstPage => {\n console.log('First page:', firstPage);\n // Use firstPage.meta.pagination.page_token for subsequent requests\n});\n```\n\n**Required Permission:** `get-all-accounts`\n\nThis endpoint requires the permission claim `get-all-accounts` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Accounts_GetAll", "parameters": [ { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 1 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 2 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 3 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfAccountOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 2, "pageToken": "202407250072428721.02,99", "totalSize": 955, "pageSize": 99 } }, "data": [ { "accountId": 12345678901, "cif": 3000032, "currency": "USD", "accountSubType": "CURRENT.ACCOUNTS", "accountNumber": 1000078766, "status": "ACTIVE", "availableBalance": { "currency": "USD", "amount": 1000 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "John Doe", "accountHolderType": "Primary" }, { "displayName": "Jane Doe", "accountHolderType": "Joint" } ], "accountAttributes": [ { "name": "OPEN_DATE", "value": "2023-01-01" }, { "name": "STATUS", "value": "ACTIVE" }, { "name": "ACCOUNT_TYPE", "value": "CURRENT.ACCOUNTS" } ] }, { "accountId": 98765432109, "cif": 3000033, "currency": "EUR", "accountSubType": "SAVINGS.ACCOUNTS", "accountNumber": 2000087654, "status": "INACTIVE", "availableBalance": { "currency": "EUR", "amount": 500 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "Alice Smith", "accountHolderType": "Primary" } ], "accountAttributes": [ { "name": "OPEN_DATE", "value": "2022-06-15" }, { "name": "STATUS", "value": "INACTIVE" }, { "name": "ACCOUNT_TYPE", "value": "SAVINGS.ACCOUNTS" } ] } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_account_id\",\"data_0_cif\",\"data_0_account_number\",\"data_0_status\",\"data_0_currency\",\"data_0_available_balance_currency\",\"data_0_available_balance_amount\",\"data_0_account_sub_type\",\"data_0_owners_0_display_name\",\"data_0_owners_0_account_holder_type\",\"data_0_owners_1_display_name\",\"data_0_owners_1_account_holder_type\",\"data_0_account_attributes_0_name\",\"data_0_account_attributes_0_value\",\"data_0_account_attributes_1_name\",\"data_0_account_attributes_1_value\",\"data_0_account_attributes_2_name\",\"data_0_account_attributes_2_value\",\"data_1_account_id\",\"data_1_cif\",\"data_1_account_number\",\"data_1_status\",\"data_1_currency\",\"data_1_available_balance_currency\",\"data_1_available_balance_amount\",\"data_1_account_sub_type\",\"data_1_owners_0_display_name\",\"data_1_owners_0_account_holder_type\",\"data_1_account_attributes_0_name\",\"data_1_account_attributes_0_value\",\"data_1_account_attributes_1_name\",\"data_1_account_attributes_1_value\",\"data_1_account_attributes_2_name\",\"data_1_account_attributes_2_value\"", "\"2\",\"202407250072428721.02,99\",\"955\",\"99\",\"12345678901\",\"3000032\",\"1000078766\",\"ACTIVE\",\"USD\",\"USD\",\"1000.00\",\"CURRENT.ACCOUNTS\",\"John Doe\",\"Primary\",\"Jane Doe\",\"Joint\",\"OPEN_DATE\",\"2023-01-01\",\"STATUS\",\"ACTIVE\",\"ACCOUNT_TYPE\",\"CURRENT.ACCOUNTS\",\"98765432109\",\"3000033\",\"2000087654\",\"INACTIVE\",\"EUR\",\"EUR\",\"500.00\",\"SAVINGS.ACCOUNTS\",\"Alice Smith\",\"Primary\",\"OPEN_DATE\",\"2022-06-15\",\"STATUS\",\"INACTIVE\",\"ACCOUNT_TYPE\",\"SAVINGS.ACCOUNTS\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - No accounts were found for the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-all-accounts" ] }, { "Authorization": [] } ] } }, "/v1/payments/ach-local": { "post": { "tags": [ "Payments" ], "summary": "ACH Local Payment", "description": "Initiates a domestic same-currency bank transfer over the ACH clearing network. The request carries debtor account, instructed amount, debit currency, creditor account + bank reference, and 1–2 lines of remittance information. JSON and CSV response formats are supported via the `Accept` header.\n \n### Supported Currencies\nOnly **USD** and **BMD** are accepted. `debitCurrency` and `instructedAmount.currency` must be identical - cross-currency is not supported on this endpoint.\n \n### Settlement and Cut-Off\nTransfers settle **same-day** when submitted before **3:15 PM local AST**; later submissions are queued for the next business day. The value/effective date in the response reflects the settlement date.\n \n### Creditor Bank Reference\nProvide `creditorBank` with the destination bank `bankCode` and `currency`.\nThe API validates this combination against the configured bank reference lookup.\nIf the `bankCode` and `currency` combination is not found, the API returns `400 Bad Request`\nwith error code `BANK_REFERENCE_NOT_FOUND`.\n \nThe ACH local bank reference lookup contains the following values:\n \n| Bank Code | Currency | Bank Name |\n|-----------|----------|-----------|\n| `BUTTERFIELD` | `BMD` | Bank of N.T. Butterfield & Sons |\n| `HSBC` | `BMD` | HSBC Bermuda |\n| `CLARIEN` | `BMD` | Clarien Bank Bermuda |\n| `BUTTERFIELD` | `USD` | Bank of N.T. Butterfield & Sons |\n| `HSBC` | `USD` | HSBC Bermuda |\n| `CLARIEN` | `USD` | Clarien Bank Bermuda |\n \n### Request basics\n- **Endpoint:** `POST https://api.bcb.bm/v1/payments/ach-local`\n- **Authorization:** `Bearer {token}` (required).\n- **Accept:** `application/json` (default) or `text/csv`.\n- **Idempotency-Key:** optional UUID v4 header (≤ 255 chars). See below.\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header. When supplied, the server caches the **successful** response and replays it on repeat calls.\n- If no idempotency key is provided, the request is processed normally (duplicates are possible).\n- If a valid UUID key is supplied, the system stores the response of the first `2xx` outcome and replays it on subsequent calls with the same key.\n- **TTL (cache lifetime):** the stored response is retained for a limited window (currently on the order of one hour). After expiry the same key is treated as a new request - but `instructionIdentification` deduplication still applies for **24 hours**. Plan client-side retries to land inside the cache window.\n- **Scope:** keys are partitioned by client/user, HTTP method, and request path. The same key on `/payments/ach-local` and `/payments/swift` is **not** shared - each endpoint has its own cache slot.\n- **Concurrency:** if a second request with the same key arrives while the first is still in flight, the second is rejected with `409 Conflict` and message `\"Request is already being processed.\"` Wait and retry.\n- **Body mismatch:** request bodies are **not** compared on replay. If you reuse a key with a different body, the original cached response is returned - the new body is ignored. Mint a fresh key for any logically different request.\n- **Non-2xx responses are not cached.** A `4xx` validation failure or `5xx` server error can be retried with the same key and will execute again.\n \n### Deduplication\nA separate, business-level guard on the `instructionIdentification` field, applied independently of the `Idempotency-Key` header:\n- Reusing an `instructionIdentification` for an active ACH local payment is rejected with `409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID`.\n- Use a fresh `instructionIdentification` for each new payment intent. Reuse it (with the same `Idempotency-Key`) only when retrying the exact same payment.\n- The deduplication window is currently configured as **24 hours** from the first accepted request.\n \n### How `Idempotency-Key` and `instructionIdentification` combine\nThey are independent mechanisms with different purposes.\n- `Idempotency-Key` (header) is a **transport-level retry token**. It lets you safely retry the same HTTP call and get the original response replayed.\n- `instructionIdentification` (body) is the **business identifier of the payment**. It is persisted on the payment record and forwarded downstream. To prevent the same payment intent from being submitted twice, a value that is already in flight or recently accepted is rejected with `409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID` (window: 24 hours).\n \n| `Idempotency-Key` | `instructionIdentification` | Behaviour |\n|---|---|---|\n| no | no | No protection. Each call creates a new payment. |\n| **yes** | no | HTTP retries of the same call replay the original response. A new `Idempotency-Key` creates a new payment. |\n| no | **yes** | First call is processed normally. Reusing the same business identifier within 24 hours is rejected with `409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID`. The original success response is **not** replayed - record it client-side. |\n| **yes** | **yes** | Recommended. HTTP retries of the same call replay the original response. A new `Idempotency-Key` reusing an in-flight `instructionIdentification` is rejected with `409`. |\n \n### Resilience: classifying responses\nThe dedupe and idempotency layers together cover three distinct failure modes. The status code tells you what to do next:\n \n- `503 DEDUPE_LOCK_UNAVAILABLE` - the duplicate-check store could not acquire its lock for `instructionIdentification`. The payment was **not** submitted to core banking. Safe to retry after a short backoff with the **same** `instructionIdentification` (and the **same** `Idempotency-Key`, if you used one). This is **not** \"a duplicate was detected\" - it is \"we could not verify uniqueness right now.\"\n- `409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID` - this `instructionIdentification` was already accepted within the 24-hour window. Do **not** retry the `POST`; query payment status to reconcile.\n- `5xx`, connection timeout, or no response - outcome unknown. Retry with the **same** `Idempotency-Key` and **same** `instructionIdentification`. The server will either replay the original `201` (if the first attempt landed) or return `409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID` (also indicating the first attempt landed).\n \nDecision tree in pseudocode:\n \n```javascript\nasync function submitAchLocalPayment(paymentRequest, idempotencyKey) {\n for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {\n const res = await postPayment(paymentRequest, idempotencyKey);\n \n switch (res.status) {\n case 201:\n return res.body; // success - persist paymentId against instructionIdentification\n \n case 409: // ACH_LOCAL_DUPLICATE_INSTRUCTION_ID - intent already submitted\n // Do NOT retry with a new instructionId. Reconcile via status lookup.\n return await reconcileViaStatusLookup(paymentRequest.instructionIdentification);\n \n case 503: // DEDUPE_LOCK_UNAVAILABLE - NOT submitted, safe to retry as-is\n case 502: case 504: // transient gateway\n await backoff(attempt); continue;\n \n default:\n if (isNetworkError(res)) { // unknown outcome - retry SAME key + SAME instructionId\n await backoff(attempt); continue;\n }\n throw res; // 4xx other - fix request, mint NEW instructionId before retrying\n }\n }\n}\n```\n \n### When to rotate `instructionIdentification`\n \n```javascript\n// NEW payment intent (user clicks \"Send\" again, new business event)\nconst intent = {\n instructionIdentification: uuid(),\n idempotencyKey: uuid()\n};\n \n// RETRY of the SAME intent (5xx, 503 DEDUPE_LOCK_UNAVAILABLE, timeout)\n// -> keep BOTH values stable; the server will replay or short-circuit safely\nretry(intent);\n \n// After 409 ACH_LOCAL_DUPLICATE_INSTRUCTION_ID\n// -> do NOT POST again; query status to reconcile\nawait getPaymentStatus(intent.instructionIdentification);\n```\n \n### `Idempotency-Key` lifecycle (client-side checklist)\n- Mint the key **before** the HTTP call and persist it alongside the payment intent so a process restart or retry can still find it.\n- Reuse it for every retry of the same intent; treat it as \"spent\" only after a terminal (`2xx` or non-retryable `4xx`) response.\n- Plan retries to land inside the cache window (~1 hour). Beyond that, `instructionIdentification` (24 h) is your remaining guard.\n \n### Validation Rules\n| Field | Constraint |\n|-------|-----------|\n| `instructionIdentification` | Optional, max 16 characters |\n| `debtorAccount.identification` | Required, max 36 characters |\n| `debitCurrency` | Required, exactly 3 characters, USD or BMD only |\n| `instructedAmount.amount` | Required, max 18 characters, valid decimal (up to 2 decimal places) |\n| `instructedAmount.currency` | Required, exactly 3 characters, USD or BMD only, must equal `debitCurrency` |\n| `creditorAccount.identification` | Required, max 17 characters |\n| `creditorAccount.name` | Required, max 22 characters |\n| `creditorBank.bankCode` | Required, 1-100 characters (see Creditor Bank Reference below) |\n| `creditorBank.currency` | Required, exactly 3 characters, must match `debitCurrency` |\n| `remittanceInformation` | Required, 1–2 non-empty lines, each max 35 characters |\n \n### Minimal Request Example\n \n```javascript\nconst res = await fetch('https://api.bcb.bm/v1/payments/ach-local', {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${token}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': idempotencyKey, // UUID v4, per payment intent\n },\n body: JSON.stringify(paymentRequest), // shape: see request schema below\n});\n```\n \nThe full request and response schemas, including field types and a worked example, are rendered below from the API contract.\n\n**Required Permission:** `payment-ach`\n\nThis endpoint requires the permission claim `payment-ach` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "AchLocalPayments_Post", "requestBody": { "x-name": "request", "description": "The ACH local payment request containing all necessary payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchLocalPaymentRequest" }, "example": { "instructionIdentification": "REF-123456", "debtorAccount": { "identification": 123456789012 }, "debitCurrency": "USD", "instructedAmount": { "currency": "USD", "amount": 1500 }, "creditorAccount": { "identification": 9876543210123, "name": "John Doe", "additionalInformation": null }, "creditorBank": { "bankCode": "HSBC", "currency": "USD" }, "remittanceInformation": [ "Invoice 2026-0001" ] } } }, "x-position": 1 }, "responses": { "201": { "description": "Created - The ACH local payment was successfully processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "examples": { "Json": { "value": { "id": "PAY-8F2A1C", "status": "success", "transactionStatus": "accepted", "uniqueIdentifier": "20260311-ACH-000123", "details": { "extReference": "REF-123456", "instructedAmount": { "currency": "USD", "amount": 1500 }, "debtorAccount": { "schemeName": "AccountNumber", "identification": 123456789012, "currency": "" }, "beneficiaryAccount": { "schemeName": "AccountNumber", "identification": 9876543210123, "currency": "" }, "creditorAccount": { "schemeName": "AccountNumber", "identification": 9876543210123, "currency": "" }, "settlementDetails": { "amountCredited": { "currency": "USD", "amount": 1500 }, "amountDebited": { "currency": "USD", "amount": 1500 }, "valueDate": "2026-03-11", "recordStatus": "" }, "chargeDetails": { "chargesType": "", "chargeAmount": { "currency": "USD", "amount": 0 }, "chargeAccount": { "schemeName": null, "identification": 123456789012, "currency": "" }, "chargeAnalysis": null }, "remittanceInformation": [ { "unstructured": "Invoice 2026-0001" } ], "beneficiary": { "identification": 9876543210123, "name": "John Doe", "additionalInformation": null }, "beneficiaryAgent": { "identification": 21000021, "name": null, "additionalInformation": null }, "intermediaryAgent": null }, "linkedActivities": [] } }, "Csv": { "value": [ "\"id\",\"status\",\"transaction_status\",\"unique_identifier\",\"details_ext_reference\",\"details_instructed_amount_currency\",\"details_instructed_amount_amount\",\"details_debtor_account_scheme_name\",\"details_debtor_account_identification\",\"details_debtor_account_name\",\"details_beneficiary_account_scheme_name\",\"details_beneficiary_account_identification\",\"details_beneficiary_account_name\",\"details_creditor_account_scheme_name\",\"details_creditor_account_identification\",\"details_creditor_account_name\",\"details_settlement_details_amount_credited_currency\",\"details_settlement_details_amount_credited_amount\",\"details_settlement_details_amount_debited_currency\",\"details_settlement_details_amount_debited_amount\",\"details_settlement_details_value_date\",\"details_settlement_details_record_status\",\"details_charge_details_charges_type\",\"details_charge_details_charge_amount_currency\",\"details_charge_details_charge_amount_amount\",\"details_charge_details_charge_account_identification\",\"details_charge_details_charge_account_name\",\"details_remittance_information_0_unstructured\",\"details_beneficiary_identification\",\"details_beneficiary_name\",\"details_beneficiary_agent_identification\"", "\"PAY-8F2A1C\",\"success\",\"accepted\",\"20260311-ACH-000123\",\"REF-123456\",\"USD\",\"1500.00\",\"AccountNumber\",\"123456789012\",\"\",\"AccountNumber\",\"9876543210123\",\"\",\"AccountNumber\",\"9876543210123\",\"\",\"USD\",\"1500.00\",\"USD\",\"1500.00\",\"2026-03-11\",\"\",\"\",\"USD\",\"0.00\",\"123456789012\",\"\",\"Invoice 2026-0001\",\"9876543210123\",\"John Doe\",\"021000021\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - The instructionIdentification has already been submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable - The duplicate check lock is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "payment-ach" ] }, { "Authorization": [] } ] } }, "/v1/credentials": { "post": { "tags": [ "Credentials" ], "summary": "Create new API client credentials", "description": "Creates new API client credentials based on an existing client's permissions and configuration.\nThe new credentials will inherit the same roles and permissions as the specified existing client.\n\n **Key Features**:\n- A new client ID (GUID) is generated automatically\n- A cryptographically secure password (22-30 characters) is generated automatically\n- A cryptographically secure message signing secret (32 bytes) is generated automatically for HMAC-SHA256 signing\n- All roles and direct permissions are copied from the existing client\n- The new credentials can have different IP restrictions if specified\n\n**Password Security:**\n- Generated passwords are 22-30 characters long for enhanced security\n- Include uppercase letters, lowercase letters, digits, and special characters\n- The generated password is only returned once in the response\n\n**Message Signing Secret:**\n- A 32-byte (256-bit) random key (Base64 encoded) is generated for signing API requests\n- This key will be used by the system to sign callback responses - notifications, background job webhooks\n- The secret is returned only once in the response\n\n**Access Control:**\n- You can only create credentials based on clients you have access to\n- New client inherits exact role and permission set from source client\n- IP restrictions can be customized or inherited from source client\n \n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/credentials\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function createCredentials() {\n try {\n const token = localStorage.getItem('jwt'); // Your JWT token from authentication\n \n const response = await fetch('https://api.bcb.bm/v1/credentials', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n },\n body: JSON.stringify({\n allowedIps: '192.168.1.100,10.0.0.0/24' // Optional: specify IP restrictions, or omit/'*' for all IPs\n })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const data = await response.json();\n console.log('New credentials created:', {\n clientId: data.clientId,\n clientSecret: data.clientSecret, // Save this securely - only shown once!\n messageSigningSecret: data.messageSigningSecret, // Save this securely - only shown once!\n isActive: data.isActive,\n allowedIps: data.allowedIps\n });\n \n // Store new credentials securely\n // WARNING: This is just an example - use secure storage in production\n localStorage.setItem('newClientId', data.clientId);\n localStorage.setItem('newClientSecret', data.clientSecret);\n localStorage.setItem('newMessageSigningSecret', data.messageSigningSecret);\n \n } catch (error) {\n console.error('Error creating credentials:', error);\n }\n}\n\ncreateCredentials();\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_Post", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientCredentialsCreateRequest" }, "example": { "allowedIps": "192.168.1.1,192.168.1.2" } } }, "x-position": 1 }, "responses": { "201": { "description": "Credentials created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientCredentialsCreateResponse" }, "example": { "clientId": "a1b2c3d4-e5f6-4789-b012-3456789abcde", "clientSecret": "Abc123XyzP9mN7kLAbc123XyzP95", "isActive": true, "allowedIps": "192.168.1.1,192.168.1.2", "messageSigningSecret": "HtYp2oJm5DwQ1xL8bSeRgUkN4vZc3PhYtLwSxV2N9Cs=" } } } }, "400": { "description": "Invalid request data or validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient permissions or unauthorized access to the existing client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request is already being processed (idempotency conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}": { "patch": { "tags": [ "Credentials" ], "summary": "Rotate the client secret for an existing API client", "description": "Rotates (changes) the client secret AND the message signing secret for an existing API client while preserving all other settings.\nThis is useful for credential rotation policies, security incident response, or regular maintenance.\n\n **Key Features**:\n- A new cryptographically secure password (22-30 characters) is generated automatically\n- A new cryptographically secure message signing secret (32 bytes) is generated automatically\n- The existing client's secrets are immediately replaced with the new ones\n- All roles, permissions, and other settings remain unchanged\n- The old secrets become invalid immediately after successful rotation\n- The new secrets are returned in the response (only shown once)\n\n**Password Security:**\n- Generated passwords are 22-30 characters long for enhanced security\n- Include uppercase letters, lowercase letters, digits, and special characters\n- The new password is only returned once in the response\n\n**Access Control:**\n- You can only rotate secrets for clients you have access to\n- The rotated client retains all existing roles and permissions\n\n**Important Security Notes:**\n- The old secret stops working immediately after successful rotation\n- Any applications using the old secret will need to be updated with the new secret\n- Store the new secret securely as it won't be shown again\n \n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/credentials/{clientId}\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function rotateClientSecret(clientId) {\n try {\n const token = localStorage.getItem('jwt'); // Your JWT token from authentication\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}`, {\n method: 'PATCH',\n headers: {\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const data = await response.json();\n console.log('Client secret rotated successfully:', {\n clientId: data.clientId,\n newClientSecret: data.clientSecret, // Save this securely - only shown once!\n newMessageSigningSecret: data.messageSigningSecret, // Save this securely - only shown once!\n isActive: data.isActive,\n allowedIps: data.allowedIps\n });\n \n // Update stored credentials securely\n // WARNING: This is just an example - use secure storage in production\n localStorage.setItem('clientSecret', data.clientSecret);\n localStorage.setItem('messageSigningSecret', data.messageSigningSecret);\n \n // Important: Update any applications using the old secret\n console.warn('IMPORTANT: Update all applications using this client with the new secret!');\n \n } catch (error) {\n console.error('Error rotating client secret:', error);\n }\n}\n\n// Example usage\nrotateClientSecret('12345678-1234-1234-1234-123456789abc');\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_Patch", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "The unique identifier of the client whose secret should be rotated", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "Secret rotated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientCredentialsCreateResponse" }, "examples": { "Example 1": { "value": { "clientId": "a1b2c3d4-e5f6-4789-b012-3456789abcde", "clientSecret": "Abc123XyzP9mN7kLAbc123XyzP95", "isActive": true, "allowedIps": "192.168.1.1,192.168.1.2", "messageSigningSecret": "HtYp2oJm5DwQ1xL8bSeRgUkN4vZc3PhYtLwSxV2N9Cs=" } }, "Example 2": { "value": { "clientId": "a1b2c3d4-e5f6-7890-abcd-123456789def", "clientSecret": "", "isActive": false, "allowedIps": "192.168.1.100,10.0.0.0/24", "messageSigningSecret": null } } } } } }, "400": { "description": "Invalid request or client validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient permissions or unauthorized access to the client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] }, "delete": { "tags": [ "Credentials" ], "summary": "Disable an existing API client", "description": "Disables an existing API client, immediately preventing any further authentication using that client ID and secret.\nThis operation also revokes all active tokens associated with the client.\n\n **Key Features**:\n- Disables the credentials instantly – all authentication requests will fail after this operation\n- Revokes all active tokens immediately for enhanced security\n- Idempotent: calling the endpoint on an already inactive client returns success\n\n**Security Considerations:**\n- All active tokens are immediately invalidated and removed from the system\n- Any applications using the disabled client will lose access immediately\n- The client record is preserved for audit and compliance purposes\n\n**Access Control:**\n- You can only disable clients that belong to your organization\n \n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/credentials/{clientId}\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function disableClient(clientId) {\n try {\n const token = localStorage.getItem('jwt'); // Your JWT token from authentication\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}`, {\n method: 'DELETE',\n headers: {\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const data = await response.json();\n console.log('Client disabled successfully:', {\n clientId: data.clientId,\n isActive: data.isActive, // Should be false\n allowedIps: data.allowedIps\n });\n \n // Important: Update any applications that were using this client\n console.warn('IMPORTANT: All applications using this client will lose access immediately!');\n \n } catch (error) {\n console.error('Error disabling client:', error);\n }\n}\n\n// Example usage\ndisableClient('12345678-1234-1234-1234-123456789abc');\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_Delete", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "The unique identifier of the client to disable", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "Client disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientCredentialsCreateResponse" }, "example": { "clientId": "a1b2c3d4-e5f6-7890-abcd-123456789def", "clientSecret": "", "isActive": false, "allowedIps": "192.168.1.100,10.0.0.0/24", "messageSigningSecret": null } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient permissions or unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}/permissions": { "get": { "tags": [ "Credentials" ], "summary": "Get permissions for an existing API client", "description": "Retrieves all permissions assigned to the specified API client. The response provides a comprehensive view of\nwhat features the client can access.\n\n **Key Features**:\n- Returns all permissions assigned to the client\n- Results are sorted alphabetically by permission key for consistent ordering\n- Includes human-readable descriptions for each permission\n\n**Access Control:**\n- You can only view permissions for clients that belong to your organization\n\n**Use Cases:**\n- Audit client access capabilities\n- Troubleshoot authentication and authorization issues\n- Verify client configuration during security reviews\n- Document client permissions for compliance purposes\n \n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/credentials/{clientId}/permissions\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function getClientPermissions(clientId) {\n try {\n const token = localStorage.getItem('jwt'); // Your JWT token from authentication\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/permissions`, {\n method: 'GET',\n headers: {\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const permissions = await response.json();\n console.log('Client permissions:', permissions);\n \n // Display permissions in a user-friendly format\n permissions.forEach(permission => {\n console.log(`- ${permission.key}: ${permission.description || 'No description available'}`);\n });\n \n return permissions;\n \n } catch (error) {\n console.error('Error retrieving client permissions:', error);\n }\n}\n\n// Example usage\ngetClientPermissions('12345678-1234-1234-1234-123456789abc');\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_GetPermissions", "parameters": [ { "name": "clientId", "in": "path", "required": true, "description": "The unique identifier of the client to retrieve permissions for", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "Permissions retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionResponse" } }, "example": [ { "key": "get-account", "description": "Allows access to retrieve individual account information" }, { "key": "get-all-accounts", "description": "Allows access to retrieve all accounts for a customer" }, { "key": "get-fx-quote", "description": "Allows access to foreign exchange quote endpoints" }, { "key": "get-transactions", "description": "Allows access to transaction history endpoints" }, { "key": "get-payment-status", "description": "Allows access to payment status tracking endpoints" }, { "key": "make-internal-transfer", "description": "Allows execution of internal transfers between accounts" }, { "key": "make-payment-swift", "description": "Allows execution of SWIFT payment transactions" }, { "key": "manage-credentials", "description": "Allows management of API client credentials and permissions" } ] } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient permissions or unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}/keys": { "get": { "tags": [ "Credentials" ], "summary": "Get public key metadata", "description": "Returns metadata for the partner RSA keys:\n- Indicates whether primary/secondary keys exist\n- Provides short fingerprints, algorithms, and last-updated timestamps\n- Shows verification status of the secondary key (after proof-of-possession)\n \n### Sample Request in JavaScript:\n\n```javascript\nasync function getKeyMetadata(clientId) {\n try {\n const token = localStorage.getItem('jwt');\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/keys`, {\n method: 'GET',\n headers: {\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const metadata = await response.json();\n console.log('Key metadata:', {\n hasPrimaryKey: metadata.hasPrimaryKey,\n hasSecondaryKey: metadata.hasSecondaryKey,\n primaryKeyFingerprint: metadata.primaryKeyFingerprint,\n secondaryKeyFingerprint: metadata.secondaryKeyFingerprint,\n secondaryKeyVerified: metadata.secondaryKeyVerified\n });\n \n return metadata;\n } catch (error) {\n console.error('Error getting key metadata:', error);\n }\n}\n\ngetKeyMetadata('12345678-1234-1234-1234-123456789abc');\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_GetKeys", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyMetadataResponse" }, "example": { "hasPrimaryKey": true, "hasSecondaryKey": true, "primaryKeyFingerprint": "A1B2C3D4E5F60708", "secondaryKeyFingerprint": "0F1E2D3C4B5A6978", "primaryKeyAlgorithm": "RSA-3072", "secondaryKeyAlgorithm": "RSA-3072", "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z", "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z", "secondaryKeyVerified": false, "secondaryKeyVerifiedUtc": null } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}/keys/secondary": { "put": { "tags": [ "Credentials" ], "summary": "Upload secondary public key", "description": "Upload a new RSA public key (PEM format) into the secondary slot to stage rotation.\n\n**Key Features:**\n- Accepts RSA public keys (2048-bit minimum recommended)\n- Resets verification status when a new key is uploaded\n- Secondary key becomes active for signature verification alongside primary\n\n**Rotation flow:**\n1. Upload secondary key (this endpoint)\n2. POST challenge → sign locally → POST verify\n3. POST promote (makes secondary the primary)\n4. (Optional) DELETE secondary if aborting\n \n### Sample Request in JavaScript:\n\n```javascript\nasync function uploadSecondaryKey(clientId, publicKeyPem) {\n try {\n const token = localStorage.getItem('jwt');\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/keys/secondary`, {\n method: 'PUT',\n headers: {\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n },\n body: JSON.stringify({\n publicKeyPem: publicKeyPem\n })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const metadata = await response.json();\n console.log('Secondary key uploaded:', {\n hasSecondaryKey: metadata.hasSecondaryKey,\n secondaryKeyFingerprint: metadata.secondaryKeyFingerprint,\n secondaryKeyVerified: metadata.secondaryKeyVerified // Will be false until verified\n });\n \n return metadata;\n } catch (error) {\n console.error('Error uploading secondary key:', error);\n }\n}\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_PutSecondaryKey", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "x-position": 1, "example": { "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAxq1RqYIgYOb7H1uxC5mS\nM8s2Dhrz6sGJYvRq9A0KIf8v0pqm+9B6ZcM+3PEm2rUp7N0CYaUtR32W0bz1gM/b\nd3BFPFdcTnMjYwXomfjAZW9XvsC8t7y7mNLgO2cMYk2fT7k6aQp0yrzmmkCudIsc\nq4drqgG/Kxi4SpwYgYYnZ2hEo6VtV5JpR6TfyxwTXXxoH1WPr5oH7D8fFvG3a7dD\nRZl/vM8UzA2yN6lcn/zoVPQ7xY9qaTYjz4cmOcuQKBgQCQKBgQCQKBgQCQKBgQ\n-----END PUBLIC KEY-----" } } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientUploadRequest" }, "example": { "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAxq1RqYIgYOb7H1uxC5mS\nM8s2Dhrz6sGJYvRq9A0KIf8v0pqm+9B6ZcM+3PEm2rUp7N0CYaUtR32W0bz1gM/b\nd3BFPFdcTnMjYwXomfjAZW9XvsC8t7y7mNLgO2cMYk2fT7k6aQp0yrzmmkCudIsc\nq4drqgG/Kxi4SpwYgYYnZ2hEo6VtV5JpR6TfyxwTXXxoH1WPr5oH7D8fFvG3a7dD\nRZl/vM8UzA2yN6lcn/zoVPQ7xY9qaTYjz4cmOcuQKBgQCQKBgQCQKBgQCQKBgQ\n-----END PUBLIC KEY-----" } } }, "required": true, "x-position": 2 }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyMetadataResponse" }, "example": { "hasPrimaryKey": true, "hasSecondaryKey": true, "primaryKeyFingerprint": "A1B2C3D4E5F60708", "secondaryKeyFingerprint": "0F1E2D3C4B5A6978", "primaryKeyAlgorithm": "RSA-3072", "secondaryKeyAlgorithm": "RSA-3072", "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z", "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z", "secondaryKeyVerified": false, "secondaryKeyVerifiedUtc": null } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] }, "delete": { "tags": [ "Credentials" ], "summary": "Delete secondary public key", "description": "Removes the secondary key from the staging slot. Useful for aborting rotation or correcting mistakes before promotion.\n\n**Key Features:**\n- Clears the secondary key slot\n- Idempotent: returns success even if secondary key doesn't exist\n- Safe for retries\n \n### Sample Request in JavaScript:\n\n```javascript\nasync function deleteSecondaryKey(clientId) {\n try {\n const token = localStorage.getItem('jwt');\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/keys/secondary`, {\n method: 'DELETE',\n headers: {\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const metadata = await response.json();\n console.log('Secondary key deleted:', {\n hasSecondaryKey: metadata.hasSecondaryKey // Now false\n });\n \n return metadata;\n } catch (error) {\n console.error('Error deleting secondary key:', error);\n }\n}\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_DeleteSecondaryKey", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyMetadataResponse" }, "example": { "hasPrimaryKey": true, "hasSecondaryKey": true, "primaryKeyFingerprint": "A1B2C3D4E5F60708", "secondaryKeyFingerprint": "0F1E2D3C4B5A6978", "primaryKeyAlgorithm": "RSA-3072", "secondaryKeyAlgorithm": "RSA-3072", "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z", "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z", "secondaryKeyVerified": false, "secondaryKeyVerifiedUtc": null } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}/keys/promote": { "post": { "tags": [ "Credentials" ], "summary": "Promote secondary key to primary", "description": "Promotes the current secondary key to primary and clears the secondary slot.\nUse after validating the new key (optionally after challenge/verify).\n\n**Key Features:**\n- Makes the secondary key the new primary\n- Clears the secondary slot\n- Previous primary key is replaced\n \n### Sample Request in JavaScript:\n\n```javascript\nasync function promoteSecondaryKey(clientId) {\n try {\n const token = localStorage.getItem('jwt');\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/keys/promote`, {\n method: 'POST',\n headers: {\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const metadata = await response.json();\n console.log('Secondary key promoted to primary:', {\n hasPrimaryKey: metadata.hasPrimaryKey,\n hasSecondaryKey: metadata.hasSecondaryKey, // Now false\n primaryKeyFingerprint: metadata.primaryKeyFingerprint // Updated\n });\n \n return metadata;\n } catch (error) {\n console.error('Error promoting secondary key:', error);\n }\n}\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_PromoteSecondaryKey", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyMetadataResponse" }, "example": { "hasPrimaryKey": true, "hasSecondaryKey": true, "primaryKeyFingerprint": "A1B2C3D4E5F60708", "secondaryKeyFingerprint": "0F1E2D3C4B5A6978", "primaryKeyAlgorithm": "RSA-3072", "secondaryKeyAlgorithm": "RSA-3072", "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z", "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z", "secondaryKeyVerified": false, "secondaryKeyVerifiedUtc": null } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}/keys/secondary/challenge": { "post": { "tags": [ "Credentials" ], "summary": "Generate secondary key challenge", "description": "Returns a time-limited challenge (Base64) that must be signed with the private key\ncorresponding to the secondary public key. Proves ownership before promotion.\n \n**Challenge Format:**\n- Base64 encoding of: `{clientId}.{nonce}.{expiry}.{keyFingerprint}`\n- Sign the decoded raw bytes of this challenge (not the Base64 literal).\n- Valid for ~5 minutes\n- Bound to the current secondary key (fingerprint included)\n \n### Sample Request in JavaScript:\n\n```javascript\nasync function requestChallenge(clientId) {\n try {\n const token = localStorage.getItem('jwt');\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/keys/secondary/challenge`, {\n method: 'POST',\n headers: {\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const { challenge, expiresUtc } = await response.json();\n console.log('Challenge received:', { challenge, expiresUtc });\n \n // Sign the challenge with your private key\n const crypto = require('crypto');\n const privateKeyPem = process.env.PRIVATE_KEY;\n \n const sign = crypto.createSign('RSA-SHA256');\n sign.update(Buffer.from(challenge, 'base64'));\n const signature = sign.sign({\n key: privateKeyPem,\n padding: crypto.constants.RSA_PKCS1_PSS_PADDING,\n saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST\n }, 'base64');\n \n console.log('Signature created, ready for verification');\n return { challenge, signature };\n \n } catch (error) {\n console.error('Error requesting challenge:', error);\n }\n}\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_RequestSecondaryKeyChallenge", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyChallengeResponse" }, "example": { "challenge": "Y2xpZW50SWQubm9uY2UuMTcwMDAwMDAwMC5BMTIzRjQ1RjY3OA==", "expiresUtc": "2026-01-15T12:05:00.0000000Z" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/credentials/{clientId}/keys/secondary/verify": { "post": { "tags": [ "Credentials" ], "summary": "Verify secondary key ownership", "description": "Submit the Base64 challenge and its RSA-PSS signature (SHA-256). \nImportant: sign the decoded raw bytes of the challenge, not the Base64 string literal.\nOn success, the secondary key is marked as verified.\n\n**Key Features:**\n- Validates signature using RSA-PSS + SHA-256\n- Checks challenge expiry (5-minute window)\n- Verifies challenge matches current secondary key\n- Sets `secondaryKeyVerified: true` on success\n \n### Sample Request in JavaScript:\n\n```javascript\nasync function verifySecondaryKey(clientId, challenge, signature) {\n try {\n const token = localStorage.getItem('jwt');\n \n const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/keys/secondary/verify`, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Authorization': `Bearer ${token}`\n },\n body: JSON.stringify({\n challenge: challenge,\n signature: signature\n })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const metadata = await response.json();\n \n if (metadata.secondaryKeyVerified) {\n console.log('✓ Secondary key verified successfully!');\n console.log('You can now promote it to primary or test with production traffic.');\n } else {\n console.error('✗ Verification failed - signature did not match');\n }\n \n return metadata;\n } catch (error) {\n console.error('Error verifying secondary key:', error);\n }\n}\n\n// Complete rotation flow example:\n// 1. Upload: await uploadSecondaryKey(clientId, publicKeyPem);\n// 2. Challenge: const { challenge, signature } = await requestChallenge(clientId);\n// 3. Verify: await verifySecondaryKey(clientId, challenge, signature);\n// 4. Promote: await promoteSecondaryKey(clientId);\n```\n\n**Required Permission:** `manage-credentials`\n\nThis endpoint requires the permission claim `manage-credentials` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Credentials_VerifySecondaryKeyChallenge", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" }, "x-position": 1, "example": { "challenge": "Y2xpZW50SWQubm9uY2UuMTcwMDAwMDAwMC5BMTIzRjQ1RjY3OA==", "signature": "MEUCIQC0j7Xf7PqJ8n+q2eVY7k1nqM+UogYNDpFQ2a3E7Xy1zwIgFqYY3d3rVfJq8zlfjtqZ5rXwzBkVxH93+zVTe6y8ygE=" } } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyVerifyRequest" }, "example": { "challenge": "Y2xpZW50SWQubm9uY2UuMTcwMDAwMDAwMC5BMTIzRjQ1RjY3OA==", "signature": "MEUCIQC0j7Xf7PqJ8n+q2eVY7k1nqM+UogYNDpFQ2a3E7Xy1zwIgFqYY3d3rVfJq8zlfjtqZ5rXwzBkVxH93+zVTe6y8ygE=" } } }, "required": true, "x-position": 2 }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientKeyMetadataResponse" }, "example": { "hasPrimaryKey": true, "hasSecondaryKey": true, "primaryKeyFingerprint": "A1B2C3D4E5F60708", "secondaryKeyFingerprint": "0F1E2D3C4B5A6978", "primaryKeyAlgorithm": "RSA-3072", "secondaryKeyAlgorithm": "RSA-3072", "primaryKeyUpdatedUtc": "2026-01-05T12:00:00.0000000Z", "secondaryKeyUpdatedUtc": "2026-01-15T12:00:00.0000000Z", "secondaryKeyVerified": false, "secondaryKeyVerifiedUtc": null } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "manage-credentials" ] }, { "Authorization": [] } ] } }, "/v1/test-deposits/swift/simulate": { "post": { "tags": [ "Testing" ], "summary": "Create a test SWIFT deposit", "description": "Creates a SWIFT deposit in the system using test-environment data and returns the created deposit details.\nThis endpoint is available only in non-production environments and is intended for integration testing,\nvalidation of payload formatting, and pre-production workflow checks.\n \nAlthough the route contains the word `simulate`, the request creates a deposit record in the system.\nIf there is a matching and active deposit notification subscription, the created deposit may also trigger\na deposit notification workflow.\n \n### Content Negotiation\nClients must use the HTTP `Accept` header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\nIf the `Accept` header is omitted, `application/json` is assumed.\n \n### Headers\n- `Authorization: Bearer {token}`\n- `Idempotency-Key: {uuid}` (optional, but recommended for safe retries)\n \n### Validation Rules / Constraints\n- `creditAccountNumber` is required and must not exceed 36 characters.\n- `instructedAmount.currency` is required and must be a 3-letter ISO currency code.\n- `instructedAmount.amount` is required and must be a valid decimal number with up to 2 decimal places.\n- `externalAccountNumber` is required and must not exceed 34 characters.\n- `orderingBank` is required and must not exceed 35 characters.\n- `orderingCustomer` must contain between 1 and 4 lines, each up to 35 characters.\n- `remittanceInformation` must contain at least 1 line, up to 4 lines total, each up to 35 characters.\n \n### Request / Response Signing\nThis endpoint uses request signature verification and response signing.\nClients should sign requests according to their configured signing method, and should verify the signature on the response when response signing is enabled for their API credentials.\n \n### Base URL\nAll API requests use the versioned base URL:\n \n https://api.bcb.bm/v1/test-deposits/swift/simulate\n \n### Sample Request in JavaScript\n \n```javascript\nasync function simulateDeposit(token, idempotencyKey) {\n const response = await fetch('https://api.bcb.bm/v1/test-deposits/swift/simulate', {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${token}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': idempotencyKey\n },\n body: JSON.stringify({\n creditAccountNumber: '1000078766',\n instructedAmount: {\n currency: 'USD',\n amount: '5000.00'\n },\n externalAccountNumber: 'GB29NWBK60161331926819',\n orderingBank: 'DEUTDEFF',\n orderingCustomer: [\n 'Global Trading Corp',\n '100 Finance Street',\n 'London, EC2V 8AB'\n ],\n remittanceInformation: [\n 'Invoice INV-2024-0042',\n 'Q1 advisory fees'\n ]\n })\n });\n \n if (!response.ok) {\n const error = await response.json();\n throw new Error(error.message || 'Deposit simulation failed');\n }\n \n return await response.json();\n}\n```\n\n**Required Permission:** `simulate-deposit`\n\nThis endpoint requires the permission claim `simulate-deposit` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "DepositSimulation_Post", "requestBody": { "x-name": "request", "description": "The SWIFT deposit details to create, including the credit account, instructed amount, ordering party, and remittance information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositSimulationRequest" }, "example": { "creditAccountNumber": 1000078766, "instructedAmount": { "currency": "USD", "amount": 5000 }, "externalAccountNumber": "GB29NWBK60161331926819", "orderingBank": "DEUTDEFF", "orderingCustomer": [ "Global Trading Corp", "100 Finance Street", "London, EC2V 8AB" ], "remittanceInformation": [ "Invoice INV-2024-0042", "Q1 advisory fees" ] } } }, "x-position": 1 }, "responses": { "200": { "description": "OK - The test deposit was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositSimulationResponse" }, "example": { "id": "DEP-SIM-20240321-001", "status": "success", "transactionStatus": "SIMULATED", "uniqueIdentifier": "dep-sim-uid-001", "details": { "amountCredited": { "currency": "USD", "amount": 5000 }, "amountDebited": { "currency": "USD", "amount": 5000 }, "orderingBank": "DEUTDEFF", "debitCurrency": "USD", "creditAccountNumber": 1000078766, "instructedAmount": { "currency": "USD", "amount": 5000 }, "externalAccountNumber": "GB29NWBK60161331926819", "orderingCustomer": [ { "unstructured": "Global Trading Corp" }, { "unstructured": "100 Finance Street" }, { "unstructured": "London, EC2V 8AB" } ], "remittanceInformation": [ { "unstructured": "Invoice INV-2024-0042" }, { "unstructured": "Q1 advisory fees" } ] }, "linkedActivities": [ { "id": "ACT-DEP-SIM-001", "transactionStatus": "SIMULATED", "status": "SUCCESS", "uniqueIdentifier": "act-dep-sim-001", "activityDetails": { "arrangementId": "arr-123456", "activityId": "act-123456", "productId": "swift-deposit-simulation", "currencyId": "USD", "effectiveDate": "2024-03-21" } } ] } } } }, "400": { "description": "Bad Request - The request is invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required or the token is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - The client is authenticated but does not have permission to create test deposits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - The allowed request rate has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred while creating the test deposit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "simulate-deposit" ] }, { "Authorization": [] } ] } }, "/v1/fx-quotes": { "get": { "tags": [ "Fx Quotes" ], "summary": "Get FX Quote", "description": "Retrieves a foreign exchange quote for converting between currencies (for the requested pair and amount).\nThe same quote will be automatically applied by the system to any internal transfer or payment involving two different currencies, provided it is used within its expiry time.\n \n### High-Value Exchange Requests (> 100 000 BMD)\nIf the requested exchange amount exceeds **100 000 BMD**, the system will **not return an automatic quote** in the `GET /v1/fx-quotes` response. \nInstead, the request is routed for **manual processing by our treasury desk** to secure the most competitive rate available.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/fx-quotes\n\n### Validation Rules\n- Currencies must be valid three-letter ISO 4217 codes\n- Unit currency and currency of transfer must be different\n- Instructed amount must be a valid decimal number with up to 2 decimal places\n\n### Sample Request in JavaScript:\n```javascript\n// Get FX quote for converting 100 USD to EUR\nconst getFxQuote = async (unitCurrency, currencyOfTransfer, instructedAmount) => {\n try {\n const response = await fetch(\n 'https://api.bcb.bm/v1/fx-quotes?' + \n new URLSearchParams({\n unitCurrency: unitCurrency,\n currencyOfTransfer: currencyOfTransfer,\n instructedAmount: instructedAmount\n }), {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n // Check if the response is ok (status in the range 200-299)\n if (!response.ok) {\n // Parse error response\n const errorData = await response.json();\n throw new Error(`Error ${response.status}: ${errorData.error} - ${errorData.message}`);\n }\n\n // Parse successful response\n const quote = await response.json();\n \n // Log the complete quote details\n console.log('FX Quote Details:');\n console.log(`Source Currency: ${quote.sourceCurrency.currency}`);\n console.log(`Source Amount: ${quote.sourceCurrency.amount}`);\n console.log(`Target Currency: ${quote.targetCurrency.currency}`);\n console.log(`Target Amount: ${quote.targetCurrency.amount}`);\n console.log(`Exchange Rate: ${quote.exchangeRate}`);\n console.log(`Quote Expires: ${new Date(quote.expiryDateTime).toLocaleString()}`);\n\n // Return the processed quote\n return {\n ...quote,\n // Add formatted values for display\n formattedSourceAmount: new Intl.NumberFormat('en-US', {\n style: 'currency',\n currency: quote.sourceCurrency.currency\n }).format(quote.sourceCurrency.amount),\n formattedTargetAmount: new Intl.NumberFormat('en-US', {\n style: 'currency',\n currency: quote.targetCurrency.currency\n }).format(quote.targetCurrency.amount)\n };\n } catch (error) {\n // Handle different types of errors\n if (error.name === 'TypeError') {\n console.error('Network error:', error.message);\n } else {\n console.error('API error:', error.message);\n }\n throw error; // Re-throw to let caller handle it\n }\n};\n \n// Example usage with error handling:\ntry {\n const quote = await getFxQuote('USD', 'EUR', '100.00');\n console.log('Formatted Quote:', quote.formattedSourceAmount, '→', quote.formattedTargetAmount);\n} catch (error) {\n console.error('Failed to get FX quote:', error.message);\n}\n```\n\n**Required Permission:** `get-fx-quote`\n\nThis endpoint requires the permission claim `get-fx-quote` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "FxQuotes_Get", "parameters": [ { "name": "unitCurrency", "in": "query", "required": true, "description": "Currency that will be converted from. Must be a valid 3-letter ISO currency code (e.g., USD, EUR, GBP).", "schema": { "type": "string", "maxLength": 3, "minLength": 3 }, "x-position": 1 }, { "name": "currencyOfTransfer", "in": "query", "required": true, "description": "Currency that will be converted to. Must be a valid 3-letter ISO currency code (e.g., USD, EUR, GBP). Must be different from the unit currency.", "schema": { "type": "string", "maxLength": 3, "minLength": 3 }, "x-position": 2 }, { "name": "instructedAmount", "in": "query", "required": true, "description": "The amount to be converted from the unit currency. Must be a valid decimal number with up to 2 decimal places (e.g., \"100.00\").", "schema": { "type": "string" }, "x-position": 3 } ], "responses": { "200": { "description": "OK - The request was successful. Returns the FX quote details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxQuote" }, "examples": { "Json": { "value": { "sourceCurrency": { "currency": "USD", "amount": 1000 }, "targetCurrency": { "currency": "EUR", "amount": 902.5 }, "expiryDateTime": "2024-05-25T10:15:00.0000000Z", "exchangeRate": 0.9025 } }, "Csv": { "value": [ "\"source_currency_currency\",\"source_currency_amount\",\"target_currency_currency\",\"target_currency_amount\",\"expiry_date_time\",\"exchange_rate\"", "\"USD\",\"1000.00\",\"EUR\",\"902.50\",\"2024-05-25T10:15:00Z\",\"0.9025\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-fx-quote" ] }, { "Authorization": [] } ] } }, "/v1/internal-transfers": { "post": { "tags": [ "Internal Transfers" ], "summary": "Internal Transfer", "description": "Initiates an internal funds transfer between two accounts within the institution. \nThe request must include source and destination account details, along with the amount and currency to be transferred. \nOptionally, clients may provide a transaction reference and remittance information describing the purpose of the payment.\n\n- debitAccountNumber: The account number from which funds will be debited.\n- debitAmountCurrency: The currency code for the debit amount. Must match the credit account currency.\n- creditAccountNumber: The account number to be credited.\n- creditAmountCurrency: The currency code for the credit amount. Must match the debit account currency.\n- debitAmount: The amount to be transferred.\n- endToEndIdentification: (Optional) A unique reference provided by the client to identify the transaction end-to-end.\n- remittanceInformation: (Optional) Free-text remittance information describing the purpose of the transaction.\n \n### Important Notes:\n- Transfers between accounts with different currencies are not allowed. The debit and credit account currencies must match.\n- Ensure all inputs are validated and the source account has sufficient funds before making the request.\n \n### High-Value Exchange Requests (> 100 000 BMD)\nIf the requested exchange amount exceeds **100 000 BMD**, the `POST /v1/transfers/internal` endpoint will **not return an immediate confirmation**. \nInstead, the request is routed for **manual processing by our treasury desk** to secure the most competitive rate available.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default).\n- Set `Accept: text/csv` for CSV responses.\nIf the Accept header is omitted, `application/json` is assumed.\n \n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/internal-transfers\n \n### Sample Request in JavaScript:\n \n```javascript\nasync function executeInternalTransfer() {\n try {\n const response = await fetch('https://api.bcb.bm/v1/internal-transfers', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional: UUID format required if provided\n },\n body: JSON.stringify({\n debitAccountNumber: \"12345678901234567890123456\",\n debitAmountCurrency: \"USD\",\n creditAccountNumber: \"98765432109876543210987654\",\n creditAmountCurrency: \"USD\", // Must match debitAmountCurrency\n debitAmount: \"100.00\",\n endToEndIdentification: \"REF-INV-20250417-001\", // Optional external transaction reference\n remittanceInformationUnstructured: \"Payment for invoice #12345\" // Optional payment description\n })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Transfer failed: ${JSON.stringify(errorData)}`);\n }\n \n const data = await response.json();\n console.log('Transfer result:', data);\n \n // Example processing of the returned object\n const { id, status, uniqueIdentifier, internalTransferDetails, linkedActivities } = data;\n const { amountCredited, creditAmountCurrency, debitAmount, amountDebited, chargeAmount, valueDate, chargeAnalysisReceiver, chargeAnalysisSender, debitAccountNumber, creditAccountNumber, chargeAccountNumber } = internalTransferDetails;\n\n // Log the main transfer details.\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Amount Credited:', amountCredited.amount, amountCredited.currency);\n console.log('Credit Amount Currency:', creditAmountCurrency);\n console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);\n console.log('Amount Debited:', amountDebited.amount, amountDebited.currency);\n console.log('Charge Amount:', chargeAmount.amount, chargeAmount.currency);\n console.log('Value Date:', valueDate);\n console.log('Charge Analysis Receiver:', chargeAnalysisReceiver);\n console.log('Charge Analysis Sender:', chargeAnalysisSender);\n \n // Process debit account information.\n console.log('Debit Account Number:', debitAccountNumber.number);\n if (debitAccountNumber.accountRoutings) {\n debitAccountNumber.accountRoutings.forEach(routing => {\n console.log('Debit Account Routing Scheme:', routing.scheme);\n console.log('Debit Account Routing Address:', routing.address);\n });\n }\n \n // Process credit account information.\n console.log('Credit Account Number:', creditAccountNumber.number);\n if (creditAccountNumber.accountRoutings) {\n creditAccountNumber.accountRoutings.forEach(routing => {\n console.log('Credit Account Routing Scheme:', routing.scheme);\n console.log('Credit Account Routing Address:', routing.address);\n });\n }\n \n // Process charge account information.\n console.log('Charge Account Number:', chargeAccountNumber.number);\n if (chargeAccountNumber.accountRoutings) {\n chargeAccountNumber.accountRoutings.forEach(routing => {\n console.log('Charge Account Routing Scheme:', routing.scheme);\n console.log('Charge Account Routing Address:', routing.address);\n });\n }\n \n // Process linked activities.\n linkedActivities.forEach(activity => {\n console.log('Linked Activity ID:', activity.id);\n console.log('Linked Activity Transaction Status:', activity.transactionStatus);\n console.log('Linked Activity Status:', activity.status);\n console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);\n const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;\n console.log('Linked Activity Arrangement ID:', arrangementId);\n console.log('Linked Activity Activity ID:', activityId);\n console.log('Linked Activity Product ID:', productId);\n console.log('Linked Activity Currency ID:', currencyId);\n console.log('Linked Activity Effective Date:', effectiveDate);\n });\n \n // Final status logging.\n if (status === 'SUCCESS') {\n console.log('The transfer was successful.');\n } else {\n console.log('The transfer failed:', status);\n }\n } catch (error) {\n console.error('Error executing internal transfer:', error);\n }\n}\n \nexecuteInternalTransfer();\n```\n\n**Required Permission:** `internal-transfer`\n\nThis endpoint requires the permission claim `internal-transfer` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "InternalTransfers_Post", "requestBody": { "x-name": "transfer", "description": "The internal transfer request details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransferRequest" }, "example": { "endToEndIdentification": "REF-INV-20250417-001", "remittanceInformation": "Payment for invoice #12345", "debitAccountNumber": 987654321098765, "debitAmountCurrency": "USD", "creditAccountNumber": 123456789012345, "creditAmountCurrency": "USD", "debitAmount": 100 } } }, "x-position": 1 }, "responses": { "201": { "description": "The transfer was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransfer" }, "examples": { "Json": { "value": { "id": "internal-transfer-123", "status": "COMPLETED", "uniqueIdentifier": "unique-identifier-123", "internalTransferDetails": { "amountCredited": { "currency": "USD", "amount": 100 }, "creditAmountCurrency": "USD", "debitAmount": { "currency": "USD", "amount": 100 }, "amountDebited": { "currency": "USD", "amount": 100 }, "chargeAmount": { "currency": "USD", "amount": 5 }, "valueDate": "2023-05-31", "chargeAnalysisReceiver": "Receiver Charge Analysis", "chargeAnalysisSender": "Sender Charge Analysis", "debitAccountNumber": { "number": 123456789, "accountRoutings": [ { "scheme": "IBAN", "address": "IBAN123456789" } ] }, "creditAccountNumber": { "number": 987654321, "accountRoutings": [ { "scheme": "IBAN", "address": "IBAN987654321" } ] }, "chargeAccountNumber": { "number": "charge123", "accountRoutings": [ { "scheme": "IBAN", "address": "IBANcharge123" } ] } }, "linkedActivities": [ { "id": "activity123", "transactionStatus": "SUCCESS", "status": "COMPLETED", "uniqueIdentifier": "unique-activity-123", "activityDetails": { "arrangementId": "arrangement123", "activityId": "activity123", "productId": "product123", "currencyId": "USD", "effectiveDate": "2023-05-31" } } ] } }, "Csv": { "value": [ "\"id\",\"status\",\"unique_identifier\",\"internal_transfer_details_amount_credited_currency\",\"internal_transfer_details_amount_credited_amount\",\"internal_transfer_details_credit_amount_currency\",\"internal_transfer_details_debit_amount_currency\",\"internal_transfer_details_debit_amount_amount\",\"internal_transfer_details_amount_debited_currency\",\"internal_transfer_details_amount_debited_amount\",\"internal_transfer_details_charge_amount_currency\",\"internal_transfer_details_charge_amount_amount\",\"internal_transfer_details_value_date\",\"internal_transfer_details_charge_analysis_receiver\",\"internal_transfer_details_charge_analysis_sender\",\"internal_transfer_details_debit_account_number_number\",\"internal_transfer_details_debit_account_number_account_routings_0_scheme\",\"internal_transfer_details_debit_account_number_account_routings_0_address\",\"internal_transfer_details_credit_account_number_number\",\"internal_transfer_details_credit_account_number_account_routings_0_scheme\",\"internal_transfer_details_credit_account_number_account_routings_0_address\",\"internal_transfer_details_charge_account_number_number\",\"internal_transfer_details_charge_account_number_account_routings_0_scheme\",\"internal_transfer_details_charge_account_number_account_routings_0_address\",\"linked_activities_0_id\",\"linked_activities_0_transaction_status\",\"linked_activities_0_status\",\"linked_activities_0_unique_identifier\",\"linked_activities_0_activity_details_arrangement_id\",\"linked_activities_0_activity_details_activity_id\",\"linked_activities_0_activity_details_product_id\",\"linked_activities_0_activity_details_currency_id\",\"linked_activities_0_activity_details_effective_date\"", "\"internal-transfer-123\",\"COMPLETED\",\"unique-identifier-123\",\"USD\",\"100.00\",\"USD\",\"USD\",\"100.00\",\"USD\",\"100.00\",\"USD\",\"5.00\",\"2023-05-31\",\"Receiver Charge Analysis\",\"Sender Charge Analysis\",\"123456789\",\"IBAN\",\"IBAN123456789\",\"987654321\",\"IBAN\",\"IBAN987654321\",\"charge123\",\"IBAN\",\"IBANcharge123\",\"activity123\",\"SUCCESS\",\"COMPLETED\",\"unique-activity-123\",\"arrangement123\",\"activity123\",\"product123\",\"USD\",\"2023-05-31\"" ] } } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "internal-transfer" ] }, { "Authorization": [] } ] } }, "/v1/payments/swift": { "post": { "tags": [ "Payments" ], "summary": "SWIFT Payment", "description": "Initiates an international wire transfer over the SWIFT network. The request carries source and destination account information, payment amount and currency, beneficiary details, and remittance/reference information. Both JSON and CSV response formats are supported via the `Accept` header.\n \n### Cross-Currency FX\nFor cross-currency payments you may supply the **debit amount** instead of the instructed amount (additive format):\n- Send `debitAmount` (currency + amount) as the exact amount to be debited.\n- Send `instructedAmount` with `currency` only (amount omitted); the bank assigns the exchange rate and computes the credited amount.\n- Do **not** send both `debitAmount.amount` and `instructedAmount.amount`.\n- If `debitAmount` is omitted, `instructedAmount` (currency + amount) is used as the standard same-currency behaviour.\n \n### Creditor Agent (Beneficiary Bank)\n- If `creditorAgent.identification` (BIC/bank identifier) is provided, `creditorAgent.name` and `creditorAgent.additionalInformation` are optional and may be omitted.\n- If `creditorAgent.identification` is not provided, supply `creditorAgent.name` and `creditorAgent.additionalInformation` to identify the beneficiary bank.\n \n### Request basics\n- **Endpoint:** `POST https://api.bcb.bm/v1/payments/swift`\n- **Authorization:** `Bearer {token}`.\n- **Accept:** `application/json` (default) or `text/csv`.\n- **Idempotency-Key:** optional UUID v4 header (≤ 255 chars). See below.\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header. When supplied, the server caches the **successful** response and replays it on repeat calls.\n- If no idempotency key is provided, the request is processed normally (duplicates are possible).\n- If a valid UUID key is supplied, the system stores the response of the first `2xx` outcome and replays it on subsequent calls with the same key.\n- **TTL (cache lifetime):** the stored response is retained for a limited window (currently on the order of one hour). After expiry the same key is treated as a new request - but `instructionIdentification` deduplication still applies for **24 hours**. Plan client-side retries to land inside the cache window.\n- **Scope:** keys are partitioned by client/user, HTTP method, and request path. The same key on `/payments/swift` and `/payments/ach-local` is **not** shared - each endpoint has its own cache slot.\n- **Concurrency:** if a second request with the same key arrives while the first is still in flight, the second is rejected with `409 Conflict` and message `\"Request is already being processed.\"` Wait and retry.\n- **Body mismatch:** request bodies are **not** compared on replay. If you reuse a key with a different body, the original cached response is returned - the new body is ignored. Mint a fresh key for any logically different request.\n- **Non-2xx responses are not cached.** A `4xx` validation failure or `5xx` server error can be retried with the same key and will execute again.\n \n### Deduplication\nA separate, business-level guard on the `instructionIdentification` field, applied independently of the `Idempotency-Key` header:\n- Reusing an `instructionIdentification` for an active payment is rejected with `409 PAYMENT_DUPLICATE_INSTRUCTION_ID`.\n- Use a fresh `instructionIdentification` for each new payment intent. Reuse it (with the same `Idempotency-Key`) only when retrying the exact same payment.\n- The deduplication window is currently configured as **24 hours** from the first accepted request.\n \n### How `Idempotency-Key` and `instructionIdentification` combine\nThey are independent mechanisms with different purposes.\n- `Idempotency-Key` (header) is a **transport-level retry token**. It lets you safely retry the same HTTP call and get the original response replayed.\n- `instructionIdentification` (body) is the **business identifier of the payment**. It is persisted on the payment record and forwarded downstream. To prevent the same payment intent from being submitted twice, a value that is already in flight or recently accepted is rejected with `409 PAYMENT_DUPLICATE_INSTRUCTION_ID` (window: 24 hours).\n \n| `Idempotency-Key` | `instructionIdentification` | Behaviour |\n|---|---|---|\n| no | no | No protection. Each call creates a new payment. |\n| **yes** | no | HTTP retries of the same call replay the original response. A new `Idempotency-Key` creates a new payment. |\n| no | **yes** | First call is processed normally. Reusing the same business identifier within 24 hours is rejected with `409 PAYMENT_DUPLICATE_INSTRUCTION_ID`. The original success response is **not** replayed - record it client-side. |\n| **yes** | **yes** | Recommended. HTTP retries of the same call replay the original response. A new `Idempotency-Key` reusing an in-flight `instructionIdentification` is rejected with `409`. |\n \n### Resilience: classifying responses\nThe dedupe and idempotency layers together cover three distinct failure modes. The status code tells you what to do next:\n \n- `503 DEDUPE_LOCK_UNAVAILABLE` - the duplicate-check store could not acquire its lock for `instructionIdentification`. The payment was **not** submitted to core banking. Safe to retry after a short backoff with the **same** `instructionIdentification` (and the **same** `Idempotency-Key`, if you used one). This is **not** \"a duplicate was detected\" - it is \"we could not verify uniqueness right now.\"\n- `409 PAYMENT_DUPLICATE_INSTRUCTION_ID` - this `instructionIdentification` was already accepted within the 24-hour window. Do **not** retry the `POST`; query payment status to reconcile.\n- `5xx`, connection timeout, or no response - outcome unknown. Retry with the **same** `Idempotency-Key` and **same** `instructionIdentification`. The server will either replay the original `201` (if the first attempt landed) or return `409 PAYMENT_DUPLICATE_INSTRUCTION_ID` (also indicating the first attempt landed).\n \nDecision tree in pseudocode:\n \n```javascript\nasync function submitPayment(paymentRequest, idempotencyKey) {\n for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {\n const res = await postPayment(paymentRequest, idempotencyKey);\n \n switch (res.status) {\n case 201:\n return res.body; // success - persist paymentId against instructionIdentification\n \n case 409: // PAYMENT_DUPLICATE_INSTRUCTION_ID - intent already submitted\n // Do NOT retry with a new instructionId. Reconcile via status lookup.\n return await reconcileViaStatusLookup(paymentRequest.instructionIdentification);\n \n case 503: // DEDUPE_LOCK_UNAVAILABLE - NOT submitted, safe to retry as-is\n case 502: case 504: // transient gateway\n await backoff(attempt); continue;\n \n default:\n if (isNetworkError(res)) { // unknown outcome - retry SAME key + SAME instructionId\n await backoff(attempt); continue;\n }\n throw res; // 4xx other - fix request, mint NEW instructionId before retrying\n }\n }\n}\n```\n \n### When to rotate `instructionIdentification`\n \n```javascript\n// NEW payment intent (user clicks \"Send\" again, new business event)\nconst intent = {\n instructionIdentification: uuid(),\n idempotencyKey: uuid()\n};\n \n// RETRY of the SAME intent (5xx, 503 DEDUPE_LOCK_UNAVAILABLE, timeout)\n// -> keep BOTH values stable; the server will replay or short-circuit safely\nretry(intent);\n \n// After 409 PAYMENT_DUPLICATE_INSTRUCTION_ID\n// -> do NOT POST again; query status to reconcile\nawait getPaymentStatus(intent.instructionIdentification);\n```\n \n### `Idempotency-Key` lifecycle (client-side checklist)\n- Mint the key **before** the HTTP call and persist it alongside the payment intent so a process restart or retry can still find it.\n- Reuse it for every retry of the same intent; treat it as \"spent\" only after a terminal (`2xx` or non-retryable `4xx`) response.\n- Plan retries to land inside the cache window (~1 hour). Beyond that, `instructionIdentification` (24 h) is your remaining guard.\n \n### Minimal Request Example\n \n```javascript\nconst res = await fetch('https://api.bcb.bm/v1/payments/swift', {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${token}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': idempotencyKey, // UUID v4, per payment intent\n },\n body: JSON.stringify(paymentRequest), // shape: see request schema below\n});\n```\n \nThe full request and response schemas, including field types and a worked example, are rendered below from the API contract.\n\n**Required Permission:** `payment-swift`\n\nThis endpoint requires the permission claim `payment-swift` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Payments_Post", "requestBody": { "x-name": "request", "description": "The SWIFT payment request containing all necessary payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "example": { "instructionIdentification": "PAY-2024-03-21-001", "debtorAccount": { "identification": "BM12BCBK00001234567890" }, "instructedAmount": { "currency": "USD", "amount": 50000 }, "debitAmount": null, "creditorAccount": { "identification": "US12BCBK00001234567890", "name": "Global Investment Services Inc", "additionalInformation": [ "350 Fifth Avenue", "New York, NY 10118", "United States" ] }, "creditorAgent": { "identification": "CHASUS33", "name": "JPMorgan Chase Bank", "additionalInformation": [ "383 Madison Avenue", "New York, NY 10179", "United States" ] }, "intermediaryAgent": { "identification": "BCBKBMHM", "name": "Bermuda Commercial Bank", "additionalInformation": [ "Victoria Place", "31 Victoria Street", "Hamilton HM 10, Bermuda" ] }, "chargesType": "OUR", "remittanceInformation": [ "Payment for investment management services Q1 2024", "Invoice #INV-2024-001", "Service Period: Jan-Mar 2024" ] } } }, "x-position": 1 }, "responses": { "201": { "description": "Created - The payment was successfully processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "examples": { "Json": { "value": { "id": "PAY987654321", "status": "success", "transactionStatus": "COMPLETED", "uniqueIdentifier": "unique-identifier-987", "details": { "extReference": "EXT98765", "instructedAmount": { "currency": "USD", "amount": 50000 }, "debtorAccount": { "schemeName": "IBAN", "identification": "BM12BCBK00001234567890", "currency": "" }, "beneficiaryAccount": { "schemeName": "IBAN", "identification": "US12BCBK00001234567890", "currency": "" }, "creditorAccount": { "schemeName": "IBAN", "identification": "US12BCBK00001234567890", "currency": "" }, "settlementDetails": { "amountCredited": { "currency": "USD", "amount": 50000 }, "amountDebited": { "currency": "USD", "amount": 50100 }, "valueDate": "2024-03-21", "recordStatus": "COMPLETED" }, "chargeDetails": { "chargesType": "OUR", "chargeAmount": { "currency": "USD", "amount": 100 }, "chargeAccount": { "schemeName": "IBAN", "identification": "BM12BCBK00001234567890", "currency": "" }, "chargeAnalysis": null }, "remittanceInformation": [ { "unstructured": "Payment for investment management services Q1 2024" }, { "unstructured": "Invoice #INV-2024-001" }, { "unstructured": "Service Period: Jan-Mar 2024" } ], "beneficiary": { "identification": "US12BCBK00001234567890", "name": "Global Investment Services Inc", "additionalInformation": [ "350 Fifth Avenue", "New York, NY 10118", "United States" ] }, "beneficiaryAgent": { "identification": "CHASUS33", "name": "JPMorgan Chase Bank", "additionalInformation": [ "SWIFT/BIC: CHASUS33", "383 Madison Avenue", "New York, NY 10179", "United States" ] }, "intermediaryAgent": { "identification": "BCBKBMHM", "name": "Bermuda Commercial Bank", "additionalInformation": [ "SWIFT/BIC: BCBKBMHM", "Victoria Place", "31 Victoria Street", "Hamilton HM 10, Bermuda" ] } }, "linkedActivities": [ { "id": "ACT987654", "transactionStatus": "COMPLETED", "status": "SUCCESS", "uniqueIdentifier": "act-987", "activityDetails": { "arrangementId": "arr-987", "activityId": "act-987", "productId": "prod-987", "currencyId": "USD", "effectiveDate": "2024-03-21" } } ] } }, "Csv": { "value": [ "\"id\",\"status\",\"transaction_status\",\"unique_identifier\",\"details_ext_reference\",\"details_instructed_amount_currency\",\"details_instructed_amount_amount\",\"details_debtor_account_scheme_name\",\"details_debtor_account_identification\",\"details_debtor_account_name\",\"details_beneficiary_account_scheme_name\",\"details_beneficiary_account_identification\",\"details_beneficiary_account_name\",\"details_creditor_account_scheme_name\",\"details_creditor_account_identification\",\"details_creditor_account_name\",\"details_settlement_details_amount_credited_currency\",\"details_settlement_details_amount_credited_amount\",\"details_settlement_details_amount_debited_currency\",\"details_settlement_details_amount_debited_amount\",\"details_settlement_details_value_date\",\"details_settlement_details_record_status\",\"details_charge_details_charges_type\",\"details_charge_details_charge_amount_currency\",\"details_charge_details_charge_amount_amount\",\"details_charge_details_charge_account_scheme_name\",\"details_charge_details_charge_account_identification\",\"details_charge_details_charge_account_name\",\"details_remittance_information_0_unstructured\",\"details_remittance_information_1_unstructured\",\"details_remittance_information_2_unstructured\",\"details_beneficiary_identification\",\"details_beneficiary_name\",\"details_beneficiary_additional_information_0\",\"details_beneficiary_additional_information_1\",\"details_beneficiary_additional_information_2\",\"details_beneficiary_agent_identification\",\"details_beneficiary_agent_name\",\"details_beneficiary_agent_additional_information_0\",\"details_beneficiary_agent_additional_information_1\",\"details_beneficiary_agent_additional_information_2\",\"details_beneficiary_agent_additional_information_3\",\"details_intermediary_agent_identification\",\"details_intermediary_agent_name\",\"details_intermediary_agent_additional_information_0\",\"details_intermediary_agent_additional_information_1\",\"details_intermediary_agent_additional_information_2\",\"details_intermediary_agent_additional_information_3\",\"linked_activities_0_id\",\"linked_activities_0_transaction_status\",\"linked_activities_0_status\",\"linked_activities_0_unique_identifier\",\"linked_activities_0_activity_details_arrangement_id\",\"linked_activities_0_activity_details_activity_id\",\"linked_activities_0_activity_details_product_id\",\"linked_activities_0_activity_details_currency_id\",\"linked_activities_0_activity_details_effective_date\"", "\"PAY987654321\",\"success\",\"COMPLETED\",\"unique-identifier-987\",\"EXT98765\",\"USD\",\"50000.00\",\"IBAN\",\"BM12BCBK00001234567890\",\"\",\"IBAN\",\"US12BCBK00001234567890\",\"\",\"IBAN\",\"US12BCBK00001234567890\",\"\",\"USD\",\"50000.00\",\"USD\",\"50100.00\",\"2024-03-21\",\"COMPLETED\",\"OUR\",\"USD\",\"100.00\",\"IBAN\",\"BM12BCBK00001234567890\",\"\",\"Payment for investment management services Q1 2024\",\"Invoice #INV-2024-001\",\"Service Period: Jan-Mar 2024\",\"US12BCBK00001234567890\",\"Global Investment Services Inc\",\"350 Fifth Avenue\",\"New York, NY 10118\",\"United States\",\"CHASUS33\",\"JPMorgan Chase Bank\",\"SWIFT/BIC: CHASUS33\",\"383 Madison Avenue\",\"New York, NY 10179\",\"United States\",\"BCBKBMHM\",\"Bermuda Commercial Bank\",\"SWIFT/BIC: BCBKBMHM\",\"Victoria Place\",\"31 Victoria Street\",\"Hamilton HM 10, Bermuda\",\"ACT987654\",\"COMPLETED\",\"SUCCESS\",\"act-987\",\"arr-987\",\"act-987\",\"prod-987\",\"USD\",\"2024-03-21\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - The instructionIdentification has already been submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable - The duplicate check lock is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "payment-swift" ] }, { "Authorization": [] } ] } }, "/v1/.well-known/jwks.json": { "get": { "tags": [ "Public Keys" ], "summary": "Gets the bank's current signing public key.", "description": "Gets the bank’s current signing public key in JWKS format. Returns a JWKS containing one RSA key with fields:\n- kid: rsa-{keyVersion}\n- kty: RSA\n- alg: PS256\n- use: sig\n- n/e: base64url-encoded modulus and exponent\nThis endpoint requires OpenBankApi authorization; no private key material is exposed.", "operationId": "PublicKeys_GetJwks", "responses": { "200": { "description": "JWKS payload with the active signing key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JwksResponse" }, "example": { "keys": [ { "kty": "RSA", "use": "sig", "alg": "PS256", "kid": "rsa-v1", "n": "u8Jx7zV9KkWlZqS5qZ1e8E6-hwFkZl0ob8BZqC5JxW0SP-L9c7szw1Zcrw1xwqXkDFFG8sUiDqJcVQnI-AVS4fRNn2drXr6IJuE5i2jxEwHkJq9e-3KifxHbK7WfG5A0yXspwxvzI8vEOwUlTta_yYB5kAEV1kZkH6yN2V_2Q7vJz0ZfM_kqfC1M3G2aCQ6U7gCgN_Qmfrj7q6kP2zR9a7vSg9QZyYxBrS_ImV1LhNWDKqHeX5vKQ1CW6m6Qd4y9P7Q", "e": "AQAB" } ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [] } ] } }, "/auth/token": { "post": { "tags": [ "Token" ], "summary": "Generate Token", "description": "Generates a JWT access token based on provided client credentials. Use this POST endpoint to authenticate using your `clientId` and `clientSecret` and receive a JWT token.\n\n**Token Validity:** 40 minutes from the time of issuance.\n\n**Endpoint:** `https://api.bcb.bm/auth/token`\n\n**Required Headers:**\n- `Content-Type: application/json`\n- `Accept: application/json`\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function getToken() {\n try {\n const response = await fetch('https://api.bcb.bm/auth/token', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n },\n body: JSON.stringify({\n clientId: 'your-client-id',\n clientSecret: 'your-client-secret'\n })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || response.statusText}`);\n }\n \n const data = await response.json();\n console.log('JWT Token:', data.token);\n // Store token securely\n localStorage.setItem('jwt', data.token);\n } catch (error) {\n console.error('Fetch error:', error);\n }\n}\n\ngetToken();\n```", "operationId": "Token_GenerateToken", "requestBody": { "x-name": "credentials", "description": "The API credentials containing client ID and client secret for authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredentials" }, "example": { "clientId": "your-client-id-here", "clientSecret": "your-client-secret-here" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Token generated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiToken" } } } }, "400": { "description": "Invalid request. Ensure the client credentials are provided correctly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized. The client credentials are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests. You have exceeded the allowed number of requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error occurred during token generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/accounts/{accountNumber}/transactions": { "get": { "tags": [ "Transactions" ], "summary": "Account Transactions", "description": "Retrieves transaction details for the specified account and date range. This endpoint:\n\n- Validates the provided date parameters. The accepted date formats are `yyyy-MM-dd` or `yyyyMMdd`.\n- Maximum date range is one year.\n- Supports both JSON and CSV response formats based on the Accept header.\n- **Supports cursor-based pagination** for efficient handling of large transaction datasets.\n\n### Transaction ID Uniqueness\n**Important**: Transaction IDs are globally unique across the entire banking system. For internal transfers, the same transaction ID appears on both accounts (debit and credit entries) with only the transaction type differing. When fees apply, multiple entries may share the same transaction ID.\n\n📖 **For detailed information about transaction ID behavior, see**: https://developers.bcb.bm/guides/transaction-id-uniqueness-guide\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including pageSize, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/accounts/{accountNumber}/transactions\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getAllTransactionsPaginated(accountNumber, fromDate, toDate) {\n try {\n let allTransactions = [];\n let pageStart = 1;\n let pageToken = null;\n let totalPages = 0;\n\n do {\n // Build URL with pagination parameters\n let url = `https://api.bcb.bm/v1/accounts/${accountNumber}/transactions`;\n const params = new URLSearchParams();\n \n // Always include date range\n params.append('fromDate', fromDate);\n params.append('toDate', toDate);\n \n if (pageStart === 1) {\n // First request: specify pageSize\n params.append('pageSize', '100');\n } else {\n // Subsequent requests: use pageToken and pageStart\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n url += '?' + params.toString();\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log(`Page ${pageStart} data:`, data);\n\n // Store pagination info from first request\n if (pageStart === 1 && data.meta && data.meta.pagination) {\n pageToken = data.meta.pagination.page_token;\n totalPages = Math.ceil(data.meta.pagination.total_size / data.meta.pagination.page_size);\n console.log(`Total pages: ${totalPages}, Page token: ${pageToken}`);\n }\n\n // Collect transactions from this page\n if (data.data && data.data.length > 0) {\n allTransactions.push(...data.data);\n console.log(`Collected ${data.data.length} transactions from page ${pageStart}`);\n }\n\n pageStart++;\n } while (pageStart <= totalPages);\n\n console.log(`Total transactions collected: ${allTransactions.length}`);\n\n // Process all collected transactions\n allTransactions.forEach((transaction, index) => {\n console.log(`Transaction ${index + 1}:`, transaction.id);\n console.log('Account Number:', transaction.thisAccount.number);\n console.log('Other Account Number:', transaction.otherAccount.number);\n console.log('Type:', transaction.details.type);\n console.log('Description:', transaction.details.description);\n console.log('Posted Date:', transaction.details.posted);\n console.log('Amount:', transaction.details.value.amount);\n console.log('Currency:', transaction.details.value.currency);\n console.log('Narrative:', transaction.metadata.narrative);\n \n if (transaction.transactionAttributes && transaction.transactionAttributes.length > 0) {\n transaction.transactionAttributes.forEach(attribute => {\n console.log(`${attribute.name}: ${attribute.value}`);\n });\n }\n });\n\n return allTransactions;\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n throw error;\n }\n}\n\n// Alternative: Get single page of transactions\nasync function getTransactionsPage(accountNumber, fromDate, toDate, pageStart = 1, pageToken = null) {\n try {\n let url = `https://api.bcb.bm/v1/accounts/${accountNumber}/transactions`;\n const params = new URLSearchParams();\n \n // Always include date range\n params.append('fromDate', fromDate);\n params.append('toDate', toDate);\n \n if (pageStart === 1 && !pageToken) {\n params.append('pageSize', '250'); // Custom page size\n } else {\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n url += '?' + params.toString();\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log('Transactions page:', data);\n return data;\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n throw error;\n }\n}\n\n// Example usage:\ngetAllTransactionsPaginated('1234567890', '2023-01-25', '2023-02-25'); // Retrieves all transactions across multiple pages\n// OR\ngetTransactionsPage('1234567890', '2023-01-25', '2023-02-25', 1).then(firstPage => {\n console.log('First page:', firstPage);\n // Use firstPage.meta.pagination.page_token for subsequent requests\n});\n```\n\n**Required Permission:** `get-transactions`\n\nThis endpoint requires the permission claim `get-transactions` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Transactions_Get", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "The account number to retrieve transactions for.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1 }, { "name": "fromDate", "in": "query", "required": true, "description": "The start date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 2 }, { "name": "toDate", "in": "query", "required": true, "description": "The end date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 3 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 4 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 5 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 6 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfTransactionOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 2, "pageToken": "202407250072428721.02,99", "totalSize": 955, "pageSize": 99 } }, "data": [ { "id": 1, "thisAccount": { "number": 123456789, "accountRoutings": [ { "scheme": "BIC", "address": 123456789 } ] }, "otherAccount": { "number": 987654321, "accountRoutings": [ { "scheme": "BIC", "address": 987654321 } ] }, "details": { "type": "Credit", "description": "Payment", "posted": "2019-01-01", "completed": "", "newBalance": null, "value": { "currency": "USD", "amount": 100 } }, "metadata": { "narrative": "Payment for services" }, "transactionAttributes": [ { "name": "Service", "value": "Payment" } ] }, { "id": 2, "thisAccount": { "number": 123456789, "accountRoutings": [ { "scheme": "BIC", "address": 123456789 } ] }, "otherAccount": { "number": 987654321, "accountRoutings": [ { "scheme": "BIC", "address": 987654321 } ] }, "details": { "type": "Credit", "description": "Payment", "posted": "2019-01-01", "completed": "", "newBalance": null, "value": { "currency": "USD", "amount": 100 } }, "metadata": { "narrative": "Payment for services" }, "transactionAttributes": [ { "name": "Service", "value": "Payment" } ] }, { "id": 3, "thisAccount": { "number": 123456789, "accountRoutings": [ { "scheme": "BIC", "address": 123456789 } ] }, "otherAccount": { "number": 987654321, "accountRoutings": [ { "scheme": "BIC", "address": 987654321 } ] }, "details": { "type": "Credit", "description": "Payment", "posted": "2019-01-01", "completed": "", "newBalance": null, "value": { "currency": "USD", "amount": 100 } }, "metadata": { "narrative": "Payment for services" }, "transactionAttributes": [ { "name": "Service", "value": "Payment" } ] } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_id\",\"data_0_this_account_number\",\"data_0_this_account_account_routings_0_scheme\",\"data_0_this_account_account_routings_0_address\",\"data_0_other_account_number\",\"data_0_other_account_account_routings_0_scheme\",\"data_0_other_account_account_routings_0_address\",\"data_0_details_type\",\"data_0_details_description\",\"data_0_details_posted\",\"data_0_details_completed\",\"data_0_details_value_currency\",\"data_0_details_value_amount\",\"data_0_metadata_narrative\",\"data_0_transaction_attributes_0_name\",\"data_0_transaction_attributes_0_value\",\"data_1_id\",\"data_1_this_account_number\",\"data_1_this_account_account_routings_0_scheme\",\"data_1_this_account_account_routings_0_address\",\"data_1_other_account_number\",\"data_1_other_account_account_routings_0_scheme\",\"data_1_other_account_account_routings_0_address\",\"data_1_details_type\",\"data_1_details_description\",\"data_1_details_posted\",\"data_1_details_completed\",\"data_1_details_value_currency\",\"data_1_details_value_amount\",\"data_1_metadata_narrative\",\"data_1_transaction_attributes_0_name\",\"data_1_transaction_attributes_0_value\",\"data_2_id\",\"data_2_this_account_number\",\"data_2_this_account_account_routings_0_scheme\",\"data_2_this_account_account_routings_0_address\",\"data_2_other_account_number\",\"data_2_other_account_account_routings_0_scheme\",\"data_2_other_account_account_routings_0_address\",\"data_2_details_type\",\"data_2_details_description\",\"data_2_details_posted\",\"data_2_details_completed\",\"data_2_details_value_currency\",\"data_2_details_value_amount\",\"data_2_metadata_narrative\",\"data_2_transaction_attributes_0_name\",\"data_2_transaction_attributes_0_value\"", "\"2\",\"202407250072428721.02,99\",\"955\",\"99\",\"1\",\"123456789\",\"BIC\",\"123456789\",\"987654321\",\"BIC\",\"987654321\",\"Credit\",\"Payment\",\"2019-01-01\",\"\",\"USD\",\"100.00\",\"Payment for services\",\"Service\",\"Payment\",\"2\",\"123456789\",\"BIC\",\"123456789\",\"987654321\",\"BIC\",\"987654321\",\"Credit\",\"Payment\",\"2019-01-01\",\"\",\"USD\",\"100.00\",\"Payment for services\",\"Service\",\"Payment\",\"3\",\"123456789\",\"BIC\",\"123456789\",\"987654321\",\"BIC\",\"987654321\",\"Credit\",\"Payment\",\"2019-01-01\",\"\",\"USD\",\"100.00\",\"Payment for services\",\"Service\",\"Payment\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-transactions" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/balances": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Get Virtual Account Balances", "description": "Retrieves balances for a provided list of virtual account numbers. This endpoint:\n \n- Accepts a JSON payload with one or more `accountNumbers`\n- Returns a JSON envelope with `meta` and `data` fields\n- Supports both JSON and CSV response formats based on the Accept header\n- **Pagination**: This endpoint does not accept pagination parameters\n \n**Required Request Properties**\n- **accountNumbers**: Array of virtual account numbers (minimum 1, maximum 1000)\n \n**Response shape**\n- `data` is an array of `{ accountNumber, balance { currency, amount } }`\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n \n### Base URL\nAll API requests use the versioned base URL:\n \n https://api.bcb.bm/v1/virtual-accounts/balances\n \n### Sample Request in JavaScript\n```javascript\nasync function getVirtualAccountBalances(accountNumbers) {\n const response = await fetch('https://api.bcb.bm/v1/virtual-accounts/balances', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n },\n body: JSON.stringify({ accountNumbers })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Failed to retrieve balances: ${JSON.stringify(errorData)}`);\n }\n \n const result = await response.json();\n // result.data is an array of balances\n result.data.forEach(item => {\n console.log(item.accountNumber, item.balance?.amount, item.balance?.currency);\n });\n return result;\n}\n \n// Example usage:\ngetVirtualAccountBalances(['1000331038', '1000331062']);\n```\n\n**Required Permission:** `get-virtual-account-transactions`\n\nThis endpoint requires the permission claim `get-virtual-account-transactions` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsBalances_Post", "requestBody": { "x-name": "request", "description": "Payload containing the list of virtual account numbers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountsGetBalancesRequest" }, "example": { "accountNumbers": [ 1000331038, 1000331062 ] } } }, "x-position": 1 }, "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfVirtualAccountBalanceOf" }, "example": { "meta": { "pagination": { "pageStart": 0, "pageToken": null, "totalSize": 0, "pageSize": 0 } }, "data": [ { "accountNumber": 1000331038, "balance": { "currency": "USD", "amount": 192.98 } }, { "accountNumber": 1000331062, "balance": { "currency": "USD", "amount": 0 } } ] } } } }, "400": { "description": "Bad Request - Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-account-transactions" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/balances/total": { "get": { "tags": [ "Virtual Accounts" ], "summary": "Get Virtual Account Balances Total", "description": "Retrieves the **total balance across all virtual accounts**. This endpoint:\n \n- Returns a **single object** `{ currency, amount }` (one record)\n- Supports both JSON and CSV response formats based on the Accept header\n- **Pagination**: This endpoint does not accept pagination parameters\n \n### Sample Response (JSON)\n```json\n{\n \"currency\": \"USD\",\n \"amount\": \"6755.67\"\n}\n```\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n \n### Base URL\nAll API requests use the versioned base URL:\n \n https://api.bcb.bm/v1/virtual-accounts/balances/total\n \n### Sample Request in JavaScript\n```javascript\nasync function getVirtualAccountBalancesTotal() {\n const response = await fetch('https://api.bcb.bm/v1/virtual-accounts/balances/total', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Accept': 'application/json'\n }\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Failed to retrieve total balance: ${JSON.stringify(errorData)}`);\n }\n \n const result = await response.json();\n console.log(result.data?.amount, result.data?.currency);\n return result;\n}\n```\n\n**Required Permission:** `get-virtual-account-transactions`\n\nThis endpoint requires the permission claim `get-virtual-account-transactions` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsBalances_Get", "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyAmount" }, "example": { "currency": "USD", "amount": 6755.67 } } } }, "400": { "description": "Bad Request - Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-account-transactions" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Create Virtual Accounts", "description": "Creates one or more virtual (sub) accounts for a corporate client. Virtual accounts allow funds to be segregated and tracked independently while remaining linked to a single settlement account.\n \n**Migration notice:** v1 is being retained for backward compatibility only and is planned to be discontinued in the future.\nNew integrations should use `POST /v2/virtual-accounts` and existing consumers should plan their migration to v2.\n \n**Schema scope:** v1 supports `currency`, `accountHolderName`, `accountName`, optional `dob`,\noptional `nativeLanguageName`, optional `unallocated`, and optional `clientReference`.\nUse v2 when you need `nationality`, `taxIdentificationNumber`, or `countryOfResidence` at create time.\n \n**Required Request Properties**\n- **items**: Array of virtual account creation requests (minimum 1, maximum 1000)\n - **currency**: ISO-4217 currency code for the virtual account (e.g., USD, BMD)\n - **accountHolderName**: Human-readable label for the virtual account (required unless `unallocated` is true). **Immutable after first update.**\n - **accountName**: Official account title that will appear on statements (required unless `unallocated` is true). **Immutable after first update.**\n - **Allowed characters (accountHolderName, accountName)**: A-Z, a-z, 0-9, space, and `! \" # $ % & ' ( ) * + , - . / [ \\ ]`. Common symbols such as `_ @ : ; ? { }` are not allowed.\n \n**Optional Request Properties**\n- **unallocated**: When set to `true`, creates the account in \"for allocation\" mode with placeholder values (\"UNALLOCATED\") for `accountHolderName` and `accountName`. This allows bulk pre-creation of virtual accounts for later assignment to end-customers via a one-time PATCH update.\n- **dob**: Date of birth of the account holder, if applicable. **Immutable after first update.**\n- **nativeLanguageName**: Native name of the account holder's language, if applicable (max 255 characters). **Immutable after first update.**\n- **callbackUrl**: URL to receive notifications when the batch job completes (optional)\n- **clientReference**: External reference provided by the client to aid reconciliation (max 35 characters) - per item\n- **customHeaders**: Object of string key/value pairs to be echoed back in the completion callback. Limits: up to 10 headers; each key ≤ 50 characters; each value ≤ 500 characters.\n \n### Unallocated Accounts\nOperationally, clients often need to pre-create many virtual accounts to allocate later. The `unallocated` flag enables a safe \"for allocation\" mode:\n- Creates accounts with generic placeholder values: \"UNALLOCATED\" for `accountHolderName` and `accountName`\n- When `unallocated` is `true`, the `accountHolderName` and `accountName` fields become optional\n- Allows a one-time update via PATCH when the account is assigned to a real end-customer\n- **Important**: The following fields are immutable after the first update: `accountHolderName`, `accountName`, `dob`, and `nativeLanguageName`\n \n### Asynchronous Processing\nVirtual account creation requests are processed asynchronously to ensure optimal performance and reliability:\n- **Immediate Response**: You receive a job ID and status URLs immediately upon submission\n- **Status Monitoring**: Use the provided status URL to monitor job progress\n- **Result Retrieval**: Use the provided result URL to fetch final outcomes when complete\n- **Callback Notifications**: Optionally provide a callback URL for automatic notifications after the job completes\n \n### Message Signing\nCallback notifications are signed. When your client configuration enables response signing, callbacks use the asymmetric option (RSA-PSS + SHA-256) and include `Bcb-Signature`, `Bcb-Timestamp`, `Bcb-Nonce`, and `Bcb-Signature-Version` (e.g., `rsa-v1`). If asymmetry is not configured, callbacks use the HMAC option with your Message Signing Secret and no `Bcb-Signature-Version` header. See the Message Signing guide for verification steps.\n \n### Virtual Account Structure\nEach successfully created virtual account will contain the following properties:\n\n```json\n{\n \"virtualAccountNumber\": \"1000327642\",\n \"bicCode\": \"BPBKBMHMXXX\",\n \"bicCodeFx\": \"BEOEBMH2\",\n \"accountHolderName\": \"T1 Project Alpha Escrow\",\n \"accountName\": \"New Title T2\",\n \"currency\": \"USD\",\n \"balance\": {\n \"amount\": \"0\",\n \"currency\": \"USD\"\n },\n \"category\": \"CMS Sub Acct\"\n}\n```\n \n### Job Status Tracking\nThe response includes URLs for monitoring your batch job:\n- **Status URL**: Poll this URL to check job progress and completion status\n- **Result URL**: Access this URL to retrieve detailed results for each virtual account\n- **Job ID**: Unique identifier for tracking your batch job\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided, the system stores the key and associates it with the batch job\n- If the same idempotency key is received again, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\")\n \n### Sample Request in JavaScript\n \n```javascript\nasync function createVirtualAccounts() {\n try {\n const response = await fetch('https://api.bcb.bm/v1/virtual-accounts', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n callbackUrl: 'https://my-callback-url.com', // Optional\n // Optional: custom headers echoed in the completion webhook\n customHeaders: {\n 'X-Custom-Header-1': 'CustomValue1',\n 'X-Custom-Header-2': 'CustomValue2',\n 'X-Custom-Header-3': 'CustomValue3'\n },\n items: [\n {\n currency: 'USD',\n accountHolderName: 'Test Company Ltd',\n accountName: 'Test Virtual Account 001',\n clientReference: 'BATCH-REF-001'\n },\n {\n currency: 'USD',\n accountHolderName: 'Test Company Ltd',\n accountName: 'Test Virtual Account 002',\n clientReference: 'BATCH-REF-002'\n },\n // Example: Pre-create unallocated accounts for later assignment\n {\n currency: 'USD',\n unallocated: true,\n clientReference: 'UNALLOC-001'\n }\n ]\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Virtual account creation failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const batchResponse = await response.json();\n\n // Display batch job information\n console.log('Batch Job Created:');\n console.log(` Job ID: ${batchResponse.jobId}`);\n console.log(` Status: ${batchResponse.status}`);\n console.log(` Status URL: ${batchResponse.statusUrl}`);\n console.log(` Result URL: ${batchResponse.resultUrl}`);\n\n // Store these URLs for monitoring the job\n // Use statusUrl to check progress\n // Use resultUrl to get final outcomes\n\n return batchResponse;\n } catch (error) {\n console.error('Failed to create virtual accounts:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Create multiple virtual accounts\ncreateVirtualAccounts();\n```\n\n**Required Permission:** `create-virtual-account`\n\nThis endpoint requires the permission claim `create-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_Post", "requestBody": { "x-name": "request", "description": "Batch request containing virtual account creation items and optional callback URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountCreateBatchRequest" }, "example": { "callbackUrl": "https://my-callback-url.com", "customHeaders": { "X-Custom-Header-1": "Custom Value 1", "X-Custom-Header-2": "Custom Value 2" }, "items": [ { "currency": "USD", "accountHolderName": null, "accountName": null, "clientReference": "BATCH-UNALLOC-001", "dateOfBirth": null, "nativeLanguageName": null, "unallocated": true }, { "currency": "USD", "accountHolderName": "Test Company Ltd", "accountName": "Test Virtual Account 001", "clientReference": "BATCH-REF-001", "dateOfBirth": "1990-01-01T00:00:00.0000000", "nativeLanguageName": "Native Name", "unallocated": false }, { "currency": "USD", "accountHolderName": "Test Company Ltd", "accountName": "Test Virtual Account 002", "clientReference": "BATCH-REF-002", "dateOfBirth": null, "nativeLanguageName": null, "unallocated": false }, { "currency": "USD", "accountHolderName": "Test Company Ltd", "accountName": "Test Virtual Account 003", "clientReference": "BATCH-REF-003", "dateOfBirth": null, "nativeLanguageName": null, "unallocated": false } ] } } }, "x-position": 1 }, "responses": { "202": { "description": "Accepted - Virtual account creation job has been queued for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" }, "example": { "jobId": "550e8400-e29b-41d4-a716-446655440001", "status": "Pending", "statusUrl": "https://api.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001", "resultUrl": "https://api.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results" } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "create-virtual-account" ] }, { "Authorization": [] } ] }, "get": { "tags": [ "Virtual Accounts" ], "summary": "Get All Virtual Accounts", "description": "Retrieves all virtual accounts for the authenticated corporate client. This endpoint:\n\n- Returns a paginated list of virtual accounts for the client\n- Response contains the client’s real (non-virtual) accounts as well:\n- **Settlement Account** – the primary clearing account used for cash movements. Account category: \"CMS Settlement\".\n- **Parent Account** – the parent account under which all virtual accounts are organised. Account category: \"CMS Parent Cate\".\n- **Virtual accounts** have the category \"CMS Sub Acct\".\n- Supports optional currency filtering to return only accounts in a specific currency\n- **Supports pagination** for efficient handling of large account datasets\n\n### Filtering\nUse the optional `currency` query parameter to filter results:\n- Must be a valid 3-letter ISO currency code (e.g., USD, BMD, EUR)\n- If omitted, accounts in all currencies are returned\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including pageSize, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getAllVirtualAccounts(currency = null, pageSize = 25, pageStart = 1, pageToken = null) {\n try {\n // Build URL with optional parameters\n let url = 'https://api.bcb.bm/v1/virtual-accounts';\n const params = new URLSearchParams();\n \n if (currency) {\n params.append('currency', currency);\n }\n \n if (pageStart === 1 && !pageToken) {\n // First request only: optionally specify pageSize\n params.append('pageSize', pageSize.toString());\n } else {\n // Subsequent requests: use pageToken + pageStart and do NOT send pageSize again\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n url += '?' + params.toString();\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Virtual accounts retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n\n // Access pagination info\n const pagination = result.meta.pagination;\n console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);\n\n // Process virtual accounts\n result.data.forEach((account, index) => {\n console.log(`Account ${index + 1}:`);\n console.log(` Virtual Account Number: ${account.virtualAccountNumber}`);\n console.log(` BIC: ${account.bicCode}`);\n console.log(` BIC (FX): ${account.bicCodeFx}`);\n console.log(` Account Holder: ${account.accountHolderName}`);\n console.log(` Account Name: ${account.accountName}`);\n console.log(` Currency: ${account.currency}`);\n console.log(` Balance: ${account.balance ? account.balance.amount + ' ' + account.balance.currency : 'N/A'}`);\n console.log(` Category: ${account.category}`);\n \n if (account.clientReference) {\n console.log(` Client Reference: ${account.clientReference}`);\n }\n \n if (account.effectiveDate) {\n console.log(` Effective Date: ${account.effectiveDate}`);\n }\n \n if (account.createdAt) {\n console.log(` Created At: ${account.createdAt}`);\n }\n \n // Log parent/settlement account relationships\n if (account.parentAccount) {\n console.log(` Parent Account: ${account.parentAccount.accountNumber} (${account.parentAccount.accountName})`);\n }\n if (account.settlementAccount) {\n console.log(` Settlement Account: ${account.settlementAccount.accountNumber} (${account.settlementAccount.accountName})`);\n }\n \n console.log('---');\n });\n\n return result;\n } catch (error) {\n console.error('Failed to retrieve virtual accounts:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get all virtual accounts\ngetAllVirtualAccounts();\n\n// Get only USD virtual accounts\ngetAllVirtualAccounts('USD');\n\n// Get first 10 virtual accounts\ngetAllVirtualAccounts(null, 10);\n```\n\n**Required Permission:** `get-virtual-accounts`\n\nThis endpoint requires the permission claim `get-virtual-accounts` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_GetAll", "parameters": [ { "name": "currency", "in": "query", "description": "Optional. The currency of the virtual accounts to filter by. If not specified, all virtual accounts will be returned.", "schema": { "type": "string", "maxLength": 3, "minLength": 0, "nullable": true }, "x-position": 1 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 2 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 3 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 4 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfVirtualAccountOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "202506234881430088.01,99", "totalSize": 7, "pageSize": 99 } }, "data": [ { "virtualAccountNumber": 1000326948, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Global Investment Fund Ltd", "accountName": "Settlement Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Settlement", "clientReference": "SETTLE-REF-001", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": "Native Name", "unallocated": false }, { "virtualAccountNumber": 1000326956, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Global Investment Fund Ltd", "accountName": "Parent Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Parent Cate", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327057, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Corporate Treasury Holdings", "accountName": "Sub Account Operations", "currency": "USD", "balance": { "currency": "USD", "amount": 130492.24 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327073, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Asset Management Services", "accountName": "Sub Account Operations", "currency": "USD", "balance": { "currency": "USD", "amount": 100776.49 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327197, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Project Alpha Escrow", "accountName": "Project Alpha Virtual Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327642, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Treasury Operations Ltd", "accountName": "Enhanced Operations Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327887, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "UNALLOCATED", "accountName": "UNALLOCATED", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": "UNALLOCATED-003", "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": true } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_virtual_account_number\",\"data_0_bic_code\",\"data_0_bic_code_fx\",\"data_0_account_holder_name\",\"data_0_account_name\",\"data_0_currency\",\"data_0_balance_currency\",\"data_0_balance_amount\",\"data_0_category\",\"data_0_client_reference\",\"data_0_dob\",\"data_0_native_language_name\",\"data_0_unallocated\",\"data_1_virtual_account_number\",\"data_1_bic_code\",\"data_1_bic_code_fx\",\"data_1_account_holder_name\",\"data_1_account_name\",\"data_1_currency\",\"data_1_balance_currency\",\"data_1_balance_amount\",\"data_1_category\",\"data_1_unallocated\",\"data_2_virtual_account_number\",\"data_2_bic_code\",\"data_2_bic_code_fx\",\"data_2_account_holder_name\",\"data_2_account_name\",\"data_2_currency\",\"data_2_balance_currency\",\"data_2_balance_amount\",\"data_2_category\",\"data_2_unallocated\",\"data_3_virtual_account_number\",\"data_3_bic_code\",\"data_3_bic_code_fx\",\"data_3_account_holder_name\",\"data_3_account_name\",\"data_3_currency\",\"data_3_balance_currency\",\"data_3_balance_amount\",\"data_3_category\",\"data_3_unallocated\",\"data_4_virtual_account_number\",\"data_4_bic_code\",\"data_4_bic_code_fx\",\"data_4_account_holder_name\",\"data_4_account_name\",\"data_4_currency\",\"data_4_balance_currency\",\"data_4_balance_amount\",\"data_4_category\",\"data_4_unallocated\",\"data_5_virtual_account_number\",\"data_5_bic_code\",\"data_5_bic_code_fx\",\"data_5_account_holder_name\",\"data_5_account_name\",\"data_5_currency\",\"data_5_balance_currency\",\"data_5_balance_amount\",\"data_5_category\",\"data_5_unallocated\",\"data_6_virtual_account_number\",\"data_6_bic_code\",\"data_6_bic_code_fx\",\"data_6_account_holder_name\",\"data_6_account_name\",\"data_6_currency\",\"data_6_balance_currency\",\"data_6_balance_amount\",\"data_6_category\",\"data_6_client_reference\",\"data_6_unallocated\"", "\"1\",\"202506234881430088.01,99\",\"7\",\"99\",\"1000326948\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Global Investment Fund Ltd\",\"Settlement Account\",\"USD\",\"USD\",\"0\",\"CMS Settlement\",\"SETTLE-REF-001\",\"1990-05-15T00:00:00\",\"Native Name\",\"False\",\"1000326956\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Global Investment Fund Ltd\",\"Parent Account\",\"USD\",\"USD\",\"0\",\"CMS Parent Cate\",\"False\",\"1000327057\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Corporate Treasury Holdings\",\"Sub Account Operations\",\"USD\",\"USD\",\"130492.24\",\"CMS Sub Acct\",\"False\",\"1000327073\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Asset Management Services\",\"Sub Account Operations\",\"USD\",\"USD\",\"100776.49\",\"CMS Sub Acct\",\"False\",\"1000327197\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Project Alpha Escrow\",\"Project Alpha Virtual Account\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"False\",\"1000327642\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Treasury Operations Ltd\",\"Enhanced Operations Account\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"False\",\"1000327887\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"UNALLOCATED\",\"UNALLOCATED\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"UNALLOCATED-003\",\"True\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - No virtual accounts were found for the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-accounts" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{virtualAccountNumber}": { "patch": { "tags": [ "Virtual Accounts" ], "summary": "Update Virtual Account", "description": "Updates an existing virtual (sub) account for a corporate client. Only the fields provided in the request body will be updated.\n \n**Migration notice:** v1 is being retained for backward compatibility only and is planned to be discontinued in the future.\nNew integrations should use `PATCH /v2/virtual-accounts/{virtualAccountNumber}` and existing consumers should plan their migration to v2.\n \n**Updatable Properties**\n- **accountHolderName**: Human-readable label for the virtual account. **Immutable after first update** – can only be changed once from the \"UNALLOCATED\" state.\n- **accountName**: Official account title that will appear on statements. **Immutable after first update** – can only be changed once from the \"UNALLOCATED\" state.\n- **Allowed characters (accountHolderName, accountName)**: A-Z, a-z, 0-9, space, and `! \" # $ % & ' ( ) * + , - . / [ \\ ]`. Common symbols such as `_ @ : ; ? { }` are not allowed.\n- **dob**: Date of birth of the account holder. **Immutable after first update** – can only be set once.\n- **nativeLanguageName**: Native name of the account holder's language (max 255 characters). **Immutable after first update** – can only be set once.\n- **clientReference**: External reference provided by the client to aid reconciliation (max 35 characters). This field can be updated multiple times.\n \n**Schema scope:** v1 supports `accountHolderName`, `accountName`, `dob`, `nativeLanguageName`, and `clientReference`.\nUse v2 when you need `nationality`, `taxIdentificationNumber`, or `countryOfResidence`.\n \n### Allocating Unallocated Accounts\nFor virtual accounts created with `unallocated: true`, use this endpoint to perform a **one-time** assignment to a real end-customer:\n- Update `accountHolderName`, `accountName`, `dob`, and `nativeLanguageName` from their initial/placeholder values to the actual customer details\n- **Important**: This is a one-time operation. Once these fields are set, they become immutable:\n - `accountHolderName` and `accountName` can only be changed from \"UNALLOCATED\" state\n - `dob` and `nativeLanguageName` can only be set once (if not provided during creation)\n- Attempting to update immutable fields after the first update will result in a `409 Conflict` error with code `ACCOUNT_NAMES_IMMUTABLE`\n- Only `clientReference` can be updated after allocation\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Sample Request (JavaScript)\n```javascript\nasync function updateVirtualAccount(virtualAccountNumber) {\n try {\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountNumber}`, {\n method: 'PATCH',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n },\n body: JSON.stringify({\n // Note: Only clientReference can be updated after first allocation\n // accountHolderName, accountName, dob, and nativeLanguageName are immutable after first update\n clientReference: 'updated-reference-123'\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n \n // Handle immutable field error\n if (response.status === 409 && errorData.code === 'ACCOUNT_NAMES_IMMUTABLE') {\n console.error('Cannot update immutable fields - already set after first update');\n return;\n }\n \n throw new Error(`Virtual account update failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n const virtualAccount = result.data;\n \n // Log updated details\n console.log('Virtual Account Updated Successfully:');\n console.log(` Account Number: ${virtualAccount.virtualAccountNumber}`);\n console.log(` Account Holder: ${virtualAccount.accountHolderName}`);\n console.log(` Account Name: ${virtualAccount.accountName}`);\n console.log(` Currency: ${virtualAccount.currency}`);\n console.log(` Category: ${virtualAccount.category}`);\n \n if (virtualAccount.balance) {\n console.log(` Balance: ${virtualAccount.balance.amount} ${virtualAccount.balance.currency}`);\n }\n \n if (virtualAccount.clientReference) {\n console.log(` Client Reference: ${virtualAccount.clientReference}`);\n }\n \n console.log(` Effective Date: ${virtualAccount.effectiveDate}`);\n console.log(` Created: ${virtualAccount.createdAt}`);\n \n // Log parent/settlement account info\n if (virtualAccount.parentAccount) {\n console.log(` Parent Account: ${virtualAccount.parentAccount.accountNumber} (${virtualAccount.parentAccount.accountSubType})`);\n }\n if (virtualAccount.settlementAccount) {\n console.log(` Settlement Account: ${virtualAccount.settlementAccount.accountNumber} (${virtualAccount.settlementAccount.accountSubType})`);\n }\n\n return result;\n } catch (err) {\n console.error('Error updating virtual account:', err);\n throw err;\n }\n}\n\n// Example usage:\nupdateVirtualAccount('1000327642');\n\n// Example: Allocating an unallocated account to a customer (ONE-TIME OPERATION)\nasync function allocateUnallocatedAccount(virtualAccountNumber, customerName, accountTitle, dob, nativeLanguageName) {\n try {\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountNumber}`, {\n method: 'PATCH',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n },\n body: JSON.stringify({\n // All these fields are immutable after this update!\n accountHolderName: customerName,\n accountName: accountTitle,\n dob: dob, // Optional - immutable after set\n nativeLanguageName: nativeLanguageName // Optional - immutable after set\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n \n // Handle case where account was already allocated\n if (response.status === 409 && errorData.code === 'ACCOUNT_NAMES_IMMUTABLE') {\n throw new Error('Account has already been allocated. Immutable fields cannot be changed after first update.');\n }\n \n throw new Error(`Account allocation failed: ${JSON.stringify(errorData)}`);\n }\n\n const result = await response.json();\n console.log('Account successfully allocated to:', customerName);\n return result;\n } catch (err) {\n console.error('Error allocating account:', err);\n throw err;\n }\n}\n\n// Allocate a pre-created unallocated account (can only be done once!)\nallocateUnallocatedAccount('1000327650', 'Acme Corporation', 'Acme Trading Account', '1990-05-15', 'John Smith');\n```\n\n**Required Permission:** `update-virtual-account`\n\nThis endpoint requires the permission claim `update-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_Patch", "parameters": [ { "name": "virtualAccountNumber", "in": "path", "required": true, "description": "Virtual account identifier (ID) that uniquely identifies the virtual account", "schema": { "type": "string" }, "x-position": 1 } ], "requestBody": { "x-name": "request", "description": "Payload containing virtual account fields to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountUpdateRequest" }, "example": { "accountHolderName": "Updated Project Alpha Escrow", "accountName": "Updated Project Alpha Virtual Account", "clientReference": "ref-1234567890", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nativeLanguageName": "Native Name" } } }, "x-position": 2 }, "responses": { "200": { "description": "Virtual account updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDetails" }, "examples": { "Json": { "value": { "effectiveDate": "2025-06-20", "createdAt": "2025-07-25T08:23:00.0000000Z", "parentAccount": { "accountId": "1000326956-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Parent Cate", "accountNumber": 1000326956, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "settlementAccount": { "accountId": "1000326948-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Settlement", "accountNumber": 1000326948, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "virtualAccountNumber": 1000327642, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "T1 Project Alpha Escrow", "accountName": "New Title T2", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": "T12cc62d3fb446e7950ffd0797d0a6f41", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": "Native Name", "unallocated": false } }, "Csv": { "value": [ "\"virtual_account_number\",\"bic_code\",\"bic_code_fx\",\"account_holder_name\",\"account_name\",\"currency\",\"balance_currency\",\"balance_amount\",\"category\",\"client_reference\",\"dob\",\"native_language_name\",\"unallocated\",\"effective_date\",\"created_at\",\"parent_account_account_id\",\"parent_account_cif\",\"parent_account_account_number\",\"parent_account_status\",\"parent_account_currency\",\"parent_account_available_balance_currency\",\"parent_account_available_balance_amount\",\"parent_account_account_sub_type\",\"parent_account_owners_0_display_name\",\"parent_account_owners_0_account_holder_type\",\"settlement_account_account_id\",\"settlement_account_cif\",\"settlement_account_account_number\",\"settlement_account_status\",\"settlement_account_currency\",\"settlement_account_available_balance_currency\",\"settlement_account_available_balance_amount\",\"settlement_account_account_sub_type\",\"settlement_account_owners_0_display_name\",\"settlement_account_owners_0_account_holder_type\"", "\"1000327642\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"T1 Project Alpha Escrow\",\"New Title T2\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"T12cc62d3fb446e7950ffd0797d0a6f41\",\"1990-05-15T00:00:00\",\"Native Name\",\"False\",\"2025-06-20\",\"2025-07-25T08:23:00Z\",\"1000326956-2000365\",\"2000365\",\"1000326956\",\"AUTH\",\"USD\",\"USD\",\"0\",\"CMS Parent Cate\",\"GLOB-INVEST BOND FUND LTD\",\"Primary\",\"1000326948-2000365\",\"2000365\",\"1000326948\",\"AUTH\",\"USD\",\"USD\",\"0\",\"CMS Settlement\",\"GLOB-INVEST BOND FUND LTD\",\"Primary\"" ] } } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Virtual account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict – Immutable fields (accountHolderName, accountName, dob, nativeLanguageName) cannot be changed after first update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "update-virtual-account" ] }, { "Authorization": [] } ] }, "get": { "tags": [ "Virtual Accounts" ], "summary": "Get Virtual Account Details", "description": "Retrieves comprehensive information about a specific virtual account, including all its sub-accounts, parent account details, and settlement account information. This endpoint:\n\n- Returns the virtual account details as a single object\n- Includes parent account information (the account this virtual account is derived from)\n- Provides settlement account details (the account used for settlement operations)\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{accountNumber}\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getVirtualAccountDetails(accountNumber) {\n try {\n const url = `https://api.bcb.bm/v1/virtual-accounts/${encodeURIComponent(accountNumber)}`;\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Virtual account details retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n\n // Get the virtual account details (single object, not an array)\n const virtualAccount = result.data;\n console.log('Virtual Account Details:');\n console.log(` Account Number: ${virtualAccount.virtualAccountNumber}`);\n console.log(` BIC: ${virtualAccount.bicCode}`);\n console.log(` BIC (FX): ${virtualAccount.bicCodeFx}`);\n console.log(` Account Holder: ${virtualAccount.accountHolderName}`);\n console.log(` Account Name: ${virtualAccount.accountName}`);\n console.log(` Currency: ${virtualAccount.currency}`);\n console.log(` Category: ${virtualAccount.category}`);\n \n if (virtualAccount.balance) {\n console.log(` Balance: ${virtualAccount.balance.amount} ${virtualAccount.balance.currency}`);\n }\n \n console.log(` Effective Date: ${virtualAccount.effectiveDate}`);\n console.log(` Created: ${virtualAccount.createdAt}`);\n \n if (virtualAccount.clientReference) {\n console.log(` Client Reference: ${virtualAccount.clientReference}`);\n }\n \n // Log parent account details\n if (virtualAccount.parentAccount) {\n console.log(' Parent Account:');\n console.log(` Account Number: ${virtualAccount.parentAccount.accountNumber}`);\n console.log(` Account ID: ${virtualAccount.parentAccount.accountId}`);\n console.log(` CIF: ${virtualAccount.parentAccount.cif}`);\n console.log(` Currency: ${virtualAccount.parentAccount.currency}`);\n console.log(` Sub Type: ${virtualAccount.parentAccount.accountSubType}`);\n console.log(` Status: ${virtualAccount.parentAccount.status}`);\n if (virtualAccount.parentAccount.availableBalance) {\n console.log(` Available Balance: ${virtualAccount.parentAccount.availableBalance.amount} ${virtualAccount.parentAccount.availableBalance.currency}`);\n }\n if (virtualAccount.parentAccount.owners && virtualAccount.parentAccount.owners.length > 0) {\n console.log(` Owner: ${virtualAccount.parentAccount.owners[0].displayName} (${virtualAccount.parentAccount.owners[0].accountHolderType})`);\n }\n }\n \n // Log settlement account details\n if (virtualAccount.settlementAccount) {\n console.log(' Settlement Account:');\n console.log(` Account Number: ${virtualAccount.settlementAccount.accountNumber}`);\n console.log(` Account ID: ${virtualAccount.settlementAccount.accountId}`);\n console.log(` CIF: ${virtualAccount.settlementAccount.cif}`);\n console.log(` Currency: ${virtualAccount.settlementAccount.currency}`);\n console.log(` Sub Type: ${virtualAccount.settlementAccount.accountSubType}`);\n console.log(` Status: ${virtualAccount.settlementAccount.status}`);\n if (virtualAccount.settlementAccount.availableBalance) {\n console.log(` Available Balance: ${virtualAccount.settlementAccount.availableBalance.amount} ${virtualAccount.settlementAccount.availableBalance.currency}`);\n }\n if (virtualAccount.settlementAccount.owners && virtualAccount.settlementAccount.owners.length > 0) {\n console.log(` Owner: ${virtualAccount.settlementAccount.owners[0].displayName} (${virtualAccount.settlementAccount.owners[0].accountHolderType})`);\n }\n }\n\n return result;\n } catch (error) {\n console.error('Failed to retrieve virtual account details:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get details for a specific virtual account\ngetVirtualAccountDetails('1000326808');\n```\n\n**Required Permission:** `get-a-virtual-account`\n\nThis endpoint requires the permission claim `get-a-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_GetDetails", "parameters": [ { "name": "virtualAccountNumber", "in": "path", "required": true, "description": "The virtual account number assigned by the bank.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDetails" }, "examples": { "Json": { "value": { "effectiveDate": "2025-06-20", "createdAt": "2025-07-25T08:23:00.0000000Z", "parentAccount": { "accountId": "1000326956-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Parent Cate", "accountNumber": 1000326956, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "settlementAccount": { "accountId": "1000326948-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Settlement", "accountNumber": 1000326948, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "virtualAccountNumber": 1000327642, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "T1 Project Alpha Escrow", "accountName": "New Title T2", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": "T12cc62d3fb446e7950ffd0797d0a6f41", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": "Native Name", "unallocated": false } }, "Csv": { "value": [ "\"virtual_account_number\",\"bic_code\",\"bic_code_fx\",\"account_holder_name\",\"account_name\",\"currency\",\"balance_currency\",\"balance_amount\",\"category\",\"client_reference\",\"dob\",\"native_language_name\",\"unallocated\",\"effective_date\",\"created_at\",\"parent_account_account_id\",\"parent_account_cif\",\"parent_account_account_number\",\"parent_account_status\",\"parent_account_currency\",\"parent_account_available_balance_currency\",\"parent_account_available_balance_amount\",\"parent_account_account_sub_type\",\"parent_account_owners_0_display_name\",\"parent_account_owners_0_account_holder_type\",\"settlement_account_account_id\",\"settlement_account_cif\",\"settlement_account_account_number\",\"settlement_account_status\",\"settlement_account_currency\",\"settlement_account_available_balance_currency\",\"settlement_account_available_balance_amount\",\"settlement_account_account_sub_type\",\"settlement_account_owners_0_display_name\",\"settlement_account_owners_0_account_holder_type\"", "\"1000327642\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"T1 Project Alpha Escrow\",\"New Title T2\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"T12cc62d3fb446e7950ffd0797d0a6f41\",\"1990-05-15T00:00:00\",\"Native Name\",\"False\",\"2025-06-20\",\"2025-07-25T08:23:00Z\",\"1000326956-2000365\",\"2000365\",\"1000326956\",\"AUTH\",\"USD\",\"USD\",\"0\",\"CMS Parent Cate\",\"GLOB-INVEST BOND FUND LTD\",\"Primary\",\"1000326948-2000365\",\"2000365\",\"1000326948\",\"AUTH\",\"USD\",\"USD\",\"0\",\"CMS Settlement\",\"GLOB-INVEST BOND FUND LTD\",\"Primary\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - The virtual account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-a-virtual-account" ] }, { "Authorization": [] } ] } }, "/v2/virtual-accounts": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Create Virtual Accounts (V2)", "description": "Creates one or more virtual (sub) accounts using the v2 request schema.\n \n**V2 difference:** For allocated accounts (`unallocated = false`), `dob` and `nationality` are required.\n`dob` must be a past date and at least 18 years in the past.\n`taxIdentificationNumber` and `countryOfResidence` are optional additional KYC fields. `nativeLanguageName`,\n`clientReference`, callback handling, and batch job semantics behave the same as v1.\n \n**Required Request Properties**\n- **items**: Array of virtual account creation requests (minimum 1, maximum 1000)\n - **currency**: ISO-4217 currency code for the virtual account (e.g., USD, BMD)\n - **accountHolderName**: Human-readable label for the virtual account (required unless `unallocated` is true). **Immutable after first update.**\n - **accountName**: Official account title that will appear on statements (required unless `unallocated` is true). **Immutable after first update.**\n - **Allowed characters (accountHolderName, accountName)**: A-Z, a-z, 0-9, space, and `! \" # $ % & ' ( ) * + , - . / [ \\ ]`. Common symbols such as `_ @ : ; ? { }` are not allowed.\n - **dob**: Required for allocated accounts. Must be an ISO 8601 date string in the past, and at least 18 years in the past. **Immutable after first update.**\n - **nationality**: Required for allocated accounts. Must be an ISO 3166-1 alpha-2 country code. **Immutable after first update.**\n \n**Optional Request Properties**\n- **taxIdentificationNumber**: Optional customer tax identifier (max 255 characters)\n- **countryOfResidence**: Optional ISO 3166-1 alpha-2 country code\n- **nativeLanguageName**: Native name of the account holder's language, if applicable (max 255 characters). **Immutable after first update.**\n- **unallocated**: When set to `true`, creates the account in \"for allocation\" mode and defers the mandatory v2 KYC fields until the one-time allocation PATCH.\n- **callbackUrl**: URL to receive notifications when the batch job completes (optional)\n- **clientReference**: External reference provided by the client to aid reconciliation (max 35 characters) - per item\n- **customHeaders**: Object of string key/value pairs to be echoed back in the completion callback. Limits: up to 10 headers; each key ≤ 50 characters; each value ≤ 500 characters.\n \n### Unallocated Accounts\nWhen `unallocated` is `true`, the batch can pre-create accounts for later assignment.\nThe required v2 customer fields (`dob` and `nationality`) are enforced when the account is allocated via PATCH rather than during creation.\n \n### Asynchronous Processing\nThis endpoint queues a background job and immediately returns job tracking URLs.\n \n### Message Signing\nCallback notifications are signed using the same rules and headers as v1.\n \n### Job Status Tracking\nThe response includes a job ID plus status and result URLs for monitoring completion.\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n \n### Base URL\nAll API requests use the versioned base URL:\n \n https://api.bcb.bm/v2/virtual-accounts\n \n### Idempotency\nIdempotency behaviour is identical to v1.\n\n**Required Permission:** `create-virtual-account`\n\nThis endpoint requires the permission claim `create-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_PostV2", "requestBody": { "x-name": "request", "description": "Batch request containing v2 virtual account creation items, optional callback URL, and optional custom headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountCreateBatchRequestV2" }, "example": { "callbackUrl": "https://my-callback-url.com", "customHeaders": { "X-Custom-Header-1": "Custom Value 1", "X-Custom-Header-2": "Custom Value 2" }, "items": [ { "currency": "USD", "unallocated": true, "clientReference": "BATCH-UNALLOC-V2-001" }, { "currency": "USD", "accountHolderName": "Acme Corporation", "accountName": "Acme Trading Account", "clientReference": "BATCH-V2-REF-001", "dob": "1985-04-23T00:00:00.0000000", "nationality": "HK", "taxIdentificationNumber": "TIN-001", "countryOfResidence": "BM", "nativeLanguageName": "Native Name", "unallocated": false } ] } } }, "x-position": 1 }, "responses": { "202": { "description": "Accepted - Virtual account creation job has been queued for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" }, "example": { "jobId": "550e8400-e29b-41d4-a716-446655440001", "status": "Pending", "statusUrl": "https://api.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001", "resultUrl": "https://api.bcb.bm/v1/jobs/550e8400-e29b-41d4-a716-446655440001/results" } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "create-virtual-account" ] }, { "Authorization": [] } ] }, "get": { "tags": [ "Virtual Accounts" ], "summary": "Get All Virtual Accounts", "description": "Retrieves all virtual accounts for the authenticated corporate client. This endpoint:\n\n- Returns a paginated list of virtual accounts for the client\n- Response contains the client’s real (non-virtual) accounts as well:\n- **Settlement Account** – the primary clearing account used for cash movements. Account category: \"CMS Settlement\".\n- **Parent Account** – the parent account under which all virtual accounts are organised. Account category: \"CMS Parent Cate\".\n- **Virtual accounts** have the category \"CMS Sub Acct\".\n- Supports optional currency filtering to return only accounts in a specific currency\n- **Supports pagination** for efficient handling of large account datasets\n\n### Filtering\nUse the optional `currency` query parameter to filter results:\n- Must be a valid 3-letter ISO currency code (e.g., USD, BMD, EUR)\n- If omitted, accounts in all currencies are returned\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including pageSize, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getAllVirtualAccounts(currency = null, pageSize = 25, pageStart = 1, pageToken = null) {\n try {\n // Build URL with optional parameters\n let url = 'https://api.bcb.bm/v1/virtual-accounts';\n const params = new URLSearchParams();\n \n if (currency) {\n params.append('currency', currency);\n }\n \n if (pageStart === 1 && !pageToken) {\n // First request only: optionally specify pageSize\n params.append('pageSize', pageSize.toString());\n } else {\n // Subsequent requests: use pageToken + pageStart and do NOT send pageSize again\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n url += '?' + params.toString();\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Virtual accounts retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n\n // Access pagination info\n const pagination = result.meta.pagination;\n console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);\n\n // Process virtual accounts\n result.data.forEach((account, index) => {\n console.log(`Account ${index + 1}:`);\n console.log(` Virtual Account Number: ${account.virtualAccountNumber}`);\n console.log(` BIC: ${account.bicCode}`);\n console.log(` BIC (FX): ${account.bicCodeFx}`);\n console.log(` Account Holder: ${account.accountHolderName}`);\n console.log(` Account Name: ${account.accountName}`);\n console.log(` Currency: ${account.currency}`);\n console.log(` Balance: ${account.balance ? account.balance.amount + ' ' + account.balance.currency : 'N/A'}`);\n console.log(` Category: ${account.category}`);\n \n if (account.clientReference) {\n console.log(` Client Reference: ${account.clientReference}`);\n }\n \n if (account.effectiveDate) {\n console.log(` Effective Date: ${account.effectiveDate}`);\n }\n \n if (account.createdAt) {\n console.log(` Created At: ${account.createdAt}`);\n }\n \n // Log parent/settlement account relationships\n if (account.parentAccount) {\n console.log(` Parent Account: ${account.parentAccount.accountNumber} (${account.parentAccount.accountName})`);\n }\n if (account.settlementAccount) {\n console.log(` Settlement Account: ${account.settlementAccount.accountNumber} (${account.settlementAccount.accountName})`);\n }\n \n console.log('---');\n });\n\n return result;\n } catch (error) {\n console.error('Failed to retrieve virtual accounts:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get all virtual accounts\ngetAllVirtualAccounts();\n\n// Get only USD virtual accounts\ngetAllVirtualAccounts('USD');\n\n// Get first 10 virtual accounts\ngetAllVirtualAccounts(null, 10);\n```\n\n**Required Permission:** `get-virtual-accounts`\n\nThis endpoint requires the permission claim `get-virtual-accounts` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_GetAll2", "parameters": [ { "name": "currency", "in": "query", "description": "Optional. The currency of the virtual accounts to filter by. If not specified, all virtual accounts will be returned.", "schema": { "type": "string", "maxLength": 3, "minLength": 0, "nullable": true }, "x-position": 1 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 2 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 3 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 4 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfVirtualAccountOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "202506234881430088.01,99", "totalSize": 7, "pageSize": 99 } }, "data": [ { "virtualAccountNumber": 1000326948, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Global Investment Fund Ltd", "accountName": "Settlement Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Settlement", "clientReference": "SETTLE-REF-001", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": "Native Name", "unallocated": false }, { "virtualAccountNumber": 1000326956, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Global Investment Fund Ltd", "accountName": "Parent Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Parent Cate", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327057, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Corporate Treasury Holdings", "accountName": "Sub Account Operations", "currency": "USD", "balance": { "currency": "USD", "amount": 130492.24 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327073, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Asset Management Services", "accountName": "Sub Account Operations", "currency": "USD", "balance": { "currency": "USD", "amount": 100776.49 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327197, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Project Alpha Escrow", "accountName": "Project Alpha Virtual Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327642, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "Treasury Operations Ltd", "accountName": "Enhanced Operations Account", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": null, "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": false }, { "virtualAccountNumber": 1000327887, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "UNALLOCATED", "accountName": "UNALLOCATED", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": "UNALLOCATED-003", "dateOfBirth": null, "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": null, "unallocated": true } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_virtual_account_number\",\"data_0_bic_code\",\"data_0_bic_code_fx\",\"data_0_account_holder_name\",\"data_0_account_name\",\"data_0_currency\",\"data_0_balance_currency\",\"data_0_balance_amount\",\"data_0_category\",\"data_0_client_reference\",\"data_0_dob\",\"data_0_native_language_name\",\"data_0_unallocated\",\"data_1_virtual_account_number\",\"data_1_bic_code\",\"data_1_bic_code_fx\",\"data_1_account_holder_name\",\"data_1_account_name\",\"data_1_currency\",\"data_1_balance_currency\",\"data_1_balance_amount\",\"data_1_category\",\"data_1_unallocated\",\"data_2_virtual_account_number\",\"data_2_bic_code\",\"data_2_bic_code_fx\",\"data_2_account_holder_name\",\"data_2_account_name\",\"data_2_currency\",\"data_2_balance_currency\",\"data_2_balance_amount\",\"data_2_category\",\"data_2_unallocated\",\"data_3_virtual_account_number\",\"data_3_bic_code\",\"data_3_bic_code_fx\",\"data_3_account_holder_name\",\"data_3_account_name\",\"data_3_currency\",\"data_3_balance_currency\",\"data_3_balance_amount\",\"data_3_category\",\"data_3_unallocated\",\"data_4_virtual_account_number\",\"data_4_bic_code\",\"data_4_bic_code_fx\",\"data_4_account_holder_name\",\"data_4_account_name\",\"data_4_currency\",\"data_4_balance_currency\",\"data_4_balance_amount\",\"data_4_category\",\"data_4_unallocated\",\"data_5_virtual_account_number\",\"data_5_bic_code\",\"data_5_bic_code_fx\",\"data_5_account_holder_name\",\"data_5_account_name\",\"data_5_currency\",\"data_5_balance_currency\",\"data_5_balance_amount\",\"data_5_category\",\"data_5_unallocated\",\"data_6_virtual_account_number\",\"data_6_bic_code\",\"data_6_bic_code_fx\",\"data_6_account_holder_name\",\"data_6_account_name\",\"data_6_currency\",\"data_6_balance_currency\",\"data_6_balance_amount\",\"data_6_category\",\"data_6_client_reference\",\"data_6_unallocated\"", "\"1\",\"202506234881430088.01,99\",\"7\",\"99\",\"1000326948\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Global Investment Fund Ltd\",\"Settlement Account\",\"USD\",\"USD\",\"0\",\"CMS Settlement\",\"SETTLE-REF-001\",\"1990-05-15T00:00:00\",\"Native Name\",\"False\",\"1000326956\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Global Investment Fund Ltd\",\"Parent Account\",\"USD\",\"USD\",\"0\",\"CMS Parent Cate\",\"False\",\"1000327057\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Corporate Treasury Holdings\",\"Sub Account Operations\",\"USD\",\"USD\",\"130492.24\",\"CMS Sub Acct\",\"False\",\"1000327073\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Asset Management Services\",\"Sub Account Operations\",\"USD\",\"USD\",\"100776.49\",\"CMS Sub Acct\",\"False\",\"1000327197\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Project Alpha Escrow\",\"Project Alpha Virtual Account\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"False\",\"1000327642\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"Treasury Operations Ltd\",\"Enhanced Operations Account\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"False\",\"1000327887\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"UNALLOCATED\",\"UNALLOCATED\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"UNALLOCATED-003\",\"True\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - No virtual accounts were found for the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-accounts" ] }, { "Authorization": [] } ] } }, "/v2/virtual-accounts/{virtualAccountNumber}": { "patch": { "tags": [ "Virtual Accounts" ], "summary": "Update Virtual Account (V2)", "description": "Updates an existing virtual account using the v2 schema. Only the fields provided in the request body will be updated.\n \n**V2 difference:** In addition to the v1 fields, the v2 schema supports `nationality`,\n`taxIdentificationNumber`, and `countryOfResidence`.\n \n**Updatable Properties**\n- **accountHolderName**: Human-readable label for the virtual account. **Immutable after first update** – can only be changed once from the \"UNALLOCATED\" state.\n- **accountName**: Official account title that will appear on statements. **Immutable after first update** – can only be changed once from the \"UNALLOCATED\" state.\n- **Allowed characters (accountHolderName, accountName)**: A-Z, a-z, 0-9, space, and `! \" # $ % & ' ( ) * + , - . / [ \\ ]`. Common symbols such as `_ @ : ; ? { }` are not allowed.\n- **dob**: Date of birth of the account holder. The effective v2 account state must contain a DOB after the patch, and any supplied DOB must be in the past and at least 18 years in the past. **Immutable after first update.**\n- **nationality**: ISO 3166-1 alpha-2 nationality. The effective v2 account state must contain a nationality after the patch. **Immutable after first update.**\n- **taxIdentificationNumber**: Optional tax identifier for the account holder (max 255 characters)\n- **countryOfResidence**: Optional ISO 3166-1 alpha-2 country code\n- **nativeLanguageName**: Native name of the account holder's language (max 255 characters). **Immutable after first update.**\n- **clientReference**: External reference provided by the client to aid reconciliation (max 35 characters). This field can be updated multiple times.\n \n### Allocating Unallocated Accounts\nFor virtual accounts created with `unallocated: true`, use this endpoint to perform a **one-time** assignment to a real end-customer.\n \n### Validation Rules\nFor v2 updates, the final effective account state after applying the PATCH must contain valid `dob` and `nationality`.\nThis means a request can rely on stored values that are already present, but the update will fail if the merged result\nwould still leave either field missing or invalid.\nWhen allocating an unallocated account, `accountHolderName` and `accountName` must still be supplied.\n`taxIdentificationNumber`, `countryOfResidence`, and `nativeLanguageName` remain optional additional profile fields.\nOnce immutable customer profile fields have been set, later attempts to change them may result in a `409 Conflict`.\n`clientReference` remains the only field intended for ongoing updates after allocation or first profile update.\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n \n### Base URL\nAll API requests use the versioned base URL:\n \n https://api.bcb.bm/v2/virtual-accounts\n \n### Idempotency\nIdempotency behaviour is identical to v1.\n\n**Required Permission:** `update-virtual-account`\n\nThis endpoint requires the permission claim `update-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_PatchV2", "parameters": [ { "name": "virtualAccountNumber", "in": "path", "required": true, "description": "Virtual account identifier (ID) that uniquely identifies the virtual account", "schema": { "type": "string" }, "x-position": 1, "example": { "accountHolderName": "Acme Corporation", "accountName": "Acme Trading Account", "clientReference": "updated-reference-v2", "dob": "1985-04-23T00:00:00.0000000", "nationality": "HK", "taxIdentificationNumber": "TIN-001", "countryOfResidence": "BM", "nativeLanguageName": "Native Name" } } ], "requestBody": { "x-name": "request", "description": "Payload containing v2 virtual account fields to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountUpdateRequestV2" }, "example": { "accountHolderName": "Acme Corporation", "accountName": "Acme Trading Account", "clientReference": "updated-reference-v2", "dob": "1985-04-23T00:00:00.0000000", "nationality": "HK", "taxIdentificationNumber": "TIN-001", "countryOfResidence": "BM", "nativeLanguageName": "Native Name" } } }, "x-position": 2 }, "responses": { "200": { "description": "Virtual account updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDetails" }, "example": { "effectiveDate": "2025-06-20", "createdAt": "2025-07-25T08:23:00.0000000Z", "parentAccount": { "accountId": "1000326956-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Parent Cate", "accountNumber": 1000326956, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "settlementAccount": { "accountId": "1000326948-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Settlement", "accountNumber": 1000326948, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "virtualAccountNumber": 1000327642, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "T1 Project Alpha Escrow", "accountName": "New Title T2", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": "T12cc62d3fb446e7950ffd0797d0a6f41", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": "Native Name", "unallocated": false } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Virtual account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict – Immutable or locked customer profile fields cannot be changed after allocation or first update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "update-virtual-account" ] }, { "Authorization": [] } ] }, "get": { "tags": [ "Virtual Accounts" ], "summary": "Get Virtual Account Details", "description": "Retrieves comprehensive information about a specific virtual account, including all its sub-accounts, parent account details, and settlement account information. This endpoint:\n\n- Returns the virtual account details as a single object\n- Includes parent account information (the account this virtual account is derived from)\n- Provides settlement account details (the account used for settlement operations)\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{accountNumber}\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getVirtualAccountDetails(accountNumber) {\n try {\n const url = `https://api.bcb.bm/v1/virtual-accounts/${encodeURIComponent(accountNumber)}`;\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Virtual account details retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n\n // Get the virtual account details (single object, not an array)\n const virtualAccount = result.data;\n console.log('Virtual Account Details:');\n console.log(` Account Number: ${virtualAccount.virtualAccountNumber}`);\n console.log(` BIC: ${virtualAccount.bicCode}`);\n console.log(` BIC (FX): ${virtualAccount.bicCodeFx}`);\n console.log(` Account Holder: ${virtualAccount.accountHolderName}`);\n console.log(` Account Name: ${virtualAccount.accountName}`);\n console.log(` Currency: ${virtualAccount.currency}`);\n console.log(` Category: ${virtualAccount.category}`);\n \n if (virtualAccount.balance) {\n console.log(` Balance: ${virtualAccount.balance.amount} ${virtualAccount.balance.currency}`);\n }\n \n console.log(` Effective Date: ${virtualAccount.effectiveDate}`);\n console.log(` Created: ${virtualAccount.createdAt}`);\n \n if (virtualAccount.clientReference) {\n console.log(` Client Reference: ${virtualAccount.clientReference}`);\n }\n \n // Log parent account details\n if (virtualAccount.parentAccount) {\n console.log(' Parent Account:');\n console.log(` Account Number: ${virtualAccount.parentAccount.accountNumber}`);\n console.log(` Account ID: ${virtualAccount.parentAccount.accountId}`);\n console.log(` CIF: ${virtualAccount.parentAccount.cif}`);\n console.log(` Currency: ${virtualAccount.parentAccount.currency}`);\n console.log(` Sub Type: ${virtualAccount.parentAccount.accountSubType}`);\n console.log(` Status: ${virtualAccount.parentAccount.status}`);\n if (virtualAccount.parentAccount.availableBalance) {\n console.log(` Available Balance: ${virtualAccount.parentAccount.availableBalance.amount} ${virtualAccount.parentAccount.availableBalance.currency}`);\n }\n if (virtualAccount.parentAccount.owners && virtualAccount.parentAccount.owners.length > 0) {\n console.log(` Owner: ${virtualAccount.parentAccount.owners[0].displayName} (${virtualAccount.parentAccount.owners[0].accountHolderType})`);\n }\n }\n \n // Log settlement account details\n if (virtualAccount.settlementAccount) {\n console.log(' Settlement Account:');\n console.log(` Account Number: ${virtualAccount.settlementAccount.accountNumber}`);\n console.log(` Account ID: ${virtualAccount.settlementAccount.accountId}`);\n console.log(` CIF: ${virtualAccount.settlementAccount.cif}`);\n console.log(` Currency: ${virtualAccount.settlementAccount.currency}`);\n console.log(` Sub Type: ${virtualAccount.settlementAccount.accountSubType}`);\n console.log(` Status: ${virtualAccount.settlementAccount.status}`);\n if (virtualAccount.settlementAccount.availableBalance) {\n console.log(` Available Balance: ${virtualAccount.settlementAccount.availableBalance.amount} ${virtualAccount.settlementAccount.availableBalance.currency}`);\n }\n if (virtualAccount.settlementAccount.owners && virtualAccount.settlementAccount.owners.length > 0) {\n console.log(` Owner: ${virtualAccount.settlementAccount.owners[0].displayName} (${virtualAccount.settlementAccount.owners[0].accountHolderType})`);\n }\n }\n\n return result;\n } catch (error) {\n console.error('Failed to retrieve virtual account details:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get details for a specific virtual account\ngetVirtualAccountDetails('1000326808');\n```\n\n**Required Permission:** `get-a-virtual-account`\n\nThis endpoint requires the permission claim `get-a-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccounts_GetDetails2", "parameters": [ { "name": "virtualAccountNumber", "in": "path", "required": true, "description": "The virtual account number assigned by the bank.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDetails" }, "examples": { "Json": { "value": { "effectiveDate": "2025-06-20", "createdAt": "2025-07-25T08:23:00.0000000Z", "parentAccount": { "accountId": "1000326956-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Parent Cate", "accountNumber": 1000326956, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "settlementAccount": { "accountId": "1000326948-2000365", "cif": 2000365, "currency": "USD", "accountSubType": "CMS Settlement", "accountNumber": 1000326948, "status": "AUTH", "availableBalance": { "currency": "USD", "amount": 0 }, "accountType": null, "nickname": null, "owners": [ { "displayName": "GLOB-INVEST BOND FUND LTD", "accountHolderType": "Primary" } ], "accountAttributes": [] }, "virtualAccountNumber": 1000327642, "bicCode": "BPBKBMHMXXX", "bicCodeFx": "BEOEBMH2", "accountHolderName": "T1 Project Alpha Escrow", "accountName": "New Title T2", "currency": "USD", "balance": { "currency": "USD", "amount": 0 }, "category": "CMS Sub Acct", "clientReference": "T12cc62d3fb446e7950ffd0797d0a6f41", "dateOfBirth": "1990-05-15T00:00:00.0000000", "nationality": null, "taxIdentificationNumber": null, "countryOfResidence": null, "nativeLanguageName": "Native Name", "unallocated": false } }, "Csv": { "value": [ "\"virtual_account_number\",\"bic_code\",\"bic_code_fx\",\"account_holder_name\",\"account_name\",\"currency\",\"balance_currency\",\"balance_amount\",\"category\",\"client_reference\",\"dob\",\"native_language_name\",\"unallocated\",\"effective_date\",\"created_at\",\"parent_account_account_id\",\"parent_account_cif\",\"parent_account_account_number\",\"parent_account_status\",\"parent_account_currency\",\"parent_account_available_balance_currency\",\"parent_account_available_balance_amount\",\"parent_account_account_sub_type\",\"parent_account_owners_0_display_name\",\"parent_account_owners_0_account_holder_type\",\"settlement_account_account_id\",\"settlement_account_cif\",\"settlement_account_account_number\",\"settlement_account_status\",\"settlement_account_currency\",\"settlement_account_available_balance_currency\",\"settlement_account_available_balance_amount\",\"settlement_account_account_sub_type\",\"settlement_account_owners_0_display_name\",\"settlement_account_owners_0_account_holder_type\"", "\"1000327642\",\"BPBKBMHMXXX\",\"BEOEBMH2\",\"T1 Project Alpha Escrow\",\"New Title T2\",\"USD\",\"USD\",\"0\",\"CMS Sub Acct\",\"T12cc62d3fb446e7950ffd0797d0a6f41\",\"1990-05-15T00:00:00\",\"Native Name\",\"False\",\"2025-06-20\",\"2025-07-25T08:23:00Z\",\"1000326956-2000365\",\"2000365\",\"1000326956\",\"AUTH\",\"USD\",\"USD\",\"0\",\"CMS Parent Cate\",\"GLOB-INVEST BOND FUND LTD\",\"Primary\",\"1000326948-2000365\",\"2000365\",\"1000326948\",\"AUTH\",\"USD\",\"USD\",\"0\",\"CMS Settlement\",\"GLOB-INVEST BOND FUND LTD\",\"Primary\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - The virtual account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-a-virtual-account" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{virtualAccountNumber}/transactions": { "get": { "tags": [ "Virtual Accounts" ], "summary": "Virtual Account Transactions", "description": "Retrieves transaction entries for a specific virtual (sub) account within a given date range.\nThis endpoint:\n\n- Validates the provided date parameters. Accepted formats: `yyyy-MM-dd` or `yyyyMMdd`.\n- Supports a maximum date range of one year.\n- Supports both JSON and CSV response formats based on the Accept header.\n- Uses cursor-based pagination with server-side result-set management.\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including `pageSize`, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{virtualAccountNumber}/transactions\n\n### Sample Request in JavaScript\n```javascript\n// Get first page\nasync function getVirtualAccountTransactions(virtualAccountNumber, fromDate, toDate) {\n const url = new URL(`https://api.bcb.bm/v1/virtual-accounts/${encodeURIComponent(virtualAccountNumber)}/transactions`);\n url.searchParams.set('fromDate', fromDate); // yyyy-MM-dd or yyyyMMdd\n url.searchParams.set('toDate', toDate); // yyyy-MM-dd or yyyyMMdd\n url.searchParams.set('pageSize', '100'); // optional (first call only)\n\n const response = await fetch(url.toString(), {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(`Failed to get VA transactions: ${error.message || 'Unknown error'}`);\n }\n\n const result = await response.json();\n // result.meta.pagination: { page_start, page_token, total_size, page_size }\n // result.data: Array of VA transactions\n // Example: inspect first item\n if (result.data?.length) {\n const t = result.data[0];\n console.log('Tx:', t.id, t.description, t.valueDate, t.value?.amount, t.value?.currency, t.debitAccountNumber?.number, t.creditAccountNumber?.number);\n }\n return result;\n}\n\n// Paginate through all pages\nasync function getAllVirtualAccountTransactions(virtualAccountNumber, fromDate, toDate) {\n let pageStart = 1;\n let pageToken = null;\n let totalPages = 0;\n const all = [];\n\n do {\n const url = new URL(`https://api.bcb.bm/v1/virtual-accounts/${encodeURIComponent(virtualAccountNumber)}/transactions`);\n url.searchParams.set('fromDate', fromDate);\n url.searchParams.set('toDate', toDate);\n if (pageStart === 1) {\n url.searchParams.set('pageSize', '100'); // first call only\n } else {\n url.searchParams.set('pageStart', String(pageStart));\n url.searchParams.set('pageToken', pageToken);\n }\n\n const res = await fetch(url.toString(), {\n headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Accept': 'application/json' }\n });\n if (!res.ok) throw new Error('Request failed');\n const body = await res.json();\n\n if (pageStart === 1) {\n const p = body.meta?.pagination;\n pageToken = p?.page_token;\n totalPages = Math.ceil((p?.total_size ?? 0) / (p?.page_size ?? 100));\n console.log('First page meta:', p);\n }\n\n if (Array.isArray(body.data)) all.push(...body.data);\n pageStart++;\n } while (pageStart <= totalPages);\n\n return all;\n}\n```\n\n**Required Permission:** `get-virtual-account-transactions`\n\nThis endpoint requires the permission claim `get-virtual-account-transactions` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransactions_Get", "parameters": [ { "name": "virtualAccountNumber", "in": "path", "required": true, "description": "Virtual account identifier (number) to retrieve transactions for.", "schema": { "type": "string" }, "x-position": 1 }, { "name": "fromDate", "in": "query", "required": true, "description": "The start date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 2 }, { "name": "toDate", "in": "query", "required": true, "description": "The end date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 3 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 4 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 5 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 6 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfVirtualAccountTransactionDetailOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "202511150823456789.01,4", "totalSize": 4, "pageSize": 4 } }, "data": [ { "debitAccountNumber": { "number": 8901234567, "accountRoutings": [ { "scheme": "BankId", "address": "CITIBANK N.A. NEW YORK" }, { "scheme": "AccountDetails", "address": "GLOBAL TECH SOLUTIONS INC 455 MARKET STREET SAN FRANCISCO CA 94105" } ] }, "creditAccountNumber": { "number": 2000445678, "accountRoutings": [] }, "status": "Completed", "counterpartyReference": null, "id": "FT25319ABC12", "description": "WIRE TRANSFER FROM CORRESPONDENT BANK", "bookingDate": "2025-11-15", "valueDate": "2025-11-15", "value": { "currency": "USD", "amount": 25000 }, "proprietaryBankTransactionCode": "Inward Swift Payment" }, { "debitAccountNumber": { "number": 2000445678, "accountRoutings": [] }, "creditAccountNumber": { "number": 4567890123, "accountRoutings": [ { "scheme": "BankId", "address": "HSBC BANK USA N.A. NEW YORK" }, { "scheme": "AccountDetails", "address": "ATLANTIC SHIPPING CORP 89 WATER STREET HAMILTON HM12 BERMUDA" } ] }, "status": "Completed", "counterpartyReference": null, "id": "FT25319XYZ45", "description": "SWIFT TRANSFER OUT FROM SUBACCOUNT", "bookingDate": "2025-11-14", "valueDate": "2025-11-14", "value": { "currency": "USD", "amount": -100.5 }, "proprietaryBankTransactionCode": "Debit Arrangement" }, { "debitAccountNumber": { "number": 2000123456, "accountRoutings": [ { "scheme": "AccountDetails", "address": "MERIDIAN CAPITAL PARTNERS LTD 12 CHURCH STREET HAMILTON HM11 BERMUDA" } ] }, "creditAccountNumber": { "number": 2000445678, "accountRoutings": [] }, "status": "Completed", "counterpartyReference": null, "id": "FT25318DEF78", "description": "INTERNAL TRANSFER BETWEEN ACCOUNTS", "bookingDate": "2025-11-13", "valueDate": "2025-11-13", "value": { "currency": "USD", "amount": 15750.25 }, "proprietaryBankTransactionCode": "Transfer in" }, { "debitAccountNumber": { "number": 2000445678, "accountRoutings": [] }, "creditAccountNumber": { "number": 7654321098, "accountRoutings": [ { "scheme": "BankId", "address": "BANK OF AMERICA N.A. CHARLOTTE" }, { "scheme": "AccountDetails", "address": "PACIFIC TRADING COMPANY 2301 BUSINESS PARK DRIVE SEATTLE WA 98108" } ] }, "status": "Completed", "counterpartyReference": null, "id": "FT25317GHI90", "description": "ACH PAYMENT TO VENDOR", "bookingDate": "2025-11-12", "valueDate": "2025-11-12", "value": { "currency": "USD", "amount": -8920 }, "proprietaryBankTransactionCode": "Debit Arrangement" } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_debit_account_number_number\",\"data_0_debit_account_number_account_routings_0_scheme\",\"data_0_debit_account_number_account_routings_0_address\",\"data_0_debit_account_number_account_routings_1_scheme\",\"data_0_debit_account_number_account_routings_1_address\",\"data_0_credit_account_number_number\",\"data_0_status\",\"data_0_id\",\"data_0_description\",\"data_0_booking_date\",\"data_0_value_date\",\"data_0_value_currency\",\"data_0_value_amount\",\"data_0_proprietary_bank_transaction_code\",\"data_1_debit_account_number_number\",\"data_1_credit_account_number_number\",\"data_1_credit_account_number_account_routings_0_scheme\",\"data_1_credit_account_number_account_routings_0_address\",\"data_1_credit_account_number_account_routings_1_scheme\",\"data_1_credit_account_number_account_routings_1_address\",\"data_1_status\",\"data_1_id\",\"data_1_description\",\"data_1_booking_date\",\"data_1_value_date\",\"data_1_value_currency\",\"data_1_value_amount\",\"data_1_proprietary_bank_transaction_code\",\"data_2_debit_account_number_number\",\"data_2_debit_account_number_account_routings_0_scheme\",\"data_2_debit_account_number_account_routings_0_address\",\"data_2_credit_account_number_number\",\"data_2_status\",\"data_2_id\",\"data_2_description\",\"data_2_booking_date\",\"data_2_value_date\",\"data_2_value_currency\",\"data_2_value_amount\",\"data_2_proprietary_bank_transaction_code\",\"data_3_debit_account_number_number\",\"data_3_credit_account_number_number\",\"data_3_credit_account_number_account_routings_0_scheme\",\"data_3_credit_account_number_account_routings_0_address\",\"data_3_credit_account_number_account_routings_1_scheme\",\"data_3_credit_account_number_account_routings_1_address\",\"data_3_status\",\"data_3_id\",\"data_3_description\",\"data_3_booking_date\",\"data_3_value_date\",\"data_3_value_currency\",\"data_3_value_amount\",\"data_3_proprietary_bank_transaction_code\"", "\"1\",\"202511150823456789.01,4\",\"4\",\"4\",\"8901234567\",\"BankId\",\"CITIBANK N.A. NEW YORK\",\"AccountDetails\",\"GLOBAL TECH SOLUTIONS INC 455 MARKET STREET SAN FRANCISCO CA 94105\",\"2000445678\",\"Completed\",\"FT25319ABC12\",\"WIRE TRANSFER FROM CORRESPONDENT BANK\",\"2025-11-15\",\"2025-11-15\",\"USD\",\"25000.00\",\"Inward Swift Payment\",\"2000445678\",\"4567890123\",\"BankId\",\"HSBC BANK USA N.A. NEW YORK\",\"AccountDetails\",\"ATLANTIC SHIPPING CORP 89 WATER STREET HAMILTON HM12 BERMUDA\",\"Completed\",\"FT25319XYZ45\",\"SWIFT TRANSFER OUT FROM SUBACCOUNT\",\"2025-11-14\",\"2025-11-14\",\"USD\",\"-100.50\",\"Debit Arrangement\",\"2000123456\",\"AccountDetails\",\"MERIDIAN CAPITAL PARTNERS LTD 12 CHURCH STREET HAMILTON HM11 BERMUDA\",\"2000445678\",\"Completed\",\"FT25318DEF78\",\"INTERNAL TRANSFER BETWEEN ACCOUNTS\",\"2025-11-13\",\"2025-11-13\",\"USD\",\"15750.25\",\"Transfer in\",\"2000445678\",\"7654321098\",\"BankId\",\"BANK OF AMERICA N.A. CHARLOTTE\",\"AccountDetails\",\"PACIFIC TRADING COMPANY 2301 BUSINESS PARK DRIVE SEATTLE WA 98108\",\"Completed\",\"FT25317GHI90\",\"ACH PAYMENT TO VENDOR\",\"2025-11-12\",\"2025-11-12\",\"USD\",\"-8920.00\",\"Debit Arrangement\"" ] } } } } }, "400": { "description": "Bad Request - Validation failed (e.g., invalid date range, invalid pagination token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required or token is invalid/expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-account-transactions" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/transaction/report": { "get": { "tags": [ "Virtual Accounts" ], "summary": "Virtual Account Transaction Report", "description": "Retrieves a transaction report for all virtual (sub) accounts belonging to the authenticated customer within a given date range.\n\n**Response shape**\n- The endpoint returns a JSON object with `meta` and `data` fields.\n- `meta.pagination` contains pagination metadata (cursor-based).\n- `data` contains the **raw CSV report content** as a single string (RFC4180, CRLF line endings).\n\n**Note**: This endpoint does **not** return an array of transaction objects. The report is provided as CSV text inside the JSON envelope.\n\nThis endpoint:\n\n- Validates the provided date parameters. Accepted formats: `yyyy-MM-dd` or `yyyyMMdd`.\n- Supports a maximum date range of one year.\n- Uses cursor-based pagination with server-side result-set management.\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including pageSize, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\n- Set `Accept: application/json` to receive the JSON envelope where `data` is the raw CSV report string.\n- If you request `Accept: text/csv`, the platform CSV formatter will attempt to serialize the *entire response object* as CSV,\n which is different from returning the report payload itself. For the raw report content, use `application/json`.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/transaction/report\n\n### Sample Request in JavaScript\n```javascript\n// Fetch the report (JSON envelope, report CSV in result.data)\nasync function getVirtualAccountTransactionsReport(fromDate, toDate) {\n const url = new URL(`https://api.bcb.bm/v1/virtual-accounts/transaction/report`);\n url.searchParams.set('fromDate', fromDate); // yyyy-MM-dd or yyyyMMdd\n url.searchParams.set('toDate', toDate); // yyyy-MM-dd or yyyyMMdd\n\n const response = await fetch(url.toString(), {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(`Failed to get VA transaction report: ${error.message || 'Unknown error'}`);\n }\n\n const result = await response.json();\n // result.meta.pagination: { page_start, page_token, total_size, page_size }\n // result.data: raw CSV report string (may include header + summary sections)\n const csvText = result.data || '';\n console.log(csvText);\n return result;\n}\n\n// Download the CSV report from the JSON envelope\nasync function downloadVirtualAccountTransactionsReport(fromDate, toDate) {\n const { data: csvText } = await getVirtualAccountTransactionsReport(fromDate, toDate);\n const blob = new Blob([csvText || ''], { type: 'text/csv;charset=utf-8' });\n const a = document.createElement('a');\n a.href = URL.createObjectURL(blob);\n a.download = `vas-transaction-report-${fromDate}-${toDate}.csv`;\n a.click();\n URL.revokeObjectURL(a.href);\n}\n```\n\n**Required Permission:** `get-virtual-account-transactions`\n\nThis endpoint requires the permission claim `get-virtual-account-transactions` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransactions_GetReport", "parameters": [ { "name": "fromDate", "in": "query", "required": true, "description": "The start date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 1 }, { "name": "toDate", "in": "query", "required": true, "description": "The end date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 2 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 3 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 4 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 5 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfString" }, "example": { "meta": { "pagination": { "pageStart": 1, "pageToken": null, "totalSize": 20, "pageSize": 20 } }, "data": "Reference,Date,Time,Transaction Type,From Account,To Account,Direction,Amount,Currency,Customer Name,Sub Account,Leg,Settlement Balance\n=== VAS TRANSACTION REPORT (***DUMMY DATA***) ===,2025-12-01 to 2025-12-31,,,,,,,,,,,,Opening Balance: 0.00 USD\n---,---,---,---,---,---,---,---,---,---,---,---,---\nFT9A2B7XQ1LZ,15/12/2025,19:20,Deposit Received,Nostro,Sub: JOHN SMITH,IN,150,USD,JOHN SMITH,1029384756,1,0\n---,---,---,---,---,---,---,---,---,---,---,---,---\n=== SUMMARY ===,,,Total Deposits (1),,,,IN,150,USD,,,,\n,,,Net Position,,,,150,USD,,,,,Closing Balance: 150.00 USD\n" } } } }, "400": { "description": "Bad Request - Validation failed (e.g., invalid date range, invalid pagination token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required or token is invalid/expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-account-transactions" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/transactions/{transactionId}": { "get": { "tags": [ "Virtual Accounts" ], "summary": "Virtual Account Transaction Details", "description": "Retrieves detailed information for a specific virtual-account transaction identified by its globally unique transaction ID. This endpoint:\n\n- Returns a single transaction detail object with full context (accounts, amounts, value date, narrative, attributes)\n- Supports both JSON and CSV response formats based on the Accept header\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Account Routing Metadata\nThe transaction detail response includes routing metadata for\n`debitAccountNumber` or/and `creditAccountNumber` depending of transaction type.\nAccount entity contains an `accountRoutings` collection with up to four entries (when data is available):\n\n- `BankId` – BIC / SWIFT identifier of the bank handling the account\n- `BankName` – Legal name of the bank\n- `AccountName` – Account holder or counterparty name\n- `AccountAddress` – Postal address details associated with the account\n\nEntries are ordered as listed above and only appear when the upstream system\nreturns the corresponding value. Consumers can rely on the `scheme` field to\ndifferentiate each routing record.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/transactions/{transactionId}\n\n### Sample Request in JavaScript\n\n```javascript\nasync function getVirtualAccountTransactionDetail(transactionId) {\n const url = `https://api.bcb.bm/v1/virtual-accounts/transactions/${encodeURIComponent(transactionId)}`;\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(`Failed to get VA transaction detail: ${error.message || 'Unknown error'}`);\n }\n\n const result = await response.json();\n // result is a single transaction detail object\n console.log('Transaction ID:', result.id);\n console.log('Description:', result.description);\n console.log('Value Date:', result.valueDate);\n if (result.value) {\n console.log('Amount:', result.value.amount, result.value.currency);\n }\n return result;\n}\n```\n\n**Required Permission:** `get-virtual-account-transactions`\n\nThis endpoint requires the permission claim `get-virtual-account-transactions` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransactions_GetDetails", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "description": "The globally unique transaction identifier to retrieve details for.", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransactionDetail" }, "examples": { "Json": { "value": { "debitAccountNumber": { "number": 1111111111, "accountRoutings": [ { "scheme": "BankId", "address": "BBDABMHMXXX" }, { "scheme": "BankName", "address": "Bank of Bermuda Ltd" }, { "scheme": "AccountName", "address": "Global Holdings Ltd" }, { "scheme": "AccountAddress", "address": "99 Front Street, Hamilton" } ] }, "creditAccountNumber": { "number": 2222222222, "accountRoutings": [ { "scheme": "BankId", "address": "CITIUS33XXX" }, { "scheme": "BankName", "address": "Citibank N.A." }, { "scheme": "AccountName", "address": "Parent Treasury Account" }, { "scheme": "AccountAddress", "address": "399 Park Avenue, New York" } ] }, "status": "COMPLETED", "counterpartyReference": "CTP-2024-000123", "id": "TX-2024-000123", "description": "Payout to sub-account", "bookingDate": "2025-08-04", "valueDate": "2025-08-04", "value": { "currency": "USD", "amount": 100 }, "proprietaryBankTransactionCode": "PARENT.TO.SUB" } }, "Csv": { "value": "\"debit_account_number_number\",\"debit_account_number_account_routings_0_scheme\",\"debit_account_number_account_routings_0_address\",\"debit_account_number_account_routings_1_scheme\",\"debit_account_number_account_routings_1_address\",\"debit_account_number_account_routings_2_scheme\",\"debit_account_number_account_routings_2_address\",\"debit_account_number_account_routings_3_scheme\",\"debit_account_number_account_routings_3_address\",\"credit_account_number_number\",\"credit_account_number_account_routings_0_scheme\",\"credit_account_number_account_routings_0_address\",\"credit_account_number_account_routings_1_scheme\",\"credit_account_number_account_routings_1_address\",\"credit_account_number_account_routings_2_scheme\",\"credit_account_number_account_routings_2_address\",\"credit_account_number_account_routings_3_scheme\",\"credit_account_number_account_routings_3_address\",\"status\",\"counterparty_reference\",\"id\",\"description\",\"booking_date\",\"value_date\",\"value_currency\",\"value_amount\",\"proprietary_bank_transaction_code\"\n\"1111111111\",\"BankId\",\"BBDABMHMXXX\",\"BankName\",\"Bank of Bermuda Ltd\",\"AccountName\",\"Global Holdings Ltd\",\"AccountAddress\",\"99 Front Street, Hamilton\",\"2222222222\",\"BankId\",\"CITIUS33XXX\",\"BankName\",\"Citibank N.A.\",\"AccountName\",\"Parent Treasury Account\",\"AccountAddress\",\"399 Park Avenue, New York\",\"COMPLETED\",\"CTP-2024-000123\",\"TX-2024-000123\",\"Payout to sub-account\",\"2025-08-04\",\"2025-08-04\",\"USD\",\"100.00\",\"PARENT.TO.SUB\"\n" } } } } }, "400": { "description": "Bad Request - Validation failed or the request cannot be served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required or token is invalid/expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-virtual-account-transactions" ] }, { "Authorization": [] } ] }, "delete": { "tags": [ "Virtual Accounts" ], "summary": "Reverse Virtual Account Transaction", "description": "Reverses a specific virtual-account transaction identified by its globally unique transaction ID. This endpoint:\n\n- Reverses the specified transaction and returns the reversal details\n- Supports both JSON and CSV response formats based on the Accept header\n- Requires appropriate permissions to perform transaction reversals\n\n### Important Business Rules\n- **Same-Day Reversal Only**: The current development design allows only to reverse records created on the same day\n- **Completed Status Required**: The transaction status must have \"Completed\" status to be eligible for reversal\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/transactions/{transactionId}\n\n### Sample Request in JavaScript\n\n```javascript\nasync function reverseVirtualAccountTransaction(transactionId) {\n const url = `https://api.bcb.bm/v1/virtual-accounts/transactions/${encodeURIComponent(transactionId)}`;\n const response = await fetch(url, {\n method: 'DELETE',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n }\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(`Failed to reverse VA transaction: ${error.message || 'Unknown error'}`);\n }\n\n const result = await response.json();\n // result is a transaction reversal object\n console.log('Reversal Transaction ID:', result.transactionId);\n console.log('Status:', result.status);\n console.log('Transaction Status:', result.transactionStatus);\n if (result.value) {\n console.log('Amount:', result.value.amount, result.value.currency);\n }\n return result;\n}\n```\n\n**Required Permission:** `reverse-virtual-account-transaction`\n\nThis endpoint requires the permission claim `reverse-virtual-account-transaction` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransactions_Reverse", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "description": "The globally unique transaction identifier to reverse.", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "201": { "description": "Created - The transaction reversal was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransactionReversal" }, "example": { "transactionId": "FT252255GBQS", "transactionStatus": "Reversed", "status": "success", "uniqueIdentifier": "FT252255GBQS", "value": { "currency": "USD", "amount": 0.03 } } } } }, "400": { "description": "Bad Request - Validation failed or the request cannot be served.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required or token is invalid/expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - The request could not be completed due to a conflict with the current state of the resource. This includes attempting to reverse an already reverted transaction without providing an idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "reverse-virtual-account-transaction" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{virtualAccountNumber}/deposits": { "get": { "tags": [ "Virtual Accounts" ], "summary": "Get Virtual Account Deposits", "description": "Retrieves deposit transaction entries for a specific virtual (sub) account.\nThis endpoint: \n- Returns detailed deposit transaction information including account numbers, amounts, and transaction status.\n- Supports both JSON and CSV response formats based on the Accept header.\n- Uses cursor-based pagination with server-side result-set management.\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including `pageSize`, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{virtualAccountNumber}/deposits\n\n### Sample Request in JavaScript\n```javascript\n// Get first page of deposits\nasync function getVirtualAccountDeposits(virtualAccountNumber, fromDate, toDate) {\n const url = new URL(`https://api.bcb.bm/v1/virtual-accounts/${encodeURIComponent(virtualAccountNumber)}/deposits`);\n url.searchParams.set('fromDate', fromDate); // yyyy-MM-dd or yyyyMMdd\n url.searchParams.set('toDate', toDate); // yyyy-MM-dd or yyyyMMdd\n url.searchParams.set('pageSize', '100'); // optional (first call only)\n\n const response = await fetch(url.toString(), {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(`Failed to get VA deposits: ${error.message || 'Unknown error'}`);\n }\n\n const result = await response.json();\n // result.meta.pagination: { page_start, page_token, total_size, page_size }\n // result.data: Array of VA deposit transactions\n // Example: inspect first deposit\n if (result.data?.length) {\n const d = result.data[0];\n console.log('Deposit:', d.id, d.valueDate, d.value?.amount, d.value?.currency, d.proprietaryBankTransactionCode);\n console.log('From:', d.debitAccountNumber?.number, 'To:', d.creditAccountNumber?.number);\n console.log('Status:', d.status);\n }\n return result;\n}\n\n// Paginate through all deposit pages\nasync function getAllVirtualAccountDeposits(virtualAccountNumber, fromDate, toDate) {\n let pageStart = 1;\n let pageToken = null;\n let totalPages = 0;\n const all = [];\n\n do {\n const url = new URL(`https://api.bcb.bm/v1/virtual-accounts/${encodeURIComponent(virtualAccountNumber)}/deposits`);\n url.searchParams.set('fromDate', fromDate);\n url.searchParams.set('toDate', toDate);\n if (pageStart === 1) {\n url.searchParams.set('pageSize', '100'); // first call only\n } else {\n url.searchParams.set('pageStart', String(pageStart));\n url.searchParams.set('pageToken', pageToken);\n }\n\n const res = await fetch(url.toString(), {\n headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Accept': 'application/json' }\n });\n if (!res.ok) throw new Error('Request failed');\n const body = await res.json();\n\n if (pageStart === 1) {\n const p = body.meta?.pagination;\n pageToken = p?.page_token;\n totalPages = Math.ceil((p?.total_size ?? 0) / (p?.page_size ?? 100));\n console.log('First page meta:', p);\n }\n\n if (Array.isArray(body.data)) all.push(...body.data);\n pageStart++;\n } while (pageStart <= totalPages);\n\n return all;\n}\n```\n\n**Required Permission:** `deposit-virtual-account`\n\nThis endpoint requires the permission claim `deposit-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransactions_GetDeposits", "parameters": [ { "name": "virtualAccountNumber", "in": "path", "required": true, "description": "Virtual account identifier (number) to retrieve deposits for.", "schema": { "type": "string" }, "x-position": 1 }, { "name": "fromDate", "in": "query", "required": true, "description": "The start date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 2 }, { "name": "toDate", "in": "query", "required": true, "description": "The end date for the transaction range (format: yyyy-MM-dd).", "schema": { "type": "string" }, "x-position": 3 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 4 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 5 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 6 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfVirtualAccountTransactionDetailOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "202507250072428721.01,3", "totalSize": 3, "pageSize": 3 } }, "data": [ { "debitAccountNumber": { "number": 445566778, "accountRoutings": [ { "scheme": "BankId", "address": 2000033 }, { "scheme": "AccountDetails", "address": "ALPHA MANUFACTURING CORP. 789 INDUSTRIAL BLVD STE 200" } ] }, "creditAccountNumber": { "number": 2000444555, "accountRoutings": [] }, "status": "Completed", "counterpartyReference": null, "id": "FT25123A7B9C", "description": "/ROC/4567890123///URI/JF MARCH INVOICE PAYMENT", "bookingDate": "", "valueDate": "2025-03-15", "value": { "currency": "CAD", "amount": 3250 }, "proprietaryBankTransactionCode": "Inward Swift Payment" }, { "debitAccountNumber": { "number": 112233445, "accountRoutings": [ { "scheme": "BankId", "address": 2000044 }, { "scheme": "AccountDetails", "address": "BETA CONSULTING GROUP LLC. 456 FINANCIAL DISTRICT TOWER 15" } ] }, "creditAccountNumber": { "number": 2000555666, "accountRoutings": [] }, "status": "Completed", "counterpartyReference": null, "id": "FT25124D8E2F", "description": "/ROC/9876543210///URI/JF APRIL CONSULTING FEE", "bookingDate": "", "valueDate": "2025-04-22", "value": { "currency": "JPY", "amount": 450000 }, "proprietaryBankTransactionCode": "Inward Swift Payment" }, { "debitAccountNumber": { "number": 778899001, "accountRoutings": [ { "scheme": "BankId", "address": 2000055 }, { "scheme": "AccountDetails", "address": "GAMMA PROPERTY HOLDINGS INC. 321 COMMERCIAL PLAZA FLOOR 8" } ] }, "creditAccountNumber": { "number": 2000666777, "accountRoutings": [] }, "status": "Completed", "counterpartyReference": null, "id": "FT25125G3H1I", "description": "/ROC/1357924680///URI/JF MAY RENTAL PAYMENT", "bookingDate": "", "valueDate": "2025-05-08", "value": { "currency": "AUD", "amount": 8750.25 }, "proprietaryBankTransactionCode": "Inward Swift Payment" } ] } }, "Csv": { "value": "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_debit_account_number_number\",\"data_0_debit_account_number_account_routings_0_scheme\",\"data_0_debit_account_number_account_routings_0_address\",\"data_0_debit_account_number_account_routings_1_scheme\",\"data_0_debit_account_number_account_routings_1_address\",\"data_0_credit_account_number_number\",\"data_0_status\",\"data_0_id\",\"data_0_description\",\"data_0_booking_date\",\"data_0_value_date\",\"data_0_value_currency\",\"data_0_value_amount\",\"data_0_proprietary_bank_transaction_code\",\"data_1_debit_account_number_number\",\"data_1_debit_account_number_account_routings_0_scheme\",\"data_1_debit_account_number_account_routings_0_address\",\"data_1_debit_account_number_account_routings_1_scheme\",\"data_1_debit_account_number_account_routings_1_address\",\"data_1_credit_account_number_number\",\"data_1_status\",\"data_1_id\",\"data_1_description\",\"data_1_booking_date\",\"data_1_value_date\",\"data_1_value_currency\",\"data_1_value_amount\",\"data_1_proprietary_bank_transaction_code\",\"data_2_debit_account_number_number\",\"data_2_debit_account_number_account_routings_0_scheme\",\"data_2_debit_account_number_account_routings_0_address\",\"data_2_debit_account_number_account_routings_1_scheme\",\"data_2_debit_account_number_account_routings_1_address\",\"data_2_credit_account_number_number\",\"data_2_status\",\"data_2_id\",\"data_2_description\",\"data_2_booking_date\",\"data_2_value_date\",\"data_2_value_currency\",\"data_2_value_amount\",\"data_2_proprietary_bank_transaction_code\"\n\"1\",\"202507250072428721.01,3\",\"3\",\"3\",\"445566778\",\"BankId\",\"2000033\",\"AccountDetails\",\"ALPHA MANUFACTURING CORP. 789 INDUSTRIAL BLVD STE 200\",\"2000444555\",\"Completed\",\"FT25123A7B9C\",\"/ROC/4567890123///URI/JF MARCH INVOICE PAYMENT\",\"\",\"2025-03-15\",\"CAD\",\"3250.00\",\"Inward Swift Payment\",\"112233445\",\"BankId\",\"2000044\",\"AccountDetails\",\"BETA CONSULTING GROUP LLC. 456 FINANCIAL DISTRICT TOWER 15\",\"2000555666\",\"Completed\",\"FT25124D8E2F\",\"/ROC/9876543210///URI/JF APRIL CONSULTING FEE\",\"\",\"2025-04-22\",\"JPY\",\"450000.00\",\"Inward Swift Payment\",\"778899001\",\"BankId\",\"2000055\",\"AccountDetails\",\"GAMMA PROPERTY HOLDINGS INC. 321 COMMERCIAL PLAZA FLOOR 8\",\"2000666777\",\"Completed\",\"FT25125G3H1I\",\"/ROC/1357924680///URI/JF MAY RENTAL PAYMENT\",\"\",\"2025-05-08\",\"AUD\",\"8750.25\",\"Inward Swift Payment\"\n" } } } } }, "400": { "description": "Bad Request - Validation failed (e.g., invalid date range, invalid pagination token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required or token is invalid/expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "deposit-virtual-account" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{accountNumber}/transfers/credit": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Credit Virtual Account", "description": "Credits funds to a virtual account from a parent account. This endpoint allows clients to transfer funds \ninto a virtual account.\n\nThe request must include source account details, the amount to be credited, and currency information. \n\n### Key Features:\n- Transfers funds from a source account to a virtual account\n- Supports idempotency to prevent duplicate transactions\n- Validates account numbers and currency matching\n- Supports both JSON and CSV response formats\n- Automatic account number validation and matching\n\n### Important Notes:\n- The virtual account number (creditAccountNumber) is specified in the URL route, not in the request body\n- Ensure the source account has sufficient funds before making the request\n- Virtual accounts must be in an active state to receive credits\n\n**Virtual Account Hierarchy**\nVirtual accounts are sub-accounts linked to a parent account:\n```\nParent Account → Virtual Account (Sub-Account)\n```\nWhen crediting a virtual account, funds flow from the parent account to the virtual account.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{accountNumber}/transfers/credit\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function creditVirtualAccount() {\n try {\n const virtualAccountNumber = \"1556008272\";\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountNumber}/transfers/credit`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitAccountNumber: \"1000320567\",\n debitAmountCurrency: \"USD\",\n creditAmountCurrency: \"USD\", // Must match debitAmountCurrency\n debitAmount: \"100.00\"\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Credit transfer failed: ${JSON.stringify(errorData)}`);\n }\n\n const data = await response.json();\n console.log('Credit transfer result:', data);\n\n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { debitAmount, valueDate, childTransactionId, creditAmountCurrency, debitAccountNumber, creditAccountNumber } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);\n console.log('Value Date:', valueDate);\n console.log('Child Transaction ID:', childTransactionId);\n console.log('Credit Amount Currency:', creditAmountCurrency);\n\n // Process debit account information\n console.log('Debit Account Number:', debitAccountNumber.number);\n\n // Process credit account information (virtual account)\n console.log('Credit Account Number:', creditAccountNumber.number);\n\n // Process linked activities\n linkedActivities.forEach(activity => {\n console.log('Linked Activity ID:', activity.id);\n console.log('Linked Activity Transaction Status:', activity.transactionStatus);\n console.log('Linked Activity Status:', activity.status);\n console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);\n const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;\n console.log('Linked Activity Arrangement ID:', arrangementId);\n console.log('Linked Activity Activity ID:', activityId);\n console.log('Linked Activity Product ID:', productId);\n console.log('Linked Activity Currency ID:', currencyId);\n console.log('Linked Activity Effective Date:', effectiveDate);\n });\n\n // Final status logging\n if (status === 'success') {\n console.log('The virtual account credit was successful.');\n } else {\n console.log('The virtual account credit failed:', status);\n }\n } catch (error) {\n console.error('Error crediting virtual account:', error);\n }\n}\n\ncreditVirtualAccount();\n```\n\n**Required Permission:** `deposit-virtual-account`\n\nThis endpoint requires the permission claim `deposit-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfers_Credit", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "The virtual account number to be credited.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "debitAccountNumber": 1000320567, "debitAmountCurrency": "USD", "creditAmountCurrency": "USD", "debitAmount": 100 } } ], "requestBody": { "x-name": "request", "description": "The credit transfer request details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountCreditRequest" }, "example": { "debitAccountNumber": 1000320567, "debitAmountCurrency": "USD", "creditAmountCurrency": "USD", "debitAmount": 100 } } }, "x-position": 2 }, "responses": { "201": { "description": "The virtual account was credited successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountTransferDetails" }, "examples": { "Json": { "value": { "id": "AA25174JFTXZ", "status": "success", "uniqueIdentifier": "fc17c362-ae8c-47b9-9080-7e475ac31c96", "details": { "debitAmount": { "currency": "USD", "amount": 100 }, "valueDate": "2025-06-20", "childTransactionId": 292386, "creditAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320567, "accountRoutings": [ { "scheme": "IBAN", "address": "BM12BCBK12345678901234" } ] }, "creditAccountNumber": { "number": 1556008272, "accountRoutings": [ { "scheme": "IBAN", "address": "BM12BCBK15560082723456" } ] } }, "linkedActivities": [ { "id": "activity-123", "transactionStatus": "SUCCESS", "status": "COMPLETED", "uniqueIdentifier": "unique-activity-123", "activityDetails": { "arrangementId": "arrangement-123", "activityId": "activity-123", "productId": "product-123", "currencyId": "USD", "effectiveDate": "2025-06-20" } } ] } }, "Csv": { "value": [ "\"id\",\"status\",\"unique_identifier\",\"details_debit_amount_currency\",\"details_debit_amount_amount\",\"details_value_date\",\"details_child_transaction_id\",\"details_credit_amount_currency\",\"details_debit_account_number_number\",\"details_debit_account_number_account_routings_0_scheme\",\"details_debit_account_number_account_routings_0_address\",\"details_credit_account_number_number\",\"details_credit_account_number_account_routings_0_scheme\",\"details_credit_account_number_account_routings_0_address\",\"linked_activities_0_id\",\"linked_activities_0_transaction_status\",\"linked_activities_0_status\",\"linked_activities_0_unique_identifier\",\"linked_activities_0_activity_details_arrangement_id\",\"linked_activities_0_activity_details_activity_id\",\"linked_activities_0_activity_details_product_id\",\"linked_activities_0_activity_details_currency_id\",\"linked_activities_0_activity_details_effective_date\"", "\"AA25174JFTXZ\",\"success\",\"fc17c362-ae8c-47b9-9080-7e475ac31c96\",\"USD\",\"100.00\",\"2025-06-20\",\"292386\",\"USD\",\"1000320567\",\"IBAN\",\"BM12BCBK12345678901234\",\"1556008272\",\"IBAN\",\"BM12BCBK15560082723456\",\"activity-123\",\"SUCCESS\",\"COMPLETED\",\"unique-activity-123\",\"arrangement-123\",\"activity-123\",\"product-123\",\"USD\",\"2025-06-20\"" ] } } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the credit transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "deposit-virtual-account" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{accountNumber}/transfers/debit": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Debit Virtual Account", "description": "Initiates a debit transfer from a virtual (sub) account to transfer funds to the parent account and ultimately to the settlement account. \nThis endpoint allows corporate clients to withdraw funds from their virtual accounts for settlement purposes.\n \n**Use Case**: As a corporate client, I want to debit a sub account to transfer funds to the parent account and ultimately to the settlement account.\n \n### Key Features:\n- Transfers funds from a virtual account to a main account\n- Supports idempotency to prevent duplicate transactions\n- Validates account numbers and currency matching\n- Supports both JSON and CSV response formats\n- Automatic account number validation and matching\n\n### Important Notes:\n- The virtual account number (debitAccountNumber) is specified in the URL route, not in the request body\n- Ensure the virtual account has sufficient funds before making the request\n \n**Virtual Account Hierarchy**\nVirtual accounts are sub-accounts linked to a parent account:\n```\nVirtual Account (Sub-Account) → Parent Account\n```\nWhen debiting a virtual account, funds flow from the virtual account to the parent account.\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n \n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{accountNumber}/transfers/debit\n \n### Sample Request in JavaScript:\n \n```javascript\nasync function debitVirtualAccount() {\n try {\n const accountNumber = \"1000000000\"; // Virtual account number\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${accountNumber}/transfers/debit`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitAmount: \"1000.00\",\n debitAmountCurrency: \"USD\",\n creditAccountNumber: \"1000320567\", // Parent/settlement account\n creditAmountCurrency: \"USD\", // Must match debitAmountCurrency\n })\n });\n \n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Debit transfer failed: ${JSON.stringify(errorData)}`);\n }\n \n const data = await response.json();\n console.log('Debit transfer result:', data);\n \n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { debitAmount, valueDate, childTransactionId, creditAmountCurrency, debitAccountNumber, creditAccountNumber } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);\n console.log('Value Date:', valueDate);\n console.log('Child Transaction ID:', childTransactionId);\n console.log('Credit Amount Currency:', creditAmountCurrency);\n \n // Process debit account information\n console.log('Debit Account Number:', debitAccountNumber.number);\n \n // Process credit account information\n console.log('Credit Account Number:', creditAccountNumber.number);\n \n // Process linked activities\n linkedActivities.forEach(activity => {\n console.log('Linked Activity ID:', activity.id);\n console.log('Linked Activity Transaction Status:', activity.transactionStatus);\n console.log('Linked Activity Status:', activity.status);\n console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);\n const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;\n console.log('Linked Activity Arrangement ID:', arrangementId);\n console.log('Linked Activity Activity ID:', activityId);\n console.log('Linked Activity Product ID:', productId);\n console.log('Linked Activity Currency ID:', currencyId);\n console.log('Linked Activity Effective Date:', effectiveDate);\n });\n \n // Final status logging\n if (status === 'SUCCESS') {\n console.log('The debit transfer was successful.');\n } else {\n console.log('The debit transfer failed:', status);\n }\n \n } catch (error) {\n console.error('Error debiting virtual account:', error);\n }\n}\n\n// Execute example\ndebitVirtualAccount();\n```\n\n**Required Permission:** `withdraw-virtual-account`\n\nThis endpoint requires the permission claim `withdraw-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfers_Debit", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "The virtual account number to be debited.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "creditAccountNumber": 1556008272, "debitAmountCurrency": "USD", "creditAmountCurrency": "USD", "debitAmount": 100 } } ], "requestBody": { "x-name": "request", "description": "The debit transfer request details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDebitRequest" }, "example": { "creditAccountNumber": 1556008272, "debitAmountCurrency": "USD", "creditAmountCurrency": "USD", "debitAmount": 100 } } }, "x-position": 2 }, "responses": { "201": { "description": "The virtual account was debited successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountTransferDetails" }, "examples": { "Json": { "value": { "id": "AA25174JFTXZ", "status": "success", "uniqueIdentifier": "fc17c362-ae8c-47b9-9080-7e475ac31c96", "details": { "debitAmount": { "currency": "USD", "amount": 100 }, "valueDate": "2025-06-20", "childTransactionId": 292386, "creditAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320567, "accountRoutings": [ { "scheme": "IBAN", "address": "BM12BCBK12345678901234" } ] }, "creditAccountNumber": { "number": 1556008272, "accountRoutings": [ { "scheme": "IBAN", "address": "BM12BCBK15560082723456" } ] } }, "linkedActivities": [ { "id": "activity-123", "transactionStatus": "SUCCESS", "status": "COMPLETED", "uniqueIdentifier": "unique-activity-123", "activityDetails": { "arrangementId": "arrangement-123", "activityId": "activity-123", "productId": "product-123", "currencyId": "USD", "effectiveDate": "2025-06-20" } } ] } }, "Csv": { "value": [ "\"id\",\"status\",\"unique_identifier\",\"details_debit_amount_currency\",\"details_debit_amount_amount\",\"details_value_date\",\"details_child_transaction_id\",\"details_credit_amount_currency\",\"details_debit_account_number_number\",\"details_debit_account_number_account_routings_0_scheme\",\"details_debit_account_number_account_routings_0_address\",\"details_credit_account_number_number\",\"details_credit_account_number_account_routings_0_scheme\",\"details_credit_account_number_account_routings_0_address\",\"linked_activities_0_id\",\"linked_activities_0_transaction_status\",\"linked_activities_0_status\",\"linked_activities_0_unique_identifier\",\"linked_activities_0_activity_details_arrangement_id\",\"linked_activities_0_activity_details_activity_id\",\"linked_activities_0_activity_details_product_id\",\"linked_activities_0_activity_details_currency_id\",\"linked_activities_0_activity_details_effective_date\"", "\"AA25174JFTXZ\",\"success\",\"fc17c362-ae8c-47b9-9080-7e475ac31c96\",\"USD\",\"100.00\",\"2025-06-20\",\"292386\",\"USD\",\"1000320567\",\"IBAN\",\"BM12BCBK12345678901234\",\"1556008272\",\"IBAN\",\"BM12BCBK15560082723456\",\"activity-123\",\"SUCCESS\",\"COMPLETED\",\"unique-activity-123\",\"arrangement-123\",\"activity-123\",\"product-123\",\"USD\",\"2025-06-20\"" ] } } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the debit transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "withdraw-virtual-account" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{settlementAccountNumber}/settlements/internal": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Counter-party Settlement Transfer (Internal)", "description": "Corporate Client initiates Settlement request to BCB to debit Settlement Account and credit to Counterparty Account.\nThis endpoint allows clients to transfer funds from a settlement account to an internal counterparty account.\n\n### Key Features:\n- Transfers funds from a settlement account to an internal counterparty account\n- Supports idempotency to prevent duplicate transactions\n- Validates account numbers and currency matching\n- Supports both JSON and CSV response formats\n- Automatic settlement account number validation\n\n### Important Notes:\n- The settlementAccountNumber in the route parameter identifies the source settlement account\n- The creditAccountNumber in the request body specifies the destination counterparty account\n- Ensure the settlement account has sufficient funds before making the request\n- Settlement accounts must be in an active state to process transfers\n\n### Settlement Account Structure\nSettlement accounts are special accounts used for counterparty transactions:\n```\nSettlement Account → Counterparty Account (Internal)\n```\nWhen processing a settlement transfer, funds flow from the settlement account to the counterparty account.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{settlementAccountNumber}/settlements/internal\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function processInternalSettlement() {\n try {\n const settlementAccountNumber = \"1000320559\";\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${settlementAccountNumber}/settlements/internal`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitCurrency: \"USD\",\n creditAmount: {\n amount: \"1000.00\",\n currency: \"USD\"\n },\n creditAccountNumber: \"1000076925\"\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Internal settlement failed: ${JSON.stringify(errorData)}`);\n }\n\n const data = await response.json();\n console.log('Internal settlement result:', data);\n\n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { creditAmount, debitAmountCurrency, debitAccountNumber, creditAccountNumber, valueDate } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Credit Amount:', creditAmount.amount, creditAmount.currency);\n console.log('Debit Amount Currency:', debitAmountCurrency);\n console.log('Value Date:', valueDate);\n\n // Process debit account information (settlement account)\n console.log('Debit Account Number:', debitAccountNumber.number);\n\n // Process credit account information (counterparty account)\n console.log('Credit Account Number:', creditAccountNumber.number);\n\n // Final status logging\n if (status === 'success') {\n console.log('The internal settlement was successful.');\n } else {\n console.log('The internal settlement failed:', status);\n }\n } catch (error) {\n console.error('Error processing internal settlement:', error);\n }\n}\n\nprocessInternalSettlement();\n```\n\n**Required Permission:** `counter-party-settlement-transaction`\n\nThis endpoint requires the permission claim `counter-party-settlement-transaction` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfersSettlement_SettlementInternal", "parameters": [ { "name": "settlementAccountNumber", "in": "path", "required": true, "description": "The settlement account number from which funds will be debited.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "debitCurrency": "USD", "creditAmount": { "currency": "USD", "amount": 0.01 }, "creditAccountNumber": 1000076925 } } ], "requestBody": { "x-name": "request", "description": "Payload containing internal settlement transfer details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountSettlementTransferRequestInternal" }, "example": { "debitCurrency": "USD", "creditAmount": { "currency": "USD", "amount": 0.01 }, "creditAccountNumber": 1000076925 } } }, "required": true, "x-position": 2 }, "responses": { "201": { "description": "The settlement transfer was processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountSettlementTransfer" }, "example": { "id": "FT252324K67K", "status": "success", "uniqueIdentifier": "IRFX252332872527361.00", "details": { "creditAmount": { "currency": "USD", "amount": 10.01 }, "debitAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320559, "accountRoutings": [] }, "creditAccountNumber": { "number": 1000076925, "accountRoutings": [] }, "valueDate": "2025-08-20T07:36:00.0000000Z" }, "linkedActivities": [] } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the settlement transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "counter-party-settlement-transaction" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{settlementAccountNumber}/settlements/external": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Counter-party Settlement Transfer (External)", "description": "Corporate Client initiates External Settlement request to BCB to debit Settlement Account and credit to External Counterparty Account.\nThis endpoint allows clients to transfer funds from a settlement account to an external counterparty account.\n\n### Key Features:\n- Transfers funds from a settlement account to an external counterparty account\n- Supports idempotency to prevent duplicate transactions\n- Supports both JSON and CSV response formats\n- Automatic settlement account number validation\n- Includes beneficiary and ordering customer information for external transfers\n- Supports both the existing same-currency payload and the additive cross-currency FX payload\n \n### Supported Request Formats\nUse one of the following request shapes:\n \nExisting format - same-currency:\n```json\n{\n \"debitCurrency\": \"USD\",\n \"creditAmount\": {\n \"currency\": \"USD\",\n \"amount\": 2500\n }\n}\n```\n \nAdditive format - cross-currency FX:\n```json\n{\n \"debitAmount\": {\n \"currency\": \"USD\",\n \"amount\": 2500\n },\n \"creditAmount\": {\n \"currency\": \"HKD\"\n }\n}\n```\n \n### Cross-Currency FX\n- Provide `debitAmount` (currency and amount) when you want the debit side to be authoritative.\n- Provide only `creditAmount.currency` in that case; the bank assigns the exchange rate and final credited amount before forwarding to the beneficiary.\n- If `debitAmount` is omitted, the existing `debitCurrency` + `creditAmount` (currency + amount) format applies with no change to current behaviour.\n \n- `debitCurrency` is not deprecated and remains fully supported.\n- Both payload formats are accepted and return a successful response.\n\n### Important Notes:\n- The settlementAccountNumber in the route parameter identifies the source settlement account\n- The request body specifies the destination external counterparty account via `creditorAccount.identification`\n- Ensure the settlement account has sufficient funds before making the request\n- Settlement accounts must be in an active state to process transfers\n- External transfers require additional beneficiary information for compliance\n\n### Settlement Account Structure\nSettlement accounts are special accounts used for counterparty transactions:\n```\nSettlement Account → External Counterparty Account\n```\nWhen processing an external settlement transfer, funds flow from the settlement account to the external counterparty account.\n\n### External Transfer Requirements\nExternal transfers require additional information for regulatory compliance:\n- **debitCurrency**: Currency to debit from the settlement account (e.g., \"USD\")\n- **creditAmount**: Amount and currency to credit externally (e.g., { amount: \"19\", currency: \"GBP\" })\n- **debtor**: Ordering customer information (e.g., company name or reference)\n- **debtorAgent**: Ordering bank/agent identifier (free text)\n- **creditorAccount.identification**: External beneficiary account identifier\n- **creditorAccount.name / additionalInformation**: Beneficiary name and auxiliary details\n- **chargesType**: Who bears charges (e.g., OUR, BEN, SHA)\n- **creditorAgent**: Beneficiary bank info (identification, name, additionalInformation)\n- **intermediaryAgent** (optional): Intermediary bank info (identification, name, additionalInformation)\n- **remittanceInformation** (optional): Unstructured remittance lines\n \n### Creditor Agent (Beneficiary Bank)\n- If `creditorAgent.identification` (BIC/bank identifier) is provided, `creditorAgent.name` and `creditorAgent.additionalInformation` are optional and may be omitted.\n- If `creditorAgent.identification` is not provided, supply `creditorAgent.name` and `creditorAgent.additionalInformation` to identify the beneficiary bank.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{settlementAccountNumber}/settlements/external\n\n### Sample Request in JavaScript (Existing same-currency format):\n\n```javascript\nasync function processExternalSettlement() {\n try {\n const settlementAccountNumber = \"1000320559\";\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${settlementAccountNumber}/settlements/external`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitCurrency: \"USD\",\n creditAmount: {\n amount: \"19\",\n currency: \"GBP\"\n },\n debtor: \"ACME GLOBAL TRADING INC.\",\n debtorAgent: \"FIRST ATLANTIC BANK\",\n creditorAccount: {\n identification: \"GB29NWBK60161331926819\",\n name: \"OMEGA INTERNATIONAL LTD.\",\n additionalInformation: [\"LONDON\", \"GB\"]\n },\n chargesType: \"OUR\",\n creditorAgent: {\n identification: \"//ZZ123456789\",\n name: \"OMEGA BANK\",\n additionalInformation: [\"LONDON\", \"UK\"]\n },\n intermediaryAgent: {\n identification: \"INTL\",\n name: \"EURO CLEAR BANK\",\n additionalInformation: [\"BRUSSELS\", \"BE\"]\n },\n remittanceInformation: [\"INVOICE 2025-00042\"]\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`External settlement failed: ${JSON.stringify(errorData)}`);\n }\n\n const data = await response.json();\n console.log('External settlement result:', data);\n\n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { creditAmount, debitAmountCurrency, debitAccountNumber, creditAccountNumber, valueDate } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Credit Amount:', creditAmount.amount, creditAmount.currency);\n console.log('Debit Amount Currency:', debitAmountCurrency);\n console.log('Value Date:', valueDate);\n\n // Process debit account information (settlement account)\n console.log('Debit Account Number:', debitAccountNumber.number);\n\n // Process credit account information (external counterparty account)\n console.log('Credit Account Number:', creditAccountNumber.number);\n\n // Final status logging\n if (status === 'success') {\n console.log('The external settlement was successful.');\n } else {\n console.log('The external settlement failed:', status);\n }\n } catch (error) {\n console.error('Error processing external settlement:', error);\n }\n}\n\nprocessExternalSettlement();\n```\n\n**Required Permission:** `counter-party-settlement-transaction`\n\nThis endpoint requires the permission claim `counter-party-settlement-transaction` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfersSettlement_SettlementExternal", "parameters": [ { "name": "settlementAccountNumber", "in": "path", "required": true, "description": "The settlement account number from which funds will be debited.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "debitAmount": { "currency": "USD", "amount": 2500 }, "creditAmount": { "currency": "HKD" }, "debtor": "ACME GLOBAL TRADING INC.", "debtorAgent": "FIRST ATLANTIC BANK", "creditorAccount": { "identification": "GB29NWBK60161331926819", "name": "OMEGA INTERNATIONAL LTD.", "additionalInformation": [ "LONDON", "GB" ] }, "chargesType": "OUR", "creditorAgent": { "identification": "//ZZ123456789", "name": "OMEGA BANK", "additionalInformation": [ "LONDON", "UK" ] }, "intermediaryAgent": { "identification": "INTL", "name": "EURO CLEAR BANK", "additionalInformation": [ "BRUSSELS", "BE" ] }, "remittanceInformation": [ "INVOICE 2025-00042" ] } } ], "requestBody": { "x-name": "request", "description": "Payload containing external settlement transfer details. For FX cross-currency, optional debitAmount (with creditAmount currency only) may be sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountSettlementTransferRequestExternal" }, "example": { "debitAmount": { "currency": "USD", "amount": 2500 }, "creditAmount": { "currency": "HKD" }, "debtor": "ACME GLOBAL TRADING INC.", "debtorAgent": "FIRST ATLANTIC BANK", "creditorAccount": { "identification": "GB29NWBK60161331926819", "name": "OMEGA INTERNATIONAL LTD.", "additionalInformation": [ "LONDON", "GB" ] }, "chargesType": "OUR", "creditorAgent": { "identification": "//ZZ123456789", "name": "OMEGA BANK", "additionalInformation": [ "LONDON", "UK" ] }, "intermediaryAgent": { "identification": "INTL", "name": "EURO CLEAR BANK", "additionalInformation": [ "BRUSSELS", "BE" ] }, "remittanceInformation": [ "INVOICE 2025-00042" ] } } }, "required": true, "x-position": 2 }, "responses": { "201": { "description": "The settlement transfer was processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountSettlementTransfer" }, "example": { "id": "FT252324K67K", "status": "success", "uniqueIdentifier": "IRFX252332872527361.00", "details": { "creditAmount": { "currency": "USD", "amount": 10.01 }, "debitAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320559, "accountRoutings": [] }, "creditAccountNumber": { "number": 1000076925, "accountRoutings": [] }, "valueDate": "2025-08-20T07:36:00.0000000Z" }, "linkedActivities": [] } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the settlement transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "counter-party-settlement-transaction" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{virtualAccountId}/withdrawals/internal": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Withdraw funds (Internal)", "description": "Initiates an internal withdrawal transfer from a virtual account to an internal destination account.\nThis endpoint allows clients to withdraw funds from a virtual account to an internal account within the institution.\n\n### Key Features:\n- Withdraws funds from a virtual account to an internal destination account\n- Supports idempotency to prevent duplicate transactions\n- Validates account numbers and currency matching\n- Supports both JSON and CSV response formats\n- Automatic virtual account number validation\n\n### Important Notes:\n- The virtualAccountId in the route parameter identifies the source virtual account\n- The creditAccountNumber in the request body specifies the destination internal account\n- Ensure the virtual account has sufficient funds before making the request\n- Virtual accounts must be in an active state to process withdrawals\n\n### Virtual Account Withdrawal Structure\nVirtual account withdrawals transfer funds from virtual accounts to internal accounts:\n```\nVirtual Account → Internal Destination Account\n```\nWhen processing a withdrawal transfer, funds flow from the virtual account to the internal destination account.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{virtualAccountId}/withdrawals/internal\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function withdrawFromVirtualAccount() {\n try {\n const virtualAccountId = \"1000320575\";\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountId}/withdrawals/internal`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitCurrency: \"USD\",\n creditAmount: {\n currency: \"USD\",\n amount: \"100.00\"\n },\n creditAccountNumber: \"1000076925\"\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Withdrawal transfer failed: ${JSON.stringify(errorData)}`);\n }\n\n const data = await response.json();\n console.log('Withdrawal transfer result:', data);\n\n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { debitAmount, valueDate, childTransactionId, creditAmountCurrency, debitAccountNumber, creditAccountNumber } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);\n console.log('Value Date:', valueDate);\n console.log('Child Transaction ID:', childTransactionId);\n console.log('Credit Amount Currency:', creditAmountCurrency);\n\n // Process debit account information (virtual account)\n console.log('Debit Account Number:', debitAccountNumber.number);\n\n // Process credit account information (internal destination)\n console.log('Credit Account Number:', creditAccountNumber.number);\n\n // Process linked activities\n linkedActivities.forEach(activity => {\n console.log('Linked Activity ID:', activity.id);\n console.log('Linked Activity Transaction Status:', activity.transactionStatus);\n console.log('Linked Activity Status:', activity.status);\n console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);\n const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;\n console.log('Linked Activity Arrangement ID:', arrangementId);\n console.log('Linked Activity Activity ID:', activityId);\n console.log('Linked Activity Product ID:', productId);\n console.log('Linked Activity Currency ID:', currencyId);\n console.log('Linked Activity Effective Date:', effectiveDate);\n });\n\n // Final status logging\n if (status === 'success') {\n console.log('The virtual account withdrawal was successful.');\n } else {\n console.log('The virtual account withdrawal failed:', status);\n }\n } catch (error) {\n console.error('Error withdrawing from virtual account:', error);\n }\n}\n\n// Example usage:\nwithdrawFromVirtualAccount();\n```\n\n**Required Permission:** `withdraw-virtual-account`\n\nThis endpoint requires the permission claim `withdraw-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfersWithdrawal_WithdrawalInternal", "parameters": [ { "name": "virtualAccountId", "in": "path", "required": true, "description": "The virtual account number from which funds will be withdrawn.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "debitCurrency": "USD", "creditAmount": { "currency": "USD", "amount": 0.01 }, "creditAccountNumber": 1000076925 } } ], "requestBody": { "x-name": "request", "description": "Payload containing internal withdrawal transfer details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountWithDrawalTransferRequestInternal" }, "example": { "debitCurrency": "USD", "creditAmount": { "currency": "USD", "amount": 0.01 }, "creditAccountNumber": 1000076925 } } }, "required": true, "x-position": 2 }, "responses": { "201": { "description": "The withdrawal transfer was processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountWithdrawalTransfer" }, "example": { "id": "FT252324K67K", "status": "success", "uniqueIdentifier": "IRFX252332872527361.00", "details": { "creditAmount": { "currency": "USD", "amount": 10.01 }, "debitAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320559, "accountRoutings": [] }, "creditAccountNumber": { "number": 1000076925, "accountRoutings": [] }, "valueDate": "2025-08-20T07:36:00.0000000Z" }, "linkedActivities": [] } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the withdrawal transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "withdraw-virtual-account" ] }, { "Authorization": [] } ] } }, "/v1/virtual-accounts/{virtualAccountId}/withdrawals/external": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Withdraw funds (External)", "description": "Corporate Client initiates External Withdrawal request to BCB to debit Virtual Account and credit to External Beneficiary Account.\nThis endpoint allows clients to withdraw funds from a virtual account to an external beneficiary account.\n\n### Key Features:\n- Withdraws funds from a virtual account to an external beneficiary account\n- Supports idempotency to prevent duplicate transactions\n- Supports both JSON and CSV response formats\n- Automatic virtual account number validation\n- Includes comprehensive beneficiary and ordering customer information for external transfers\n- Supports both the existing same-currency payload and the additive cross-currency FX payload\n \n### Supported Request Formats\nUse one of the following request shapes:\n \nExisting format - same-currency:\n```json\n{\n \"debitCurrency\": \"USD\",\n \"creditAmount\": {\n \"currency\": \"USD\",\n \"amount\": 2500\n }\n}\n```\n \nAdditive format - cross-currency FX:\n```json\n{\n \"debitAmount\": {\n \"currency\": \"USD\",\n \"amount\": 2500\n },\n \"creditAmount\": {\n \"currency\": \"HKD\"\n }\n}\n```\n \n### Cross-Currency FX\n- Provide `debitAmount` (currency and amount) when you want the debit side to be authoritative.\n- Provide only `creditAmount.currency` in that case; the bank assigns the exchange rate and final credited amount before forwarding to the beneficiary.\n- If `debitAmount` is omitted, the existing `debitCurrency` + `creditAmount` (currency + amount) format applies with no change to current behaviour.\n \n- `debitCurrency` is not deprecated and remains fully supported.\n- Both payload formats are accepted and return a successful response.\n\n### Important Notes:\n- The virtualAccountId in the route parameter identifies the source virtual account\n- The request body specifies the destination external beneficiary account via `creditorAccount.identification`\n- Ensure the virtual account has sufficient funds before making the request\n- Virtual accounts must be in an active state to process withdrawals\n- External transfers require additional beneficiary information for compliance\n\n### Virtual Account Withdrawal Structure\nVirtual account withdrawals transfer funds from virtual accounts to external beneficiary accounts:\n```\nVirtual Account → External Beneficiary Account\n```\nWhen processing an external withdrawal transfer, funds flow from the virtual account to the external beneficiary account.\n\n### External Transfer Requirements\nExternal transfers require additional information for regulatory compliance:\n- **debitCurrency**: Currency to debit from the virtual account (e.g., \"USD\")\n- **creditAmount**: Amount and currency to credit externally (e.g., { amount: \"2500.00\", currency: \"USD\" })\n- **debtor**: Ordering customer name or reference (required, max 35 characters)\n- **debtorAgent**: Ordering bank/agent identifier (free text, max 35 characters) - Optional\n- **creditorAccount.identification**: External beneficiary account identifier (required, max 35 characters)\n- **creditorAccount.name / additionalInformation**: Beneficiary name and auxiliary details (optional)\n- **chargesType**: Who bears charges (e.g., OUR, BEN, SHA)\n- **creditorAgent**: Beneficiary bank info (identification, name, additionalInformation)\n- **intermediaryAgent** (optional): Intermediary bank info (identification, name, additionalInformation)\n- **remittanceInformation** (optional): Unstructured remittance lines\n \n### Creditor Agent (Beneficiary Bank)\n- If `creditorAgent.identification` (BIC/bank identifier) is provided, `creditorAgent.name` and `creditorAgent.additionalInformation` are optional and may be omitted.\n- If `creditorAgent.identification` is not provided, supply `creditorAgent.name` and `creditorAgent.additionalInformation` to identify the beneficiary bank.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/virtual-accounts/{virtualAccountId}/withdrawals/external\n\n### Sample Request in JavaScript (Existing same-currency format):\n\n```javascript\nasync function processExternalWithdrawal() {\n try {\n const virtualAccountId = \"1000320575\";\n const response = await fetch(`https://api.bcb.bm/v1/virtual-accounts/${virtualAccountId}/withdrawals/external`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitCurrency: \"USD\",\n creditAmount: {\n currency: \"USD\",\n amount: \"2500.00\"\n },\n debtor: \"John Smith Corporation\",\n debtorAgent: \"CHASUS33XXX\",\n creditorAccount: {\n identification: \"GB29NWBK60161331926819\",\n name: \"Acme Manufacturing Ltd\",\n additionalInformation: [\n \"123 Business Street\",\n \"London, UK SW1A 1AA\"\n ]\n },\n chargesType: \"OUR\",\n creditorAgent: {\n identification: \"NWBKGB2L\",\n name: \"NatWest Bank\",\n additionalInformation: [\n \"250 Bishopsgate\",\n \"London, UK EC2M 4AA\"\n ]\n },\n intermediaryAgent: {\n identification: \"CHASUS33\",\n name: \"JPMorgan Chase Bank\",\n additionalInformation: [\n \"383 Madison Avenue\",\n \"New York, NY 10017\"\n ]\n },\n remittanceInformation: [\n \"Withdrawal from Virtual Account VA-2024-001\",\n \"Transfer to external beneficiary account\",\n \"Reference: WD-2024-789456\"\n ]\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`External withdrawal transfer failed: ${JSON.stringify(errorData)}`);\n }\n\n const data = await response.json();\n console.log('External withdrawal transfer result:', data);\n\n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { debitAmount, valueDate, childTransactionId, creditAmountCurrency, debitAccountNumber, creditAccountNumber } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);\n console.log('Value Date:', valueDate);\n console.log('Child Transaction ID:', childTransactionId);\n console.log('Credit Amount Currency:', creditAmountCurrency);\n\n // Process debit account information (virtual account)\n console.log('Debit Account Number:', debitAccountNumber.number);\n\n // Process credit account information (external beneficiary account)\n console.log('Credit Account Number:', creditAccountNumber.number);\n\n // Process linked activities\n linkedActivities.forEach(activity => {\n console.log('Linked Activity ID:', activity.id);\n console.log('Linked Activity Transaction Status:', activity.transactionStatus);\n console.log('Linked Activity Status:', activity.status);\n console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);\n const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;\n console.log('Linked Activity Arrangement ID:', arrangementId);\n console.log('Linked Activity Activity ID:', activityId);\n console.log('Linked Activity Product ID:', productId);\n console.log('Linked Activity Currency ID:', currencyId);\n console.log('Linked Activity Effective Date:', effectiveDate);\n });\n\n // Final status logging\n if (status === 'success') {\n console.log('The external withdrawal was successful.');\n } else {\n console.log('The external withdrawal failed:', status);\n }\n } catch (error) {\n console.error('Error processing external withdrawal:', error);\n }\n}\n\n// Example usage:\nprocessExternalWithdrawal();\n```\n\n**Required Permission:** `withdraw-virtual-account`\n\nThis endpoint requires the permission claim `withdraw-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfersWithdrawal_WithdrawalExternal", "parameters": [ { "name": "virtualAccountId", "in": "path", "required": true, "description": "The virtual account number from which funds will be withdrawn.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "debitAmount": { "currency": "USD", "amount": 2500 }, "creditAmount": { "currency": "HKD" }, "debtor": "John Smith Corporation", "debtorAgent": "CHASUS33XXX", "creditorAccount": { "identification": "GB29NWBK60161331926819", "name": "Acme Manufacturing Ltd", "additionalInformation": [ "123 Business Street", "London, UK SW1A 1AA" ] }, "chargesType": "OUR", "creditorAgent": { "identification": "NWBKGB2L", "name": "NatWest Bank", "additionalInformation": [ "250 Bishopsgate", "London, UK EC2M 4AA" ] }, "intermediaryAgent": { "identification": "CHASUS33", "name": "JPMorgan Chase Bank", "additionalInformation": [ "383 Madison Avenue", "New York, NY 10017" ] }, "remittanceInformation": [ "Withdrawal from Virtual Account VA-2024-001", "Transfer to external beneficiary account", "Reference: WD-2024-789456" ] } } ], "requestBody": { "x-name": "request", "description": "Payload containing external withdrawal transfer details. For FX cross-currency, optional debitAmount (with creditAmount currency only) may be sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountWithDrawalTransferRequestExternal" }, "example": { "debitAmount": { "currency": "USD", "amount": 2500 }, "creditAmount": { "currency": "HKD" }, "debtor": "John Smith Corporation", "debtorAgent": "CHASUS33XXX", "creditorAccount": { "identification": "GB29NWBK60161331926819", "name": "Acme Manufacturing Ltd", "additionalInformation": [ "123 Business Street", "London, UK SW1A 1AA" ] }, "chargesType": "OUR", "creditorAgent": { "identification": "NWBKGB2L", "name": "NatWest Bank", "additionalInformation": [ "250 Bishopsgate", "London, UK EC2M 4AA" ] }, "intermediaryAgent": { "identification": "CHASUS33", "name": "JPMorgan Chase Bank", "additionalInformation": [ "383 Madison Avenue", "New York, NY 10017" ] }, "remittanceInformation": [ "Withdrawal from Virtual Account VA-2024-001", "Transfer to external beneficiary account", "Reference: WD-2024-789456" ] } } }, "required": true, "x-position": 2 }, "responses": { "201": { "description": "The withdrawal transfer was processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountWithdrawalTransfer" }, "example": { "id": "FT252324K67K", "status": "success", "uniqueIdentifier": "IRFX252332872527361.00", "details": { "creditAmount": { "currency": "USD", "amount": 10.01 }, "debitAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320559, "accountRoutings": [] }, "creditAccountNumber": { "number": 1000076925, "accountRoutings": [] }, "valueDate": "2025-08-20T07:36:00.0000000Z" }, "linkedActivities": [] } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the withdrawal transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "withdraw-virtual-account" ] }, { "Authorization": [] } ] } }, "/v2/virtual-accounts/{virtualAccountId}/withdrawals/external": { "post": { "tags": [ "Virtual Accounts" ], "summary": "Withdraw funds (External V2)", "description": "Corporate Client initiates External Withdrawal request to BCB to debit Virtual Account and credit to External Beneficiary Account.\nThis endpoint allows clients to withdraw funds from a virtual account to an external beneficiary account.\n \n**V2 difference:** The `debtor` field is a structured object (`{ name, additionalInformation[] }`) instead of the v1 plain string.\nAll other fields, behaviour, response shape, idempotency, and content negotiation are identical to v1.\n\n### Key Features:\n- Withdraws funds from a virtual account to an external beneficiary account\n- Supports idempotency to prevent duplicate transactions\n- Supports both JSON and CSV response formats\n- Automatic virtual account number validation\n- Includes comprehensive beneficiary and ordering customer information for external transfers\n- Supports both the existing same-currency payload and the additive cross-currency FX payload\n- **V2:** Structured debtor with name and up to 3 address lines\n \n### Structured Debtor (V2)\nThe `debtor` field must be an object containing the ordering customer name and optional address lines:\n```json\n{\n \"debtor\": {\n \"name\": \"John Smith Corporation\",\n \"additionalInformation\": [\n \"123 Business Street\",\n \"London, UK SW1A 1AA\"\n ]\n }\n}\n```\n- `debtor.name`: Required, max 35 characters\n- `debtor.additionalInformation`: Optional, up to 3 lines, each max 35 characters\n \n### Supported Request Formats\nUse one of the following request shapes:\n \nExisting format - same-currency:\n```json\n{\n \"debitCurrency\": \"USD\",\n \"creditAmount\": {\n \"currency\": \"USD\",\n \"amount\": 2500\n }\n}\n```\n \nAdditive format - cross-currency FX:\n```json\n{\n \"debitAmount\": {\n \"currency\": \"USD\",\n \"amount\": 2500\n },\n \"creditAmount\": {\n \"currency\": \"HKD\"\n }\n}\n```\n \n### Cross-Currency FX\n- Provide `debitAmount` (currency and amount) when you want the debit side to be authoritative.\n- Provide only `creditAmount.currency` in that case; the bank assigns the exchange rate and final credited amount before forwarding to the beneficiary.\n- If `debitAmount` is omitted, the existing `debitCurrency` + `creditAmount` (currency + amount) format applies with no change to current behaviour.\n \n- `debitCurrency` is not deprecated and remains fully supported.\n- Both payload formats are accepted and return a successful response.\n\n### Important Notes:\n- The virtualAccountId in the route parameter identifies the source virtual account\n- The request body specifies the destination external beneficiary account via `creditorAccount.identification`\n- Ensure the virtual account has sufficient funds before making the request\n- Virtual accounts must be in an active state to process withdrawals\n- External transfers require additional beneficiary information for compliance\n\n### Virtual Account Withdrawal Structure\nVirtual account withdrawals transfer funds from virtual accounts to external beneficiary accounts:\n```\nVirtual Account → External Beneficiary Account\n```\nWhen processing an external withdrawal transfer, funds flow from the virtual account to the external beneficiary account.\n\n### External Transfer Requirements\nExternal transfers require additional information for regulatory compliance:\n- **debitCurrency**: Currency to debit from the virtual account (e.g., \"USD\")\n- **creditAmount**: Amount and currency to credit externally (e.g., { amount: \"2500.00\", currency: \"USD\" })\n- **debtor**: Ordering customer information as `{ name, additionalInformation[] }` *(V2: structured object; V1 uses a plain string)*\n- **debtor.additionalInformation**: Up to 3 lines, each max 35 characters\n- **debtorAgent**: Ordering bank/agent identifier (free text, max 35 characters) - Optional\n- **creditorAccount.identification**: External beneficiary account identifier (required, max 35 characters)\n- **creditorAccount.name / additionalInformation**: Beneficiary name and auxiliary details (optional)\n- **chargesType**: Who bears charges (e.g., OUR, BEN, SHA)\n- **creditorAgent**: Beneficiary bank info (identification, name, additionalInformation)\n- **intermediaryAgent** (optional): Intermediary bank info (identification, name, additionalInformation)\n- **remittanceInformation** (optional): Unstructured remittance lines\n \n### Creditor Agent (Beneficiary Bank)\n- If `creditorAgent.identification` (BIC/bank identifier) is provided, `creditorAgent.name` and `creditorAgent.additionalInformation` are optional and may be omitted.\n- If `creditorAgent.identification` is not provided, supply `creditorAgent.name` and `creditorAgent.additionalInformation` to identify the beneficiary bank.\n\n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results\n- If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\").\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v2/virtual-accounts/{virtualAccountId}/withdrawals/external\n\n### Sample Request in JavaScript (Cross-currency FX format):\n\n```javascript\nasync function processExternalWithdrawalV2() {\n try {\n const virtualAccountId = \"1000320575\";\n const response = await fetch(`https://api.bcb.bm/v2/virtual-accounts/${virtualAccountId}/withdrawals/external`, {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' // Optional\n },\n body: JSON.stringify({\n debitAmount: {\n currency: \"USD\",\n amount: \"2500.00\"\n },\n creditAmount: {\n currency: \"HKD\"\n },\n debtor: {\n name: \"John Smith Corporation\",\n additionalInformation: [\n \"123 Business Street\",\n \"London, UK SW1A 1AA\"\n ]\n },\n debtorAgent: \"CHASUS33XXX\",\n creditorAccount: {\n identification: \"GB29NWBK60161331926819\",\n name: \"Acme Manufacturing Ltd\",\n additionalInformation: [\n \"123 Business Street\",\n \"London, UK SW1A 1AA\"\n ]\n },\n chargesType: \"OUR\",\n creditorAgent: {\n identification: \"NWBKGB2L\",\n name: \"NatWest Bank\",\n additionalInformation: [\n \"250 Bishopsgate\",\n \"London, UK EC2M 4AA\"\n ]\n },\n intermediaryAgent: {\n identification: \"CHASUS33\",\n name: \"JPMorgan Chase Bank\",\n additionalInformation: [\n \"383 Madison Avenue\",\n \"New York, NY 10017\"\n ]\n },\n remittanceInformation: [\n \"Withdrawal from Virtual Account VA-2024-001\",\n \"Transfer to external beneficiary account\",\n \"Reference: WD-2024-789456\"\n ]\n })\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`External withdrawal transfer failed: ${JSON.stringify(errorData)}`);\n }\n\n const data = await response.json();\n console.log('External withdrawal transfer result:', data);\n\n // Example processing of the returned object\n const { id, status, uniqueIdentifier, details, linkedActivities } = data;\n const { debitAmount, valueDate, childTransactionId, creditAmountCurrency, debitAccountNumber, creditAccountNumber } = details;\n\n // Log the main transfer details\n console.log('Transaction ID:', id);\n console.log('Status:', status);\n console.log('Unique Identifier:', uniqueIdentifier);\n console.log('Debit Amount:', debitAmount.amount, debitAmount.currency);\n console.log('Value Date:', valueDate);\n console.log('Child Transaction ID:', childTransactionId);\n console.log('Credit Amount Currency:', creditAmountCurrency);\n\n // Process debit account information (virtual account)\n console.log('Debit Account Number:', debitAccountNumber.number);\n\n // Process credit account information (external beneficiary account)\n console.log('Credit Account Number:', creditAccountNumber.number);\n\n // Process linked activities\n linkedActivities.forEach(activity => {\n console.log('Linked Activity ID:', activity.id);\n console.log('Linked Activity Transaction Status:', activity.transactionStatus);\n console.log('Linked Activity Status:', activity.status);\n console.log('Linked Activity Unique Identifier:', activity.uniqueIdentifier);\n const { arrangementId, activityId, productId, currencyId, effectiveDate } = activity.activityDetails;\n console.log('Linked Activity Arrangement ID:', arrangementId);\n console.log('Linked Activity Activity ID:', activityId);\n console.log('Linked Activity Product ID:', productId);\n console.log('Linked Activity Currency ID:', currencyId);\n console.log('Linked Activity Effective Date:', effectiveDate);\n });\n\n // Final status logging\n if (status === 'success') {\n console.log('The external withdrawal was successful.');\n } else {\n console.log('The external withdrawal failed:', status);\n }\n } catch (error) {\n console.error('Error processing external withdrawal:', error);\n }\n}\n\n// Example usage:\nprocessExternalWithdrawalV2();\n```\n\n**Required Permission:** `withdraw-virtual-account`\n\nThis endpoint requires the permission claim `withdraw-virtual-account` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "VirtualAccountsTransfersWithdrawal_WithdrawalExternalV2", "parameters": [ { "name": "virtualAccountId", "in": "path", "required": true, "description": "The virtual account number from which funds will be withdrawn.", "schema": { "type": "string", "maxLength": 36, "minLength": 1 }, "x-position": 1, "example": { "debitAmount": { "currency": "USD", "amount": 2500 }, "creditAmount": { "currency": "HKD" }, "debtor": { "name": "John Smith Corporation", "additionalInformation": [ "123 Business Street", "London, UK SW1A 1AA" ] }, "debtorAgent": "CHASUS33XXX", "creditorAccount": { "identification": "GB29NWBK60161331926819", "name": "Acme Manufacturing Ltd", "additionalInformation": [ "123 Business Street", "London, UK SW1A 1AA" ] }, "chargesType": "OUR", "creditorAgent": { "identification": "NWBKGB2L", "name": "NatWest Bank", "additionalInformation": [ "250 Bishopsgate", "London, UK EC2M 4AA" ] }, "intermediaryAgent": { "identification": "CHASUS33", "name": "JPMorgan Chase Bank", "additionalInformation": [ "383 Madison Avenue", "New York, NY 10017" ] }, "remittanceInformation": [ "Withdrawal from Virtual Account VA-2024-001", "Transfer to external beneficiary account", "Reference: WD-2024-789456" ] } } ], "requestBody": { "x-name": "request", "description": "Payload containing external withdrawal transfer details. V2 uses a structured debtor object (`{ name, additionalInformation[] }`) instead of a plain string. For FX cross-currency, optional debitAmount (with creditAmount currency only) may be sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountWithDrawalTransferRequestExternalV2" }, "example": { "debitAmount": { "currency": "USD", "amount": 2500 }, "creditAmount": { "currency": "HKD" }, "debtor": { "name": "John Smith Corporation", "additionalInformation": [ "123 Business Street", "London, UK SW1A 1AA" ] }, "debtorAgent": "CHASUS33XXX", "creditorAccount": { "identification": "GB29NWBK60161331926819", "name": "Acme Manufacturing Ltd", "additionalInformation": [ "123 Business Street", "London, UK SW1A 1AA" ] }, "chargesType": "OUR", "creditorAgent": { "identification": "NWBKGB2L", "name": "NatWest Bank", "additionalInformation": [ "250 Bishopsgate", "London, UK EC2M 4AA" ] }, "intermediaryAgent": { "identification": "CHASUS33", "name": "JPMorgan Chase Bank", "additionalInformation": [ "383 Madison Avenue", "New York, NY 10017" ] }, "remittanceInformation": [ "Withdrawal from Virtual Account VA-2024-001", "Transfer to external beneficiary account", "Reference: WD-2024-789456" ] } } }, "required": true, "x-position": 2 }, "responses": { "201": { "description": "The withdrawal transfer was processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountTransferOfVirtualAccountWithdrawalTransfer" }, "example": { "id": "FT252324K67K", "status": "success", "uniqueIdentifier": "IRFX252332872527361.00", "details": { "creditAmount": { "currency": "USD", "amount": 10.01 }, "debitAmountCurrency": "USD", "debitAccountNumber": { "number": 1000320559, "accountRoutings": [] }, "creditAccountNumber": { "number": 1000076925, "accountRoutings": [] }, "valueDate": "2025-08-20T07:36:00.0000000Z" }, "linkedActivities": [] } } } }, "400": { "description": "The request is invalid; verify account numbers, amounts, and ensure currencies match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An error occurred processing the withdrawal transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "withdraw-virtual-account" ] }, { "Authorization": [] } ] } }, "/v1/notifications/subscriptions": { "post": { "tags": [ "Notifications" ], "summary": "Create a new notification subscription", "description": "Registers a webhook subscription to receive real-time deposit notifications.\n\n### Notification Pipeline Overview:\nThis endpoint is part of a two-stage deposit notification system:\n\n**Stage 1: Subscription Setup** (this endpoint)\n- Customers register their webhook URL and topic (e.g., \"Deposits\")\n- The system stores the subscription with optional custom headers\n- Subscriptions can be activated or deactivated\n\n**Stage 2: Webhook Delivery**\n- The system matches received events with active subscriptions\n- Webhooks are delivered to registered endpoints with retry logic\n\n### Webhook Payload Structure:\nWhen a deposit matches your subscription, you'll receive a POST request to your webhook URL containing:\n```json\n{\n \"subscriptionId\": \"e2a55504-3924-4b48-9d7e-540efcd6fa30\",\n \"topic\": \"Deposits\",\n \"accountNumber\": \"1046406142\",\n \"transactionId\": \"FT2384654NXF6\",\n \"type\": \"Credit\",\n \"value\": {\n \"amount\": \"1000.00\",\n \"currency\": \"USD\"\n },\n \"transactionType\": \"Swift payment\",\n \"transactionDetails\": \"Payment details\"\n}\n```\n\nThe webhook payload is defined by the `NotificationResponse` model.\n\n### Message Signing:\nWebhook requests are signed for authenticity and replay protection.\n- **Asymmetric option (RSA-PSS + SHA-256):** When response signing is enabled for your client configuration, webhooks include `Bcb-Signature`, `Bcb-Timestamp`, `Bcb-Nonce`, and `Bcb-Signature-Version` (e.g., `rsa-v1`). Verify using the bank public key from `/v1/.well-known/jwks.json` and the canonical string `{timestamp}{nonce}{METHOD}{path}{body}`.\n- **HMAC option:** If `Bcb-Signature-Version` is absent, the webhook uses your Message Signing Secret returned by the credentials endpoints. Use the same signature string `{timestamp}{nonce}{METHOD}{path}{body}` and compare an HMAC-SHA256 hash.\n- **Replay protection:** Enforce ±5 minute timestamp tolerance and reject any repeated `{timestamp}:{nonce}` pairs (cache the nonce for 5 minutes).\nSee the Message Signing guide for full RSA and HMAC verification examples.\n\n### Idempotency:\nThis endpoint supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally\n- If a valid UUID idempotency key is provided, the system prevents duplicate subscriptions\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\")\n\n**Required Permission:** `receive-notifications`\n\nThis endpoint requires the permission claim `receive-notifications` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Notifications_Create", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeRequest" }, "example": { "topic": "Deposits", "callbackUrl": "https://your-webhook-endpoint.example.com/notifications/deposits", "customHeaders": { "X-Custom-Header": "your-custom-value", "X-Api-Key": "your-api-key" } } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSubscription" }, "example": { "subscriptionId": "e2a55504-3924-4b48-9d7e-540efcd6fa30", "topic": 0, "webhookUrl": "https://your-webhook-endpoint.example.com/notifications/deposits", "isActive": true, "createdUtc": "2025-01-15T11:30:00.0000000+01:00", "updatedUtc": "2025-01-15T11:30:00.0000000+01:00", "customHeaders": { "X-Custom-Header": "your-custom-value", "X-Api-Key": "your-api-key" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "receive-notifications" ] }, { "Authorization": [] } ] }, "get": { "tags": [ "Notifications" ], "summary": "List subscriptions", "description": "Retrieves all notification subscriptions for the authenticated client with pagination support.\n\n### Pagination:\n- Use `pageStart` to specify the starting page (default: 1)\n- Use `pageSize` to specify the number of items per page (default: 100, max: 500)\n- The response includes total count and pagination metadata\n\n### Response Details:\nReturns a paginated list of subscriptions, each containing:\n- Subscription ID (guid)\n- Topic (e.g., \"Deposits\")\n- Webhook URL\n- Status (IsActive flag)\n- Creation and update timestamps\n\n### Filtering:\n- Only returns subscriptions owned by the authenticated client\n- Includes both active and inactive subscriptions\n- Results are ordered by creation date (newest first)\n\n**Required Permission:** `receive-notifications`\n\nThis endpoint requires the permission claim `receive-notifications` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Notifications_GetAll", "parameters": [ { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 1 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 2 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfNotificationSubscriptionOf" }, "example": { "meta": { "pagination": { "pageStart": 1, "pageToken": "", "totalSize": 2, "pageSize": 100 } }, "data": [ { "subscriptionId": "e2a55504-3924-4b48-9d7e-540efcd6fa30", "topic": 0, "webhookUrl": "https://your-webhook-endpoint.example.com/notifications/deposits", "isActive": true, "createdUtc": "2025-01-15T11:30:00.0000000+01:00", "updatedUtc": "2025-01-15T11:30:00.0000000+01:00", "customHeaders": { "X-Custom-Header": "your-custom-value" } }, { "subscriptionId": "f3b66615-4035-5c59-ae8f-651f9de7cb41", "topic": 0, "webhookUrl": "https://backup-webhook.example.com/deposits", "isActive": false, "createdUtc": "2025-01-10T09:15:00.0000000+01:00", "updatedUtc": "2025-01-14T17:45:00.0000000+01:00", "customHeaders": null } ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "receive-notifications" ] }, { "Authorization": [] } ] } }, "/v1/notifications/subscriptions/{subscriptionId}": { "delete": { "tags": [ "Notifications" ], "summary": "Deactivate a subscription", "description": "Deactivates an existing notification subscription. Once deactivated:\n- The subscription will no longer receive webhook notifications\n- Future deposits will not be matched to this subscription\n- In-flight notifications will continue to be delivered\n- The subscription record remains in the system but with IsActive=false\n\n### Behavior:\n- Only the subscription owner can deactivate their own subscription\n- Attempting to deactivate another client's subscription returns 404 Not Found\n- Deactivating an already inactive subscription is idempotent (returns success)\n\n### Idempotency:\nThis endpoint supports idempotency through the optional `Idempotency-Key` header:\n- If a valid UUID idempotency key is provided, repeated calls with the same key return the same result\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\")\n\n**Required Permission:** `receive-notifications`\n\nThis endpoint requires the permission claim `receive-notifications` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Notifications_Delete", "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "guid" }, "x-position": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSubscription" }, "example": { "subscriptionId": "e2a55504-3924-4b48-9d7e-540efcd6fa30", "topic": 0, "webhookUrl": "https://your-webhook-endpoint.example.com/notifications/deposits", "isActive": true, "createdUtc": "2025-01-15T11:30:00.0000000+01:00", "updatedUtc": "2025-01-15T11:30:00.0000000+01:00", "customHeaders": { "X-Custom-Header": "your-custom-value", "X-Api-Key": "your-api-key" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "receive-notifications" ] }, { "Authorization": [] } ] }, "get": { "tags": [ "Notifications" ], "summary": "Get subscription", "description": "Retrieves a specific notification subscription by its unique identifier.\n\n### Response Details:\nThe response includes:\n- Subscription ID (guid)\n- Topic (e.g., \"Deposits\")\n- Webhook URL\n- Status (IsActive flag)\n- Creation and update timestamps\n- Client association\n\n### Security:\n- Only the subscription owner can retrieve their own subscription\n- Attempting to retrieve another client's subscription returns 404 Not Found\n\n**Required Permission:** `receive-notifications`\n\nThis endpoint requires the permission claim `receive-notifications` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "Notifications_Get", "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "guid" }, "x-position": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSubscription" }, "example": { "subscriptionId": "e2a55504-3924-4b48-9d7e-540efcd6fa30", "topic": 0, "webhookUrl": "https://your-webhook-endpoint.example.com/notifications/deposits", "isActive": true, "createdUtc": "2025-01-15T11:30:00.0000000+01:00", "updatedUtc": "2025-01-15T11:30:00.0000000+01:00", "customHeaders": { "X-Custom-Header": "your-custom-value", "X-Api-Key": "your-api-key" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "receive-notifications" ] }, { "Authorization": [] } ] } }, "/v1/jobs": { "get": { "tags": [ "Background Jobs" ], "summary": "Get All Background Jobs", "description": "Retrieves a paginated list of background jobs for the authenticated client. This endpoint:\n\n- Returns only **active** jobs (status: Pending or InProgress)\n- Completed, failed, or cancelled jobs are not included in this list\n- Provides job status information including progress summaries\n- Supports pagination for efficient handling of large job datasets\n\n### Job Status Information\nEach job entry includes:\n- **JobId**: Unique identifier for the batch job\n- **JobStatus**: Current status (Pending, InProgress, Completed, CompletedWithErrors, Cancelled)\n - **Pending**: Job has been created and is waiting to be processed\n - **InProgress**: Job is currently being processed \n - **Completed**: Job has completed successfully with no errors\n - **CompletedWithErrors**: Job has completed but some items failed during processing\n - **Cancelled**: Job has been cancelled and will not be processed further\n- **EventType**: Type of status event (typically \"job.status\")\n- **Summary**: Progress statistics (Total, Completed, Failed counts)\n\n### Pagination\nThis endpoint uses simple numeric pagination:\n- **pageStart**: 1-based index of the first record to return (default: 1)\n- **pageSize**: Number of records to return (default: 100, maximum: 1000)\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from response metadata\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/jobs\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getAllBackgroundJobs(pageStart = 1, pageSize = 50) {\n try {\n // Build URL with pagination parameters\n let url = 'https://api.bcb.bm/v1/jobs';\n const params = new URLSearchParams();\n \n params.append('pageStart', pageStart.toString());\n params.append('pageSize', pageSize.toString());\n \n url += '?' + params.toString();\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Background jobs retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n\n // Access pagination info\n const pagination = result.meta.pagination;\n console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);\n\n // Process background jobs\n result.data.forEach((job, index) => {\n console.log(`Job ${index + 1}:`);\n console.log(` Job ID: ${job.jobId}`);\n console.log(` Status: ${job.jobStatus}`);\n console.log(` Event Type: ${job.eventType}`);\n console.log(` Summary:`);\n console.log(` Total: ${job.summary.total}`);\n console.log(` Completed: ${job.summary.completed}`);\n console.log(` Failed: ${job.summary.failed}`);\n console.log('---');\n });\n\n return result;\n } catch (error) {\n console.error('Failed to retrieve background jobs:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get first 50 jobs\ngetAllBackgroundJobs(1, 50);\n\n// Get next page\ngetAllBackgroundJobs(2, 50);\n\n// Get all jobs with default pagination\ngetAllBackgroundJobs();\n```", "operationId": "BackgroundJobs_GetAll", "parameters": [ { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 1 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 2 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfBatchStatusOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "", "totalSize": 3, "pageSize": 100 } }, "data": [ { "eventType": "job.status", "jobId": "550e8400-e29b-41d4-a716-446655440001", "jobStatus": "InProgress", "summary": { "total": 150, "completed": 45, "failed": 2 } }, { "eventType": "job.status", "jobId": "550e8400-e29b-41d4-a716-446655440002", "jobStatus": "Pending", "summary": { "total": 75, "completed": 0, "failed": 0 } }, { "eventType": "job.status", "jobId": "550e8400-e29b-41d4-a716-446655440003", "jobStatus": "InProgress", "summary": { "total": 200, "completed": 200, "failed": 0 } } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_event_type\",\"data_0_job_id\",\"data_0_job_status\",\"data_0_summary_total\",\"data_0_summary_completed\",\"data_0_summary_failed\",\"data_1_event_type\",\"data_1_job_id\",\"data_1_job_status\",\"data_1_summary_total\",\"data_1_summary_completed\",\"data_1_summary_failed\",\"data_2_event_type\",\"data_2_job_id\",\"data_2_job_status\",\"data_2_summary_total\",\"data_2_summary_completed\",\"data_2_summary_failed\"", "\"1\",\"\",\"3\",\"100\",\"job.status\",\"550e8400-e29b-41d4-a716-446655440001\",\"InProgress\",\"150\",\"45\",\"2\",\"job.status\",\"550e8400-e29b-41d4-a716-446655440002\",\"Pending\",\"75\",\"0\",\"0\",\"job.status\",\"550e8400-e29b-41d4-a716-446655440003\",\"InProgress\",\"200\",\"200\",\"0\"" ] } } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [] } ] } }, "/v1/jobs/{jobId}": { "get": { "tags": [ "Background Jobs" ], "summary": "Get Job Status", "description": "Retrieves the current status and progress information for a specific background job. This endpoint:\n\n- Returns detailed status information for the specified job\n- Provides real-time progress statistics (total, completed, failed counts)\n- Shows current job status (Pending, InProgress, Completed, Failed, Cancelled)\n- Includes event type information for status tracking\n\n### Job Status Information\nThe response includes:\n- **JobId**: Unique identifier for the batch job\n- **JobStatus**: Current status (Pending, InProgress, Completed, CompletedWithErrors, Cancelled)\n - **Pending**: Job has been created and is waiting to be processed\n - **InProgress**: Job is currently being processed \n - **Completed**: Job has completed successfully with no errors\n - **CompletedWithErrors**: Job has completed but some items failed during processing\n - **Cancelled**: Job has been cancelled and will not be processed further\n- **EventType**: Type of status event (typically \"job.status\")\n- **Summary**: Progress statistics (Total, Completed, Failed counts)\n\n### Callback Notifications\nWhen a job reaches a completed state (Completed or CompletedWithErrors), the system automatically sends a callback notification to the `callbackUrl` provided during job creation (if specified).\nThis callback allows you to receive real-time notifications without polling the status endpoint.\n\n**Sample Callback Payload:**\n```json\n{\n \"eventType\": \"job.completed\",\n \"jobId\": \"badabb89-8cdb-4d3d-aaf0-c714f487f1bc\",\n \"jobStatus\": \"Completed\",\n \"summary\": {\n \"total\": 1,\n \"completed\": 1,\n \"failed\": 0\n }\n}\n```\n\n### Message Signing\nCallback notifications are signed. When your client configuration enables response signing, callbacks use the asymmetric option (RSA-PSS + SHA-256) and include `Bcb-Signature`, `Bcb-Timestamp`, `Bcb-Nonce`, and `Bcb-Signature-Version` (e.g., `rsa-v1`). If asymmetry is not configured, callbacks use the HMAC option with your Message Signing Secret and no `Bcb-Signature-Version` header. See the Message Signing guide for verification steps.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/jobs/{jobId}\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getJobStatus(jobId) {\n try {\n const url = `https://api.bcb.bm/v1/jobs/${jobId}`;\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Job status retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const jobStatus = await response.json();\n\n // Display job information\n console.log('Job Status:');\n console.log(` Job ID: ${jobStatus.jobId}`);\n console.log(` Status: ${jobStatus.jobStatus}`);\n console.log(` Event Type: ${jobStatus.eventType}`);\n console.log(` Progress Summary:`);\n console.log(` Total Items: ${jobStatus.summary.total}`);\n console.log(` Completed: ${jobStatus.summary.completed}`);\n console.log(` Failed: ${jobStatus.summary.failed}`);\n console.log(` Progress: ${((jobStatus.summary.completed / jobStatus.summary.total) * 100).toFixed(1)}%`);\n\n return jobStatus;\n } catch (error) {\n console.error('Failed to retrieve job status:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get status for a specific job\ngetJobStatus('550e8400-e29b-41d4-a716-446655440001');\n```", "operationId": "BackgroundJobs_Get", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The unique identifier of the background job to retrieve status for.", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" }, "examples": { "Json": { "value": { "eventType": "job.status", "jobId": "550e8400-e29b-41d4-a716-446655440001", "jobStatus": "InProgress", "summary": { "total": 150, "completed": 45, "failed": 2 } } }, "Csv": { "value": [ "\"event_type\",\"job_id\",\"job_status\",\"summary_total\",\"summary_completed\",\"summary_failed\"", "\"job.status\",\"550e8400-e29b-41d4-a716-446655440001\",\"InProgress\",\"150\",\"45\",\"2\"" ] } } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "tags": [ "Background Jobs" ], "summary": "Cancel Job", "description": "Cancels a background job and stops processing of all pending and in-progress items. This endpoint:\n\n- Cancels the specified job if it's in a cancellable state\n- Stops processing of all pending and in-progress items within the job\n- Marks cancelled items with appropriate error messages\n- Returns the updated job status after cancellation\n- Provides immediate feedback on cancellation success\n\n### Cancellation Rules\nA job can only be cancelled if it's in one of these states:\n- **Pending**: Job has been created but not yet started processing\n- **InProgress**: Job is currently being processed\n\nJobs in these states **cannot** be cancelled:\n- **Completed**: Job has already finished successfully\n- **CompletedWithErrors**: Job has finished with some failures\n- **Cancelled**: Job has already been cancelled\n\n### What Happens During Cancellation\n1. **Job Status Update**: The job status is changed to \"Cancelled\"\n2. **Item Cancellation**: All pending and in-progress items are marked as \"Cancelled\"\n3. **Error Messages**: Cancelled items receive the error message \"Job was cancelled by user request\"\n4. **Counter Updates**: Job completion counters are recalculated from the database\n5. **Immediate Effect**: Processing stops immediately for all affected items\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/jobs/{jobId}\n \n### Idempotency\nThe API supports idempotency through the optional `Idempotency-Key` header:\n- If no idempotency key is provided, the request is processed normally (duplicates are possible)\n- If a valid UUID idempotency key is provided, the system stores the key and associates it with the batch job\n- If the same idempotency key is received again, the system returns the previously stored response\n- Idempotency keys are user-specific - different users with the same keys don't share cached responses\n- The idempotency key must be a valid UUID format (e.g., \"123e4567-e89b-12d3-a456-426614174000\")\n\n### Sample Request in JavaScript\n \n```javascript\nasync function cancelJob(jobId) {\n try {\n const url = `https://api.bcb.bm/v1/jobs/${jobId}`;\n\n const response = await fetch(url, {\n method: 'DELETE',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Job cancellation failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const jobStatus = await response.json();\n\n // Display cancellation result\n console.log('Job Cancellation Result:');\n console.log(` Job ID: ${jobStatus.jobId}`);\n console.log(` Status: ${jobStatus.jobStatus}`);\n console.log(` Event Type: ${jobStatus.eventType}`);\n console.log(` Final Summary:`);\n console.log(` Total Items: ${jobStatus.summary.total}`);\n console.log(` Completed: ${jobStatus.summary.completed}`);\n console.log(` Failed: ${jobStatus.summary.failed}`);\n console.log(` Cancelled: ${jobStatus.summary.total - jobStatus.summary.completed - jobStatus.summary.failed}`);\n\n return jobStatus;\n } catch (error) {\n console.error('Failed to cancel job:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Cancel a specific job\ncancelJob('550e8400-e29b-41d4-a716-446655440001');\n```", "operationId": "BackgroundJobs_CancelJob", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The unique identifier of the background job to cancel.", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The job was cancelled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" }, "example": { "eventType": "job.status", "jobId": "550e8400-e29b-41d4-a716-446655440001", "jobStatus": "InProgress", "summary": { "total": 150, "completed": 45, "failed": 2 } } } } }, "400": { "description": "Bad Request – Validation failed or job cannot be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - The specified job was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - The job cannot be cancelled in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [] } ] } }, "/v1/jobs/{jobId}/results": { "get": { "tags": [ "Background Jobs" ], "summary": "Get Job Results", "description": "Retrieves the detailed results for a specific background job. This endpoint:\n\n- Returns paginated results for all items processed in the job\n- Provides detailed information about each item's processing outcome\n- Shows processing status, attempts, HTTP responses, and error details\n- Includes original payload and result data for auditing\n- Supports pagination for efficient handling of large result sets\n\n### Job Results Information\nEach result entry includes:\n- **Id**: Internal numeric identifier for this item result\n- **JobId**: Identifier of the parent batch job\n- **ExternalItemId**: Client-supplied item identifier from the original batch\n- **PayloadJson**: Original request payload serialized as JSON\n- **Status**: Current processing status (Pending, InProgress, Completed, Failed, Cancelled)\n- **Attempt**: Number of processing attempts made for this item\n- **HttpStatusCode**: HTTP status code returned by the target endpoint\n- **ResultJson**: Response payload from the target endpoint (if successful)\n- **ErrorMessage**: Error details (if processing failed)\n\n### Pagination\nThis endpoint uses simple numeric pagination:\n- **pageStart**: 1-based index of the first record to return (default: 1)\n- **pageSize**: Number of records to return (default: 100, maximum: 1000)\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from response metadata\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/jobs/{jobId}/results\n\n### Sample Request in JavaScript\n \n```javascript\nasync function getJobResults(jobId, pageStart = 1, pageSize = 50) {\n try {\n const url = `https://api.bcb.bm/v1/jobs/${jobId}/results`;\n const params = new URLSearchParams();\n \n params.append('pageStart', pageStart.toString());\n params.append('pageSize', pageSize.toString());\n \n const fullUrl = url + '?' + params.toString();\n\n const response = await fetch(fullUrl, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Job results retrieval failed: ${JSON.stringify(errorData)}`);\n }\n\n // Parse JSON response\n const result = await response.json();\n\n // Access pagination info\n const pagination = result.meta.pagination;\n console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);\n\n // Process job results\n result.data.forEach((item, index) => {\n console.log(`Result ${index + 1}:`);\n console.log(` Item ID: ${item.externalItemId}`);\n console.log(` Status: ${item.status}`);\n console.log(` Attempts: ${item.attempt}`);\n console.log(` HTTP Status: ${item.httpStatusCode}`);\n \n if (item.errorMessage) {\n console.log(` Error: ${item.errorMessage}`);\n }\n \n if (item.resultJson) {\n console.log(` Result: ${item.resultJson}`);\n }\n \n console.log('---');\n });\n\n return result;\n } catch (error) {\n console.error('Failed to retrieve job results:', error.message);\n throw error;\n }\n}\n\n// Example usage:\n\n// Get first 50 results for a job\ngetJobResults('550e8400-e29b-41d4-a716-446655440001', 1, 50);\n\n// Get next page of results\ngetJobResults('550e8400-e29b-41d4-a716-446655440001', 2, 50);\n\n// Get all results with default pagination\ngetJobResults('550e8400-e29b-41d4-a716-446655440001');\n```", "operationId": "BackgroundJobs_GetResults", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The unique identifier of the background job to retrieve results for.", "schema": { "type": "string" }, "x-position": 1 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 2 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 3 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfBatchJobResultOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "", "totalSize": 3, "pageSize": 100 } }, "data": [ { "id": "fa45cf2a-d8e1-45f3-b021-bb8415492d39", "jobId": "550e8400-e29b-41d4-a716-446655440001", "externalItemId": "item-001", "payloadJson": "{\"accountNumber\":\"1000326948\",\"amount\":\"1000.00\",\"currency\":\"USD\"}", "status": 2, "attempt": 1, "httpStatus": 200, "error": null, "resultJson": "{\"transactionId\":\"TXN-12345\",\"status\":\"success\",\"reference\":\"REF-001\"}", "createdUtc": "2026-01-15T11:30:00.0000000Z", "finishedUtc": "2026-01-15T11:35:00.0000000Z" }, { "id": "79f61a11-0ba1-48c0-842f-a01c56a1c67a", "jobId": "550e8400-e29b-41d4-a716-446655440001", "externalItemId": "item-002", "payloadJson": "{\"accountNumber\":\"1000326949\",\"amount\":\"2500.00\",\"currency\":\"USD\"}", "status": 3, "attempt": 3, "httpStatus": 400, "error": "Invalid account number provided", "resultJson": null, "createdUtc": "2026-01-15T11:30:00.0000000Z", "finishedUtc": "2026-01-15T11:40:00.0000000Z" }, { "id": "0be3b65d-e919-4f5f-a1eb-20a8195ff5a4", "jobId": "550e8400-e29b-41d4-a716-446655440001", "externalItemId": "item-003", "payloadJson": "{\"accountNumber\":\"1000326950\",\"amount\":\"500.00\",\"currency\":\"USD\"}", "status": 1, "attempt": 1, "httpStatus": 0, "error": null, "resultJson": null, "createdUtc": "2026-01-15T11:45:00.0000000Z", "finishedUtc": null } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_id\",\"data_0_job_id\",\"data_0_external_item_id\",\"data_0_payload_json\",\"data_0_status\",\"data_0_attempt\",\"data_0_http_status\",\"data_0_result_json\",\"data_0_created_utc\",\"data_0_finished_utc\",\"data_1_id\",\"data_1_job_id\",\"data_1_external_item_id\",\"data_1_payload_json\",\"data_1_status\",\"data_1_attempt\",\"data_1_http_status\",\"data_1_error\",\"data_1_created_utc\",\"data_1_finished_utc\",\"data_2_id\",\"data_2_job_id\",\"data_2_external_item_id\",\"data_2_payload_json\",\"data_2_status\",\"data_2_attempt\",\"data_2_http_status\",\"data_2_created_utc\"", "\"1\",\"\",\"3\",\"100\",\"fa45cf2a-d8e1-45f3-b021-bb8415492d39\",\"550e8400-e29b-41d4-a716-446655440001\",\"item-001\",\"{\"\"accountNumber\"\":\"\"1000326948\"\",\"\"amount\"\":\"\"1000.00\"\",\"\"currency\"\":\"\"USD\"\"}\",\"2\",\"1\",\"200\",\"{\"\"transactionId\"\":\"\"TXN-12345\"\",\"\"status\"\":\"\"success\"\",\"\"reference\"\":\"\"REF-001\"\"}\",\"2026-01-15T11:30:00Z\",\"2026-01-15T11:35:00Z\",\"79f61a11-0ba1-48c0-842f-a01c56a1c67a\",\"550e8400-e29b-41d4-a716-446655440001\",\"item-002\",\"{\"\"accountNumber\"\":\"\"1000326949\"\",\"\"amount\"\":\"\"2500.00\"\",\"\"currency\"\":\"\"USD\"\"}\",\"3\",\"3\",\"400\",\"Invalid account number provided\",\"2026-01-15T11:30:00Z\",\"2026-01-15T11:40:00Z\",\"0be3b65d-e919-4f5f-a1eb-20a8195ff5a4\",\"550e8400-e29b-41d4-a716-446655440001\",\"item-003\",\"{\"\"accountNumber\"\":\"\"1000326950\"\",\"\"amount\"\":\"\"500.00\"\",\"\"currency\"\":\"\"USD\"\"}\",\"1\",\"1\",\"0\",\"2026-01-15T11:45:00Z\"" ] } } } } }, "400": { "description": "Bad Request – Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [] } ] } }, "/v1/system/time": { "get": { "tags": [ "System" ], "summary": "Get system time", "description": "Returns the current server date and time in ISO-8601 format. \nThis endpoint helps integrators synchronize with the server clock and craft valid date/time windows for other API requests.\n\nThe response contains **two fields**:\n1. timestamp – Current Bermuda local time in ISO-8601 format with the correct offset (e.g., 2025-01-07T14:30:15-04:00).\n2. timeZone – Display name of the time zone currently in effect (\"Atlantic Daylight Time\" or \"Atlantic Standard Time\").\n \nThis allows clients to know both the precise instant and whether Daylight-Saving Time is observed.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/system/time\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function getSystemTime() {\n try {\n const response = await fetch('https://api.bcb.bm/v1/system/time', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log('Server timestamp (Bermuda time UTC-4):', data.timestamp);\n\n return data;\n } catch (error) {\n console.error('There was a problem retrieving system time:', error.message);\n }\n}\n\n// Example usage:\ngetSystemTime();\n```", "operationId": "System_GetSystemTime", "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemTimeResponse" }, "example": { "timestamp": "2025-01-07T19:30:15.1230000+01:00", "timeZone": "Atlantic Standard Time" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [] } ] } }, "/v1/accounts/{accountNumber}/payments": { "get": { "tags": [ "Payments", "Accounts" ], "summary": "List payment statuses for an account", "description": "Retrieves status information for all payments associated with a specific account. This endpoint:\n \n- Provides comprehensive payment status details including type, status, transaction ID, external reference, remittance information, amounts, value date, and exchange rate.\n- Supports both JSON and CSV response formats based on the Accept header.\n- **Supports cursor-based pagination** for efficient handling of large payment status datasets.\n\n### Pagination\nThis endpoint uses cursor-based pagination with server-side result-set management:\n- **First Request**: Optionally specify `pageSize` (default: 100, max: 1000). The server creates a cursor and returns a `pageToken`.\n- **Subsequent Requests**: Use the `pageToken` from previous responses with `pageStart` to navigate pages.\n- **Page Token**: Contains encoded pagination context including pageSize, so don't specify `pageSize` in subsequent requests.\n- **Total Pages**: Calculate using `Math.ceil(total_size / page_size)` from the response metadata.\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/accounts/{accountNumber}/payments\n\n### Sample Request in JavaScript\n\n```javascript\nasync function getAllPaymentStatusesPaginated(accountNumber) {\n try {\n let allPaymentStatuses = [];\n let pageStart = 1;\n let pageToken = null;\n let totalPages = 0;\n\n do {\n // Build URL with pagination parameters\n let url = `https://api.bcb.bm/v1/accounts/${accountNumber}/payments`;\n const params = new URLSearchParams();\n \n if (pageStart === 1) {\n // First request: specify pageSize\n params.append('pageSize', '100');\n } else {\n // Subsequent requests: use pageToken and pageStart\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n if (params.toString()) {\n url += '?' + params.toString();\n }\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log(`Page ${pageStart} data:`, data);\n\n // Store pagination info from first request\n if (pageStart === 1 && data.meta && data.meta.pagination) {\n pageToken = data.meta.pagination.page_token;\n totalPages = Math.ceil(data.meta.pagination.total_size / data.meta.pagination.page_size);\n console.log(`Total pages: ${totalPages}, Page token: ${pageToken}`);\n }\n\n // Collect payment statuses from this page\n if (data.data && data.data.length > 0) {\n allPaymentStatuses.push(...data.data);\n console.log(`Collected ${data.data.length} payment statuses from page ${pageStart}`);\n }\n\n pageStart++;\n } while (pageStart <= totalPages);\n\n console.log(`Total payment statuses collected: ${allPaymentStatuses.length}`);\n\n // Process all collected payment statuses\n allPaymentStatuses.forEach((payment, index) => {\n console.log(`Payment ${index + 1}:`, payment.transactionId);\n console.log('Type:', payment.type);\n console.log('Status:', payment.status);\n console.log('External Reference:', payment.externalReference);\n console.log('Remittance Information:', payment.remittanceInformation);\n console.log('Value Date:', payment.valueDate);\n console.log('Debit Amount:', `${payment.debitAmount.amount} ${payment.debitAmount.currency}`);\n if (payment.creditAmount && payment.creditAmount.amount) {\n console.log('Credit Amount:', `${payment.creditAmount.amount} ${payment.creditAmount.currency}`);\n }\n console.log('-------------------');\n });\n\n return allPaymentStatuses;\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n throw error;\n }\n}\n\n// Alternative: Get single page of payment statuses\nasync function getPaymentStatusesPage(accountNumber, pageStart = 1, pageToken = null) {\n try {\n let url = `https://api.bcb.bm/v1/accounts/${accountNumber}/payments`;\n const params = new URLSearchParams();\n \n if (pageStart === 1 && !pageToken) {\n params.append('pageSize', '50'); // Custom page size\n } else {\n params.append('pageToken', pageToken);\n params.append('pageStart', pageStart.toString());\n }\n \n if (params.toString()) {\n url += '?' + params.toString();\n }\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const data = await response.json();\n console.log('Payment statuses page:', data);\n return data;\n } catch (error) {\n console.error('There was a problem with the fetch operation:', error.message);\n throw error;\n }\n}\n\n// Example usage:\ngetAllPaymentStatusesPaginated('123456789'); // Retrieves all payment statuses across multiple pages\n// OR\ngetPaymentStatusesPage('123456789', 1).then(firstPage => {\n console.log('First page:', firstPage);\n // Use firstPage.meta.pagination.page_token for subsequent requests\n});\n```\n\n**Required Permission:** `get-payment-status`\n\nThis endpoint requires the permission claim `get-payment-status` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "TransactionStatus_GetAccountTransactionStatuses", "parameters": [ { "name": "accountNumber", "in": "path", "required": true, "description": "The account number to retrieve payment statuses for.", "schema": { "type": "string" }, "x-position": 1 }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "maxLength": 100, "minLength": 0, "nullable": true }, "x-position": 2 }, { "name": "pageStart", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 3 }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 4 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfTransactionStatusOf" }, "examples": { "Json": { "value": { "meta": { "pagination": { "pageStart": 1, "pageToken": "202405250011428721.01,10", "totalSize": 3, "pageSize": 10 } }, "data": [ { "type": "Outward Swift Payment MT103 API", "externalReference": "REF123456", "status": "Completed", "remittanceInformation": "Invoice payment #INV-2023-001", "transactionId": "TX-001-2023", "debitAmount": { "currency": "USD", "amount": 1000 }, "valueDate": "2023-05-15", "creditAmount": { "currency": "USD", "amount": null }, "exchangeRate": null }, { "type": "Internal Transfer API", "externalReference": "REF789012", "status": "Pending", "remittanceInformation": "Salary transfer", "transactionId": "TX-002-2023", "debitAmount": { "currency": "EUR", "amount": 2500 }, "valueDate": "2023-05-16", "creditAmount": { "currency": "EUR", "amount": null }, "exchangeRate": null }, { "type": "Inward Swift Payment MT103", "externalReference": "REF345678", "status": "Processing", "remittanceInformation": "Investment return", "transactionId": "TX-003-2023", "debitAmount": { "currency": "GBP", "amount": 5000 }, "valueDate": "2023-05-17", "creditAmount": { "currency": "GBP", "amount": null }, "exchangeRate": null } ] } }, "Csv": { "value": [ "\"meta_pagination_page_start\",\"meta_pagination_page_token\",\"meta_pagination_total_size\",\"meta_pagination_page_size\",\"data_0_type\",\"data_0_external_reference\",\"data_0_status\",\"data_0_remittance_information\",\"data_0_transaction_id\",\"data_0_debit_amount_currency\",\"data_0_debit_amount_amount\",\"data_0_value_date\",\"data_0_credit_amount_currency\",\"data_1_type\",\"data_1_external_reference\",\"data_1_status\",\"data_1_remittance_information\",\"data_1_transaction_id\",\"data_1_debit_amount_currency\",\"data_1_debit_amount_amount\",\"data_1_value_date\",\"data_1_credit_amount_currency\",\"data_2_type\",\"data_2_external_reference\",\"data_2_status\",\"data_2_remittance_information\",\"data_2_transaction_id\",\"data_2_debit_amount_currency\",\"data_2_debit_amount_amount\",\"data_2_value_date\",\"data_2_credit_amount_currency\"", "\"1\",\"202405250011428721.01,10\",\"3\",\"10\",\"Outward Swift Payment MT103 API\",\"REF123456\",\"Completed\",\"Invoice payment #INV-2023-001\",\"TX-001-2023\",\"USD\",\"1000.00\",\"2023-05-15\",\"USD\",\"Internal Transfer API\",\"REF789012\",\"Pending\",\"Salary transfer\",\"TX-002-2023\",\"EUR\",\"2500.00\",\"2023-05-16\",\"EUR\",\"Inward Swift Payment MT103\",\"REF345678\",\"Processing\",\"Investment return\",\"TX-003-2023\",\"GBP\",\"5000.00\",\"2023-05-17\",\"GBP\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-payment-status" ] }, { "Authorization": [] } ] } }, "/v1/payments/{paymentId}/status": { "get": { "tags": [ "Payments" ], "summary": "Get payment status", "description": "Retrieves detailed status information for a specific payment identified by its payment ID (also known as transaction ID). This endpoint provides comprehensive status details including:\n\n- **Type**: The type of payment (e.g., \"Outward Swift Payment MT103 API\")\n- **Status**: Current status of the payment (e.g., \"Pending\", \"Completed\", \"Reversed\")\n- **TransactionId**: Unique payment identifier (or Transaction Id)\n- **ExternalReference**: External reference number for the payment\n- **RemittanceInformation**: Free-text information about the purpose of the payment\n- **DebitAmount**: The amount debited from the account, including currency code\n- **CreditAmount**: The amount credited to the account, including currency code\n- **ValueDate**: The date when the payment was/will be processed\n- **ExchangeRate**: The exchange rate applied to the payment\n\n### Content Negotiation\nClients must use the HTTP Accept header to indicate the desired response format:\n- Set `Accept: application/json` for JSON responses (default)\n- Set `Accept: text/csv` for CSV responses\nIf the Accept header is omitted, `application/json` is assumed.\n\n### Base URL:\nAll API requests use the versioned base URL:\n\n https://api.bcb.bm/v1/payments/{paymentId}/status\n\n### Sample Request in JavaScript:\n\n```javascript\nasync function getPaymentStatus(paymentId) {\n try {\n const response = await fetch(`https://api.bcb.bm/v1/payments/${paymentId}/status`, {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n }\n });\n\n if (!response.ok) {\n const errorData = await response.json();\n throw new Error(`Error: ${errorData.message || 'Unknown error'}`);\n }\n\n const paymentStatus = await response.json();\n console.log('Payment Status Details:');\n console.log('Payment ID:', paymentStatus.transactionId);\n console.log('Type:', paymentStatus.type);\n console.log('Status:', paymentStatus.status);\n console.log('External Reference:', paymentStatus.externalReference);\n console.log('Remittance Information:', paymentStatus.remittanceInformation);\n console.log('Value Date:', paymentStatus.valueDate);\n console.log('Debit Amount:', `${paymentStatus.debitAmount.amount} ${paymentStatus.debitAmount.currency}`);\n \n if (paymentStatus.creditAmount && paymentStatus.creditAmount.amount) {\n console.log('Credit Amount:', `${paymentStatus.creditAmount.amount} ${paymentStatus.creditAmount.currency}`);\n }\n \n // Implement business logic based on payment status\n if (paymentStatus.status === 'Completed') {\n console.log('Payment has been successfully completed.');\n } else if (paymentStatus.status === 'Pending') {\n console.log('Payment is still being processed.');\n } else if (paymentStatus.status === 'Failed') {\n console.log('Payment failed. Please check the details or contact support.');\n }\n } catch (error) {\n console.error('There was a problem retrieving the payment status:', error.message);\n }\n}\n\n// Example usage:\ngetPaymentStatus('PAY-001-2023');\n```\n\n**Required Permission:** `get-payment-status`\n\nThis endpoint requires the permission claim `get-payment-status` to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.", "operationId": "TransactionStatus_GetTransactionStatus", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "The unique identifier of the payment (also known as transactionId) to retrieve status for.", "schema": { "type": "string" }, "x-position": 1 } ], "responses": { "200": { "description": "OK - The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatus" }, "examples": { "Json": { "value": { "type": "Outward Swift Payment MT103 API", "externalReference": "REF123456", "status": "Completed", "remittanceInformation": "Invoice payment #INV-2023-001", "transactionId": "TX-001-2023", "debitAmount": { "currency": "USD", "amount": 1000 }, "valueDate": "2023-05-15", "creditAmount": { "currency": "USD", "amount": null }, "exchangeRate": null } }, "Csv": { "value": [ "\"type\",\"external_reference\",\"status\",\"remittance_information\",\"transaction_id\",\"debit_amount_currency\",\"debit_amount_amount\",\"value_date\",\"credit_amount_currency\"", "\"Outward Swift Payment MT103 API\",\"REF123456\",\"Completed\",\"Invoice payment #INV-2023-001\",\"TX-001-2023\",\"USD\",\"1000.00\",\"2023-05-15\",\"USD\"" ] } } } } }, "400": { "description": "Bad Request - The request was invalid or cannot be served. Check the passed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden – The client is authenticated but does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests - You have exceeded the allowed number of requests in a given timeframe. Please wait for the rate limit to reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error - An unknown error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Authorization": [], "Feature Permissions": [ "get-payment-status" ] }, { "Authorization": [] } ] } } }, "components": { "schemas": { "Account": { "allOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "object", "description": "Bank Account following Open Banking API standards with bank-specific extensions", "additionalProperties": false, "properties": { "openingDate": { "type": "string", "description": "Date when the account was opened", "nullable": true }, "balanceEffectiveDate": { "type": "string", "description": "Date when the balance was last updated", "nullable": true }, "accountRoutings": { "type": "array", "description": "Routing details for the account", "items": { "$ref": "#/components/schemas/BankRouting" } } } } ] }, "BankRouting": { "type": "object", "additionalProperties": false, "required": [ "scheme", "address" ], "properties": { "scheme": { "type": "string", "description": "Scheme value" }, "address": { "type": "string", "description": "Address value" } } }, "AccountSummary": { "type": "object", "description": "Summary view of a bank account for listing purposes", "additionalProperties": false, "required": [ "accountId", "cif", "currency", "accountSubType", "accountNumber", "status", "availableBalance", "owners", "accountAttributes" ], "properties": { "accountId": { "type": "string", "description": "A unique ID of the account, composed of account number and CIF" }, "cif": { "type": "string", "description": "11-digit ID of the account holder" }, "currency": { "type": "string", "description": "Identification of the currency in which the account is held" }, "accountSubType": { "type": "string", "description": "Specifies the sub type of account (product)" }, "accountNumber": { "type": "string", "description": "Account number" }, "status": { "type": "string", "description": "Specifies the status of the account" }, "availableBalance": { "description": "Account balance", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "accountType": { "type": "string", "description": "Specifies the type of account (personal/business)", "nullable": true }, "nickname": { "type": "string", "description": "The nickname of the account, assigned by the account owner", "nullable": true }, "owners": { "type": "array", "description": "Ownership details of an account object", "items": { "$ref": "#/components/schemas/AccountOwner" } }, "accountAttributes": { "type": "array", "description": "Additional details or characteristics associated with an account object", "items": { "$ref": "#/components/schemas/AccountAttribute" } } } }, "CurrencyAmount": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount" ], "properties": { "currency": { "type": "string", "description": "Currency ISO code" }, "amount": { "type": "string", "description": "Amount" } } }, "AccountOwner": { "type": "object", "additionalProperties": false, "required": [ "displayName", "accountHolderType" ], "properties": { "displayName": { "type": "string", "description": "Account owner name" }, "accountHolderType": { "type": "string", "description": "Type of account holder (Primary/Joint)" } } }, "AccountAttribute": { "type": "object", "description": "Attribute value in form of (name, value)\nThis model is used to store additional metadata or characteristics of an account in a name-value pair format.", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Key or identifier of the account attribute." }, "value": { "type": "string", "description": "Actual data associated with the attribute name" } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "ApiResponseOfAccountOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Account" } } } }, "Meta": { "type": "object", "additionalProperties": false, "properties": { "pagination": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Pagination" } ] } } }, "Pagination": { "type": "object", "additionalProperties": false, "required": [ "page_start", "total_size", "page_size" ], "properties": { "page_start": { "type": "integer", "format": "int32" }, "page_token": { "type": "string", "nullable": true }, "total_size": { "type": "integer", "format": "int32" }, "page_size": { "type": "integer", "format": "int32" } } }, "PaymentResponse": { "type": "object", "description": "Represents the response to a SWIFT payment initiation request.", "additionalProperties": false, "required": [ "id", "status", "transactionStatus", "uniqueIdentifier", "details", "linkedActivities" ], "properties": { "id": { "type": "string", "description": "Unique identifier assigned by the bank for the SWIFT transfer.\nThis ID can be used for future reference and tracking of the payment." }, "status": { "type": "string", "description": "The current status of the payment processing.\nPossible values include:\n- success: Payment has been accepted for processing\n- failed: Payment failed" }, "transactionStatus": { "type": "string", "description": "Detailed transaction status indicating the current state of the transfer.\nThis provides more granular status information than the main status field." }, "uniqueIdentifier": { "type": "string", "description": "A unique identifier specific to this instance of the SWIFT transfer.\nThis identifier remains constant throughout the lifecycle of the payment\nand can be used for reconciliation purposes." }, "details": { "description": "Detailed information about the payment transaction including\namounts, accounts, and settlement information.", "allOf": [ { "$ref": "#/components/schemas/PaymentResponseDetails" } ] }, "linkedActivities": { "type": "array", "description": "Collection of related financial activities associated with this payment.\nThis may include charges, forex conversions, or other related transactions.", "items": { "$ref": "#/components/schemas/Activity" } } } }, "PaymentResponseDetails": { "type": "object", "description": "Contains detailed information about a processed SWIFT payment.", "additionalProperties": false, "required": [ "extReference", "instructedAmount", "debtorAccount", "beneficiaryAccount", "creditorAccount", "settlementDetails", "chargeDetails", "beneficiary", "beneficiaryAgent", "intermediaryAgent" ], "properties": { "extReference": { "type": "string", "description": "External reference number assigned by the bank's payment processing system.\nThis reference can be used for tracking and reconciliation purposes." }, "instructedAmount": { "description": "The amount and currency of the payment as instructed by the payment initiator.\nThis represents the original payment amount before any charges or conversions.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "debtorAccount": { "description": "Reference information for the account from which the payment is debited.\nIncludes the account identifier and scheme information.", "allOf": [ { "$ref": "#/components/schemas/AccountReference" } ] }, "beneficiaryAccount": { "description": "Reference information for the beneficiary's account.\nThis may differ from the creditor account in certain scenarios.", "allOf": [ { "$ref": "#/components/schemas/AccountReference" } ] }, "creditorAccount": { "description": "Reference information for the account to be credited with the payment.\nThis represents the immediate recipient account of the funds.", "allOf": [ { "$ref": "#/components/schemas/AccountReference" } ] }, "settlementDetails": { "description": "Details about the settlement of the payment, including credited and\ndebited amounts, value dates, and settlement status.", "allOf": [ { "$ref": "#/components/schemas/SettlementDetails" } ] }, "chargeDetails": { "description": "Information about the charges applied to the payment, including\ncharge type, amounts, and the account to which charges are applied.", "allOf": [ { "$ref": "#/components/schemas/ChargeDetails" } ] }, "remittanceInformation": { "type": "array", "description": "Collection of unstructured information provided with the payment\nto help with reconciliation and payment identification.", "nullable": true, "items": { "$ref": "#/components/schemas/UnstructuredInformation" } }, "beneficiary": { "description": "Detailed information about the ultimate beneficiary of the payment.\nIncludes identification, name, and additional information." }, "beneficiaryAgent": { "description": "Information about the beneficiary's bank or financial institution.\nTypically, includes the BIC/SWIFT code and bank details." }, "intermediaryAgent": { "description": "Details of any intermediary bank involved in the payment chain.\nThis is optional and only present for payments requiring intermediary processing." } } }, "AccountReference": { "type": "object", "description": "Reference to a debtor or creditor account", "additionalProperties": false, "required": [ "identification", "Name" ], "properties": { "schemeName": { "type": "string", "description": "The name of the identification scheme, e.g. \"BBAN\", \"AccountNumber\".", "nullable": true }, "identification": { "type": "string", "description": "The identifier within that scheme (e.g. account number)." }, "Name": { "type": "string", "description": "The name of the account, if available (optional)." } } }, "SettlementDetails": { "type": "object", "description": "Contains details about the settlement of a payment transaction.", "additionalProperties": false, "required": [ "amountCredited", "amountDebited", "valueDate", "recordStatus" ], "properties": { "amountCredited": { "description": "The amount that was credited to the beneficiary account.\nThis may differ from the instructed amount due to currency conversion\nor intermediary bank charges.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "amountDebited": { "description": "The total amount debited from the sender's account.\nThis includes the payment amount plus any applicable charges.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "valueDate": { "type": "string", "description": "The date on which the payment is settled between banks.\nThis is the date when the funds become available to the beneficiary.\nFormat: ISO 8601 date string (YYYY-MM-DD)" }, "recordStatus": { "type": "string", "description": "The current status of the settlement record." } } }, "ChargeDetails": { "type": "object", "description": "Contains information about charges applied to a payment transaction.", "additionalProperties": false, "required": [ "chargesType", "chargeAmount", "chargeAccount", "chargeAnalysis" ], "properties": { "chargesType": { "type": "string", "description": "Specifies how the charges for the payment are allocated.\nPossible values:\n- OUR: All charges are paid by the sender\n- BEN: All charges are paid by the beneficiary\n- SHA: Charges are shared between sender and beneficiary" }, "chargeAmount": { "description": "The total amount of charges applied to the payment.\nIncludes both sending and receiving bank charges.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "chargeAccount": { "description": "Reference information for the account from which charges are collected.\nThis may be different from the main debit account.", "allOf": [ { "$ref": "#/components/schemas/AccountReference" } ] }, "chargeAnalysis": { "description": "Detailed breakdown of how charges are distributed between\nthe sending and receiving parties.", "allOf": [ { "$ref": "#/components/schemas/ChargeAnalysis" } ] } } }, "ChargeAnalysis": { "type": "object", "description": "Provides a detailed breakdown of charges applied to a payment transaction.", "additionalProperties": false, "required": [ "sender", "receiver" ], "properties": { "sender": { "description": "The amount of charges applied by and payable to the sending bank.\nThis may include processing fees, wire transfer fees, or other sending bank charges.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "receiver": { "description": "The amount of charges applied by and payable to the receiving bank.\nThis may include processing fees, incoming wire fees, or other receiving bank charges.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] } } }, "UnstructuredInformation": { "type": "object", "description": "A single line of unstructured text, e.g. per Open Banking’s RemittanceInformation Unstructured field.", "additionalProperties": false, "required": [ "unstructured" ], "properties": { "unstructured": { "type": "string", "description": "The narrative text (e.g. remittance line, beneficiary note, etc.)." } } }, "PartyDetails": { "allOf": [ { "$ref": "#/components/schemas/PartyInfo" }, { "type": "object", "description": "Represents details of a party involved in a payment transaction.\nThis class can be used for various parties such as creditors, agents, or intermediaries.", "additionalProperties": false, "required": [ "identification" ], "properties": { "identification": { "type": "string", "description": "Unique identification of the party, such as a BIC (Bank Identifier Code) for financial institutions\nor an account number for account holders.", "maxLength": 35, "minLength": 1 } } } ] }, "PartyInfo": { "type": "object", "description": "Shared party information used when only name and address lines are needed.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Name by which the party is known and which is usually used to identify the party.", "maxLength": 35, "minLength": 0, "nullable": true }, "additionalInformation": { "type": "array", "description": "Additional information about the party that may be required for processing the payment,\nsuch as address details, country codes, or specific payment instructions.\nMax 3 lines; each line max 35 characters.", "nullable": true, "items": { "type": "string" } } } }, "Activity": { "type": "object", "description": "Refers to any transaction or operation performed within a financial institution that affects accounts or other financial products.", "additionalProperties": false, "required": [ "id", "transactionStatus", "status", "activityDetails" ], "properties": { "id": { "type": "string", "description": "The unique identifier for the activity." }, "transactionStatus": { "type": "string", "description": "The current processing status of the transaction." }, "status": { "type": "string", "description": "The general status of the activity." }, "uniqueIdentifier": { "type": "string", "description": "A unique identifier specific to this instance of the activity.", "nullable": true }, "activityDetails": { "description": "Detailed information about the activity.", "allOf": [ { "$ref": "#/components/schemas/ActivityDetails" } ] } } }, "ActivityDetails": { "type": "object", "description": "Holds details about a specific banking activity.", "additionalProperties": false, "required": [ "arrangementId", "activityId", "productId", "currencyId", "effectiveDate" ], "properties": { "arrangementId": { "type": "string", "description": "Unique identifier for the arrangement associated with this activity." }, "activityId": { "type": "string", "description": "Identifier for the type of activity." }, "productId": { "type": "string", "description": "Product identifier related to the activity." }, "currencyId": { "type": "string", "description": "Currency code for the activity." }, "effectiveDate": { "type": "string", "description": "Date when the activity becomes effective." } } }, "AchLocalPaymentRequest": { "type": "object", "description": "Represents an ACH local bank transfer request in the Open Banking API.\nUsed for domestic same-currency transfers via the local ACH clearing network.", "additionalProperties": false, "required": [ "debtorAccount", "debitCurrency", "instructedAmount", "creditorAccount", "creditorBank", "remittanceInformation" ], "properties": { "instructionIdentification": { "type": "string", "description": "Unique identification as assigned by an instructing party for an instructed party\nto unambiguously identify the instruction. Max 16 characters.", "maxLength": 16, "minLength": 0, "nullable": true }, "debtorAccount": { "description": "Unambiguous identification of the account of the debtor to which a debit entry\nwill be made as a result of the transaction.", "allOf": [ { "$ref": "#/components/schemas/AccountDetails" } ] }, "debitCurrency": { "type": "string", "description": "ISO 4217 currency code for the debit side of the transfer.\nMust be USD or BMD and must match InstructedAmount currency.", "maxLength": 3, "minLength": 3 }, "instructedAmount": { "description": "Amount of money to be moved between the debtor and creditor,\nexpressed in the currency as ordered by the initiating party.\nThe currency must be USD or BMD and must match DebitCurrency.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "creditorAccount": { "description": "Identification and name of the creditor (beneficiary) account.\nIdentification max 17 characters; name max 22 characters." }, "creditorBank": { "description": "Bank reference details used to resolve the creditor bank for the ACH transfer.\nIncludes the bank code and the 3-letter currency code for the destination bank.\nThe currency must be USD or BMD and must match DebitCurrency.", "allOf": [ { "$ref": "#/components/schemas/BankReferenceDetails" } ] }, "remittanceInformation": { "type": "array", "description": "Information supplied to enable the matching/reconciliation of an entry\nwith the items that the payment is intended to settle.\nRequired: 1 to 2 lines; each line max 35 characters.", "items": { "type": "string" } } } }, "AccountDetails": { "type": "object", "description": "Represents basic account identification details used in payment transactions.\nThis class is used for both debtor and creditor accounts.", "additionalProperties": false, "required": [ "identification" ], "properties": { "identification": { "type": "string", "description": "Unique identification of the account, such as an Bank Account Number\nor a local account number.", "maxLength": 36, "minLength": 1 } } }, "BankReferenceDetails": { "type": "object", "description": "Represents the creditor bank reference used to resolve the destination bank\nfor an ACH local payment.", "additionalProperties": false, "required": [ "bankCode", "currency" ], "properties": { "bankCode": { "type": "string", "description": "Bank code used to identify the destination bank in the bank reference lookup.", "maxLength": 100, "minLength": 1 }, "currency": { "type": "string", "description": "Three-letter ISO currency code used together with BankCode\nto resolve the destination bank reference. For ACH local transfers,\nonly USD and BMD are supported.", "maxLength": 3, "minLength": 3 } } }, "ApiClientCredentialsCreateResponse": { "type": "object", "description": "Response model returned when new API client credentials are successfully created or when a client secret is rotated.\nContains the complete credential information needed for API authentication.", "additionalProperties": false, "required": [ "clientId", "clientSecret", "isActive", "messageSigningSecret" ], "properties": { "clientId": { "type": "string", "description": "Unique client identifier (GUID) assigned by the authorization server.\nThis identifier is used in conjunction with the client secret for API authentication." }, "clientSecret": { "type": "string", "description": "Client secret assigned by the authorization server." }, "isActive": { "type": "boolean", "description": "Value indicating whether the client credentials are currently active and can be used for authentication." }, "allowedIps": { "type": "string", "description": "IP address restrictions for the client credentials.\nDefines which IP addresses or IP ranges are allowed to use these credentials for authentication.", "nullable": true }, "messageSigningSecret": { "type": "string", "description": "Base64-encoded 32-byte secret used to sign messages for authentication or integrity verification." } } }, "ApiClientCredentialsCreateRequest": { "type": "object", "description": "Request model for creating new API client credentials", "additionalProperties": false, "properties": { "allowedIps": { "type": "string", "description": "Optional IP address restrictions for the new client credentials.\nIf omitted (null/empty) or set to \"*\", all IP addresses will be allowed.\nOtherwise, specify a comma-separated list of allowed IP addresses and/or CIDR ranges.", "maxLength": 1000, "minLength": 0, "nullable": true, "example": "192.168.1.1,10.0.0.0/24,2001:db8::/32" } } }, "PermissionResponse": { "type": "object", "description": "Response model representing a permission that can be assigned to an API client.", "additionalProperties": false, "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Unique permission key that identifies the specific permission.\nUsed in authorization checks and JWT token claims.", "example": "get-account" }, "description": { "type": "string", "description": "Human-readable description of what this permission allows.\nProvides context for administrators managing client permissions.", "nullable": true, "example": "Allows access to account information endpoints" } } }, "ApiClientKeyMetadataResponse": { "type": "object", "description": "Metadata about a client's configured partner public keys.", "additionalProperties": false, "required": [ "hasPrimaryKey", "hasSecondaryKey", "secondaryKeyVerified" ], "properties": { "hasPrimaryKey": { "type": "boolean", "description": "True when a primary partner public key is configured." }, "hasSecondaryKey": { "type": "boolean", "description": "True when a secondary partner public key is configured (staged for rotation)." }, "primaryKeyFingerprint": { "type": "string", "description": "Short fingerprint of the primary key (first 8 bytes of SHA-256 over canonical key).", "nullable": true }, "secondaryKeyFingerprint": { "type": "string", "description": "Short fingerprint of the secondary key (first 8 bytes of SHA-256 over canonical key).", "nullable": true }, "primaryKeyAlgorithm": { "type": "string", "description": "Algorithm/size description of the primary key (e.g., RSA-2048).", "nullable": true }, "secondaryKeyAlgorithm": { "type": "string", "description": "Algorithm/size description of the secondary key (e.g., RSA-2048).", "nullable": true }, "primaryKeyUpdatedUtc": { "type": "string", "description": "Timestamp when the primary key was last updated.", "format": "date-time", "nullable": true }, "secondaryKeyUpdatedUtc": { "type": "string", "description": "Timestamp when the secondary key was last updated.", "format": "date-time", "nullable": true }, "secondaryKeyVerified": { "type": "boolean", "description": "Indicates whether the secondary key has been verified via challenge." }, "secondaryKeyVerifiedUtc": { "type": "string", "description": "Timestamp when the secondary key was last verified.", "format": "date-time", "nullable": true } } }, "ApiClientUploadRequest": { "type": "object", "description": "Request payload for uploading a partner RSA public key.", "additionalProperties": false, "required": [ "publicKeyPem" ], "properties": { "publicKeyPem": { "type": "string", "minLength": 1 } } }, "ApiClientKeyChallengeResponse": { "type": "object", "description": "Challenge payload for proof-of-possession of the partner secondary key.", "additionalProperties": false, "required": [ "challenge", "expiresUtc" ], "properties": { "challenge": { "type": "string", "description": "Base64-encoded challenge string.\nFormat: {clientId}.{nonce}.{expiry}.{keyFingerprint} (UTF-8 then Base64).\nSign this exact Base64 value with your private key using RSA-PSS + SHA-256." }, "expiresUtc": { "type": "string", "description": "When this challenge expires (UTC). Request a new challenge after this time.", "format": "date-time" } } }, "ApiClientKeyVerifyRequest": { "type": "object", "description": "Request to verify proof-of-possession for the partner secondary key.", "additionalProperties": false, "required": [ "challenge", "signature" ], "properties": { "challenge": { "type": "string", "description": "Base64-encoded challenge issued by the bank (unchanged from the response).", "minLength": 1 }, "signature": { "type": "string", "description": "Base64-encoded RSA-PSS (SHA-256) signature of the Base64 challenge, generated with the partner private key.", "minLength": 1 } } }, "DepositSimulationResponse": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "transactionStatus", "uniqueIdentifier", "details", "linkedActivities" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "transactionStatus": { "type": "string" }, "uniqueIdentifier": { "type": "string" }, "details": { "$ref": "#/components/schemas/DepositSimulationResponseDetails" }, "linkedActivities": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } } } }, "DepositSimulationResponseDetails": { "type": "object", "additionalProperties": false, "required": [ "amountCredited", "amountDebited", "orderingBank", "debitCurrency", "creditAccountNumber", "instructedAmount", "externalAccountNumber", "orderingCustomer", "remittanceInformation" ], "properties": { "amountCredited": { "$ref": "#/components/schemas/CurrencyAmount" }, "amountDebited": { "$ref": "#/components/schemas/CurrencyAmount" }, "orderingBank": { "type": "string" }, "debitCurrency": { "type": "string" }, "creditAccountNumber": { "type": "string" }, "instructedAmount": { "$ref": "#/components/schemas/CurrencyAmount" }, "externalAccountNumber": { "type": "string" }, "orderingCustomer": { "type": "array", "items": { "$ref": "#/components/schemas/UnstructuredInformation" } }, "remittanceInformation": { "type": "array", "items": { "$ref": "#/components/schemas/UnstructuredInformation" } } } }, "DepositSimulationRequest": { "type": "object", "additionalProperties": false, "required": [ "creditAccountNumber", "instructedAmount", "externalAccountNumber", "orderingBank", "orderingCustomer", "remittanceInformation" ], "properties": { "creditAccountNumber": { "type": "string", "maxLength": 36, "minLength": 1 }, "instructedAmount": { "$ref": "#/components/schemas/CurrencyAmount" }, "externalAccountNumber": { "type": "string", "maxLength": 34, "minLength": 1 }, "orderingBank": { "type": "string", "maxLength": 35, "minLength": 1 }, "orderingCustomer": { "type": "array", "items": { "type": "string" } }, "remittanceInformation": { "type": "array", "items": { "type": "string" } } } }, "FxQuote": { "type": "object", "description": "Represents a foreign exchange quote with currency conversion details.", "additionalProperties": false, "required": [ "sourceCurrency", "targetCurrency", "exchangeRate" ], "properties": { "sourceCurrency": { "description": "The source currency and amount.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "targetCurrency": { "description": "The target currency and amount.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "expiryDateTime": { "type": "string", "description": "The expiry date and time of the quote, expressed in **UTC** and formatted per ISO 8601 (yyyy-MM-ddTHH:mm:ssZ).", "nullable": true }, "exchangeRate": { "type": "number", "description": "The exchange rate for the currency conversion.", "format": "decimal" } } }, "InternalTransfer": { "type": "object", "description": "Represents an internal transfer between accounts", "additionalProperties": false, "required": [ "id", "status", "uniqueIdentifier", "internalTransferDetails", "linkedActivities" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the internal transfer" }, "status": { "type": "string", "description": "The current processing status of the transaction, e.g. Completed, Pending, Failed" }, "uniqueIdentifier": { "type": "string", "description": "Unique identifier specific to this instance of the internal transfer" }, "internalTransferDetails": { "description": "Transfer data", "allOf": [ { "$ref": "#/components/schemas/InternalTransferDetails" } ] }, "linkedActivities": { "type": "array", "description": "List of related financial activities\n ", "items": { "$ref": "#/components/schemas/Activity" } } } }, "InternalTransferDetails": { "type": "object", "additionalProperties": false, "required": [ "amountCredited", "creditAmountCurrency", "debitAmount", "amountDebited", "chargeAmount", "valueDate", "debitAccountNumber", "creditAccountNumber" ], "properties": { "amountCredited": { "description": "Amount that has been deposited into or added to a recipient's account\n ", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "creditAmountCurrency": { "type": "string", "description": "Credit amount currency\n " }, "debitAmount": { "description": "Amount that was intended to be transferred or paid, not including any additional fees or charges. It's the raw amount before any processing fees or other costs are added.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "amountDebited": { "description": "The total amount that has been debited from an account. This includes any and all deductions that have been finalized and processed out of an account.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "chargeAmount": { "description": "Sum of money that is charged as a fee or cost associated with a financial transaction", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "valueDate": { "type": "string", "description": "Date on which the transaction is officially settled, meaning the funds are considered to have been transferred legally and are available for use by the recipient\n " }, "chargeAnalysisReceiver": { "type": "string", "description": "Refers to the analysis or breakdown of charges that are applied to the receiver or beneficiary of an internal transfer.", "nullable": true }, "chargeAnalysisSender": { "type": "string", "description": "Refers to the breakdown or details of charges that are applied to the sender of a transaction", "nullable": true }, "debitAccountNumber": { "description": "Unique identifier of a bank account from which funds are being withdrawn or debited", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "creditAccountNumber": { "description": "Unique identifier of a bank account that is set to receive funds", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "chargeAccountNumber": { "description": "Bank account number from which fees associated with a transaction are debited", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] } } }, "TransactionAccount": { "type": "object", "additionalProperties": false, "required": [ "number", "accountRoutings" ], "properties": { "number": { "type": "string", "description": "Account number" }, "accountRoutings": { "type": "array", "description": "Account routing details", "items": { "$ref": "#/components/schemas/BankRouting" } } } }, "InternalTransferRequest": { "allOf": [ { "$ref": "#/components/schemas/TransferRequest" }, { "type": "object", "description": "Represents a request for an internal funds transfer between two accounts.", "additionalProperties": false, "properties": { "endToEndIdentification": { "type": "string", "description": "Reference provided by the client to identify the transaction end-to-end.", "maxLength": 16, "minLength": 0, "nullable": true }, "remittanceInformation": { "type": "string", "description": "Free-text remittance information provided by the client, describing the purpose of the transaction.", "maxLength": 100, "minLength": 0, "nullable": true } } } ] }, "TransferRequest": { "type": "object", "description": "Represents a request for an funds transfer between two accounts.", "additionalProperties": false, "required": [ "debitAmountCurrency", "creditAmountCurrency", "debitAmount", "debitAccountNumber" ], "properties": { "debitAccountNumber": { "type": "string", "description": "The account number from which the money will be taken. Please ensure this account has enough funds before initiating the transfer.", "maxLength": 36, "minLength": 1 }, "debitAmountCurrency": { "type": "string", "description": "Gets or sets the currency code of the debit amount.\nExactly 3 letters (ISO 4217).", "maxLength": 3, "minLength": 3 }, "creditAccountNumber": { "type": "string", "description": "The account number of the recipient's account.", "maxLength": 36, "minLength": 1, "nullable": true }, "creditAmountCurrency": { "type": "string", "description": "The currency code for the credit amount, such as \"USD\", \"EUR\", etc.\nExactly 3 letters (ISO 4217).", "maxLength": 3, "minLength": 3 }, "debitAmount": { "type": "string", "description": "The amount of money to be debited from the sender's account and credited to the recipient's account. Ensure\nthe amount does not exceed the available balance in the debit account.", "maxLength": 18, "minLength": 1 } } }, "PaymentRequest": { "type": "object", "description": "Represents a payment initiation request in the Open Banking API.\nThis is the root object for initiating a payment transaction.", "additionalProperties": false, "required": [ "debtorAccount", "instructedAmount", "creditorAccount", "creditorAgent", "chargesType", "remittanceInformation" ], "properties": { "instructionIdentification": { "type": "string", "description": "Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.", "maxLength": 16, "minLength": 0, "nullable": true }, "debtorAccount": { "description": "Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.", "allOf": [ { "$ref": "#/components/schemas/AccountDetails" } ] }, "instructedAmount": { "description": "Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "debitAmount": { "description": "Optional. FX: debit amount; then only instructedAmount.currency required.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "creditorAccount": { "description": "Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction." }, "creditorAgent": { "description": "Financial institution servicing an account for the creditor." }, "intermediaryAgent": { "description": "Agent between the debtor's agent and the creditor's agent.", "nullable": true }, "chargesType": { "type": "string", "description": "Specifies which party/parties will bear the charges associated with the processing of the payment transaction.\nMax length: 3 characters (e.g., OUR/SHA/BEN).", "maxLength": 3, "minLength": 1 }, "remittanceInformation": { "type": "array", "description": "Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle.\nLimit: up to 4 lines; each line max 35 characters.", "items": { "type": "string" } } } }, "JwksResponse": { "type": "object", "description": "JWKS payload containing the bank signing key.", "additionalProperties": false, "required": [ "keys" ], "properties": { "keys": { "type": "array", "description": "Collection of JSON Web Keys (JWK). Only one key is expected.", "items": { "$ref": "#/components/schemas/JwksKey" } } } }, "JwksKey": { "type": "object", "description": "JSON Web Key (RSA) used for message signing verification.", "additionalProperties": false, "required": [ "kty", "use", "alg", "kid", "n", "e" ], "properties": { "kty": { "type": "string", "description": "Key type. Always \"RSA\" for this endpoint." }, "use": { "type": "string", "description": "Intended use of the key. \"sig\" indicates signature verification." }, "alg": { "type": "string", "description": "Algorithm used with the key. \"PS256\" indicates RSA-PSS with SHA-256." }, "kid": { "type": "string", "description": "Key identifier in the form \"rsa-{version}\"." }, "n": { "type": "string", "description": "Base64Url-encoded RSA modulus." }, "e": { "type": "string", "description": "Base64Url-encoded RSA public exponent (typically \"AQAB\")." } } }, "ApiToken": { "type": "object", "description": "Represents an API token with its value and expiration date.", "additionalProperties": false, "required": [ "token", "expiration" ], "properties": { "token": { "type": "string", "description": "Gets or sets the JWT token." }, "expiration": { "type": "string", "description": "Gets or sets the expiration date and time of the token.", "format": "date-time" } } }, "ApiCredentials": { "type": "object", "description": "Represents the credentials required to generate an API token.", "additionalProperties": false, "required": [ "clientId", "clientSecret" ], "properties": { "clientId": { "type": "string", "description": "The client ID assigned by the authorization server.", "minLength": 1 }, "clientSecret": { "type": "string", "description": "The client secret assigned by the authorization server.", "minLength": 1 } } }, "ApiResponseOfTransactionOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Transaction" } } } }, "Transaction": { "type": "object", "description": "Details related to a financial transaction", "additionalProperties": false, "required": [ "id", "thisAccount", "details", "metadata", "transactionAttributes" ], "properties": { "id": { "type": "string", "description": "A unique ID of the transaction" }, "thisAccount": { "description": "Account associated with the transaction\n ", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "otherAccount": { "description": "Refers to the counter-party's account in a transaction", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "details": { "description": "Provides further transaction details", "allOf": [ { "$ref": "#/components/schemas/TransactionDetails" } ] }, "metadata": { "description": "Provides transaction metadata", "allOf": [ { "$ref": "#/components/schemas/TransactionMetadata" } ] }, "transactionAttributes": { "type": "array", "description": "Additional details or characteristics associated with an transaction object.", "items": { "$ref": "#/components/schemas/TransactionAttribute" } } } }, "TransactionDetails": { "type": "object", "additionalProperties": false, "required": [ "type", "description", "posted", "completed", "value" ], "properties": { "type": { "type": "string", "description": "Balance type, in a coded form." }, "description": { "type": "string", "description": "Transaction description" }, "posted": { "type": "string", "description": "Date and time when a transaction entry is posted to an account on the account servicer's books" }, "completed": { "type": "string", "description": "Date and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry." }, "newBalance": { "description": "New balance after a transaction entry is posted to an account on the account servicer's books", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "value": { "description": "Amount of money in the transaction entry", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] } } }, "TransactionMetadata": { "type": "object", "additionalProperties": false, "properties": { "narrative": { "type": "string", "description": "Provide additional details about the transaction\n ", "nullable": true } } }, "TransactionAttribute": { "type": "object", "description": "Attribute value in form of (name, value)", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "refers to a specific property or characteristic associated with the transaction, such as \"amount\" or \"transaction_type\"." }, "value": { "type": "string", "description": "Corresponds to the actual data or content assigned to that particular property, e.g., \"100.00\" for \"amount\" or \"debit\" for \"transaction_type\"" } } }, "ApiResponseOfVirtualAccountBalanceOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/VirtualAccountBalance" } } } }, "VirtualAccountBalance": { "type": "object", "description": "Represents a virtual account balance response item.", "additionalProperties": false, "required": [ "accountNumber", "balance" ], "properties": { "accountNumber": { "type": "string", "description": "Virtual account number." }, "balance": { "description": "Current balance of the virtual account.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] } } }, "VirtualAccountsGetBalancesRequest": { "type": "object", "description": "Request payload for retrieving balances for the specified virtual account numbers.", "additionalProperties": false, "required": [ "accountNumbers" ], "properties": { "accountNumbers": { "type": "array", "description": "Virtual account numbers to retrieve balances for.", "maxItems": 1000, "minItems": 1, "items": { "type": "string" } } } }, "BatchCreateResponse": { "type": "object", "description": "Response returned after a batch create job is accepted for asynchronous processing.", "additionalProperties": false, "required": [ "jobId", "status", "statusUrl", "resultUrl" ], "properties": { "jobId": { "type": "string", "description": "Unique identifier assigned to the batch job." }, "status": { "type": "string", "description": "Current lifecycle state of the batch job (e.g.Pending, InProgress, Completed, CompletedWithErrors, Cancelled)." }, "statusUrl": { "type": "string", "description": "Absolute URL that can be polled to retrieve up-to-date job status information." }, "resultUrl": { "type": "string", "description": "Absolute URL to obtain the final per-item results once the job has completed." } } }, "VirtualAccountCreateBatchRequest": { "type": "object", "description": "Represents a request to create a batch of virtual accounts.", "additionalProperties": false, "required": [ "items" ], "properties": { "callbackUrl": { "type": "string", "description": "Optional URL to receive asynchronous notifications about the async job processing status. ", "nullable": true }, "customHeaders": { "type": "object", "description": "Optional custom headers to include in the account creation request. It will be sent back in callbacks.\nMax 10 headers, each key max 50 chars, each value max 500 chars", "nullable": true, "additionalProperties": { "type": "string" } }, "items": { "type": "array", "description": "Payload containing the details of virtual accounts to be created in batch.", "items": { "$ref": "#/components/schemas/VirtualAccountCreateRequest" } } } }, "VirtualAccountCreateRequest": { "type": "object", "description": "Request model for creating a new virtual account following Open Banking standards.\nVirtual accounts are subaccounts associated with a corporate client that can be used \nfor specific business purposes while maintaining separation of funds.", "additionalProperties": false, "required": [ "currency", "unallocated" ], "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code for the virtual account (e.g., USD, EUR, BMD).\nMust be a supported currency by the bank.", "maxLength": 3, "minLength": 3 }, "accountHolderName": { "type": "string", "description": "Human-readable nickname or label for the virtual account.\nUsed for display purposes and client identification.\nOptional when Unallocated is true; otherwise required.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 35, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "accountName": { "type": "string", "description": "Official account name as it will appear on statements and official documents.\nThis is the formal name of the virtual account.\nOptional when Unallocated is true; otherwise required.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 70, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "clientReference": { "type": "string", "description": "Client-provided reference identifier for tracking and identification purposes.\nThis reference should be unique within the client's system for easier reconciliation.", "maxLength": 35, "minLength": 0, "nullable": true }, "dob": { "type": "string", "description": "Date of birth of the account holder, if applicable.", "format": "date-time", "nullable": true }, "nativeLanguageName": { "type": "string", "description": "Native name of the account holder's language, if applicable.", "maxLength": 255, "minLength": 0, "nullable": true }, "unallocated": { "type": "boolean", "description": "Indicates whether the virtual account is pre-created for future allocation.\nWhen set to true, the account is created in \"for allocation\" mode with placeholder\nvalues (\"UNALLOCATED\") for AccountHolderName and AccountName,\nwhich become optional. This allows clients to bulk-create virtual accounts and later\nperform a one-time update to assign them to real end-customers." } } }, "VirtualAccountDetails": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccount" }, { "type": "object", "description": "Virtual Account following Open Banking API standards with bank-specific extensions\nRepresents a sub-account or virtual account associated with a corporate client", "additionalProperties": false, "properties": { "effectiveDate": { "type": "string", "description": "Date when the virtual account becomes effective (YYYY-MM-DD format)", "nullable": true }, "createdAt": { "type": "string", "description": "Date when the virtual account was created (ISO 8601 format). Bermuda Time Zone.", "nullable": true }, "parentAccount": { "description": "Parent account summary", "allOf": [ { "$ref": "#/components/schemas/AccountSummary" } ] }, "settlementAccount": { "description": "Settlement account summary", "allOf": [ { "$ref": "#/components/schemas/AccountSummary" } ] } } } ] }, "VirtualAccount": { "type": "object", "description": "Virtual Account following Open Banking API standards with bank-specific extensions\nRepresents a sub-account or virtual account associated with a corporate client", "additionalProperties": false, "required": [ "virtualAccountNumber", "bicCode", "bicCodeFx", "accountHolderName", "accountName", "currency", "balance", "category", "unallocated" ], "properties": { "virtualAccountNumber": { "type": "string", "description": "Account number for the virtual account" }, "bicCode": { "type": "string", "description": "BIC (Bank Identifier Code)" }, "bicCodeFx": { "type": "string", "description": "BIC (Bank Identifier Code) used for FX transactions" }, "accountHolderName": { "type": "string", "description": "Owner for the virtual account" }, "accountName": { "type": "string", "description": "Virtual account name as it appears on statements and official documents" }, "currency": { "type": "string", "description": "ISO 4217 currency code for the virtual account" }, "balance": { "description": "Current balance of the virtual account", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "category": { "type": "string", "description": "Category or type of the (virtual) account, if applicable" }, "clientReference": { "type": "string", "description": "Client-provided reference identifier for the virtual account", "nullable": true }, "dob": { "type": "string", "description": "Date of birth of the account holder, if applicable.", "format": "date-time", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "taxIdentificationNumber": { "type": "string", "nullable": true }, "countryOfResidence": { "type": "string", "nullable": true }, "nativeLanguageName": { "type": "string", "description": "Native name of the account holder's language, if applicable.", "nullable": true }, "unallocated": { "type": "boolean", "description": "Indicates whether the virtual account is pre-created for future allocation." } } }, "VirtualAccountUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/PatchDto" }, { "type": "object", "description": "Request model for creating a new virtual account following Open Banking standards.\nVirtual accounts are sub-accounts associated with a corporate client that can be used \nfor specific business purposes while maintaining separation of funds.", "additionalProperties": false, "properties": { "accountHolderName": { "type": "string", "description": "Virtual account name\nUsed for display purposes and client identification.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 35, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "accountName": { "type": "string", "description": "Official account title as it will appear on statements and official documents.\nThis is the formal name of the virtual account.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 70, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "clientReference": { "type": "string", "description": "Client-provided reference identifier for tracking and identification purposes.\nThis reference should be unique within the client's system for easier reconciliation.", "maxLength": 35, "minLength": 0, "nullable": true }, "dob": { "type": "string", "description": "Date of birth of the account holder, if applicable.", "format": "date-time", "nullable": true }, "nativeLanguageName": { "type": "string", "description": "Native name of the account holder's language, if applicable.", "maxLength": 255, "minLength": 0, "nullable": true } } } ] }, "PatchDto": { "type": "object", "x-abstract": true, "additionalProperties": false }, "ApiResponseOfVirtualAccountOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "VirtualAccountCreateBatchRequestV2": { "type": "object", "description": "Represents a request to create a batch of virtual accounts using the V2 schema.", "additionalProperties": false, "required": [ "items" ], "properties": { "callbackUrl": { "type": "string", "nullable": true }, "customHeaders": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualAccountCreateRequestV2" } } } }, "VirtualAccountCreateRequestV2": { "type": "object", "description": "Version 2 request model for creating a new virtual account.\nAdds customer profile fields required for allocated accounts.", "additionalProperties": false, "required": [ "currency", "unallocated" ], "properties": { "currency": { "type": "string", "maxLength": 3, "minLength": 3 }, "accountHolderName": { "type": "string", "description": "Human-readable nickname or label for the virtual account.\nOptional when Unallocated is true; otherwise required.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 35, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "accountName": { "type": "string", "description": "Official account name as it will appear on statements and official documents.\nOptional when Unallocated is true; otherwise required.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 70, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "clientReference": { "type": "string", "maxLength": 35, "minLength": 0, "nullable": true }, "dob": { "type": "string", "description": "Date of birth of the account holder.\nRequired when Unallocated is false.", "format": "date-time", "nullable": true }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-2 nationality of the account holder.\nRequired when Unallocated is false.", "nullable": true }, "taxIdentificationNumber": { "type": "string", "maxLength": 255, "minLength": 0, "nullable": true }, "countryOfResidence": { "type": "string", "nullable": true }, "nativeLanguageName": { "type": "string", "maxLength": 255, "minLength": 0, "nullable": true }, "unallocated": { "type": "boolean" } } }, "VirtualAccountUpdateRequestV2": { "allOf": [ { "$ref": "#/components/schemas/PatchDto" }, { "type": "object", "description": "Version 2 request model for updating a virtual account.\nIf any allocation or customer profile field is supplied, the allocation fields must be provided together.", "additionalProperties": false, "properties": { "accountHolderName": { "type": "string", "description": "Human-readable nickname or label for the virtual account.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 35, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "accountName": { "type": "string", "description": "Official account name as it will appear on statements and official documents.\nAllowed characters: A-Z, a-z, 0-9, space, and ! \" # $ % & ' ( ) * + , - . / [ \\ ].\nCommon characters such as _ @ : ; ? { } are not allowed.", "maxLength": 70, "minLength": 0, "pattern": "\\A[A-Za-z0-9 !\"#$%&'()*+,\\-./\\[\\\\\\]]+\\z", "nullable": true }, "clientReference": { "type": "string", "maxLength": 35, "minLength": 0, "nullable": true }, "dob": { "type": "string", "description": "Date of birth of the account holder.\nRequired together with account holder name, account name, and nationality when any allocation or customer profile field is supplied.", "format": "date-time", "nullable": true }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-2 nationality of the account holder.\nRequired together with account holder name, account name, and date of birth when any allocation or customer profile field is supplied.", "nullable": true }, "taxIdentificationNumber": { "type": "string", "maxLength": 255, "minLength": 0, "nullable": true }, "countryOfResidence": { "type": "string", "nullable": true }, "nativeLanguageName": { "type": "string", "maxLength": 255, "minLength": 0, "nullable": true } } } ] }, "ApiResponseOfVirtualAccountTransactionDetailOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/VirtualAccountTransactionDetail" } } } }, "VirtualAccountTransactionDetail": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountTransaction" }, { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "debitAccountNumber": { "description": "Unique identifier of a bank account from which funds are being withdrawn or debited", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "creditAccountNumber": { "description": "Unique identifier of a bank account that is set to receive funds", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "status": { "type": "string", "description": "Transaction Status", "minLength": 1 }, "counterpartyReference": { "type": "string", "description": "Reference supplied by the counterparty (e.g. their own transaction or message identifier). Returned as provided by the bank.", "nullable": true } } } ] }, "VirtualAccountTransaction": { "type": "object", "additionalProperties": false, "required": [ "id", "bookingDate", "valueDate", "value" ], "properties": { "id": { "type": "string", "description": "A unique identifier of the virtual account transaction." }, "description": { "type": "string", "description": "Human-readable description of the transaction.", "nullable": true }, "bookingDate": { "type": "string", "description": "The booking date of the transaction in YYYY-MM-DD format." }, "valueDate": { "type": "string", "description": "The value date of the transaction in YYYY-MM-DD format." }, "value": { "description": "Transaction amount with currency. Positive values indicate credits; negative values indicate debits.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "proprietaryBankTransactionCode": { "type": "string", "description": "Bank-specific transaction-type code (e.g. PARENT.TO.SUB, SUB.TO.PARENT).", "nullable": true } } }, "ApiResponseOfString": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "string", "nullable": true } } }, "VirtualAccountTransactionReversal": { "type": "object", "description": "Represents a reversal of a previously posted virtual account transaction.\nAligns with the Virtual Accounts transaction framework and mirrors T24 reversal\nresponse semantics while conforming to Open Banking model patterns.", "additionalProperties": false, "required": [ "transactionId", "transactionStatus", "status", "uniqueIdentifier", "value" ], "properties": { "transactionId": { "type": "string", "description": "Unique identifier of the original (now reversed) transaction (e.g., FT1234567)." }, "transactionStatus": { "type": "string", "description": "Reversal processing status reported by the core system (e.g., Reversed).\nTypically reflects the system's internal status code for the reversal lifecycle." }, "status": { "type": "string", "description": "High-level execution status of the reversal request (e.g., success, failed)." }, "uniqueIdentifier": { "type": "string", "description": "Unique correlation / tracking identifier supplied by or derived from the core system (e.g., message or processing reference)." }, "value": { "description": "Transaction amount with currency", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] } } }, "VirtualAccountTransferOfVirtualAccountTransferDetails": { "type": "object", "description": "Represents an transfer between virtual accounts", "additionalProperties": false, "required": [ "id", "status", "uniqueIdentifier", "linkedActivities" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the transfer" }, "status": { "type": "string", "description": "The current processing status of the transaction, e.g. Completed, Pending, Failed" }, "uniqueIdentifier": { "type": "string", "description": "Unique identifier specific to this instance of the transfer" }, "details": { "description": "Transfer data", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/VirtualAccountTransferDetails" } ] }, "linkedActivities": { "type": "array", "description": "List of related financial activities\n ", "items": { "$ref": "#/components/schemas/Activity" } } } }, "VirtualAccountTransferDetails": { "type": "object", "additionalProperties": false, "required": [ "debitAmount", "valueDate", "creditAmountCurrency", "debitAccountNumber", "creditAccountNumber" ], "properties": { "debitAmount": { "description": "Amount that was intended to be transferred or paid, not including any additional fees or charges. It's the raw amount before any processing fees or other costs are added.", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "valueDate": { "type": "string", "description": "Date on which the transaction is officially settled, meaning the funds are considered to have been transferred legally and are available for use by the recipient\n " }, "childTransactionId": { "type": "string", "description": "Child transaction ID", "nullable": true }, "creditAmountCurrency": { "type": "string", "description": "Credit amount currency\n " }, "debitAccountNumber": { "description": "Unique identifier of a bank account from which funds are being withdrawn or debited", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "creditAccountNumber": { "description": "Unique identifier of a bank account that is set to receive funds", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] } } }, "VirtualAccountCreditRequest": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountTransferRequestBase" }, { "type": "object", "description": "Represents a request to credit a virtual account.\nThe virtual account number (creditAccountNumber) is specified in the URL route.", "additionalProperties": false, "required": [ "debitAccountNumber" ], "properties": { "debitAccountNumber": { "type": "string", "description": "The account number from which the money will be taken (source/parent account).\nPlease ensure this account has enough funds before initiating the transfer.", "maxLength": 36, "minLength": 1 } } } ] }, "VirtualAccountTransferRequestBase": { "type": "object", "description": "Base class for virtual account transfer requests containing common fields.", "x-abstract": true, "additionalProperties": false, "required": [ "debitAmountCurrency", "creditAmountCurrency", "debitAmount" ], "properties": { "debitAmountCurrency": { "type": "string", "description": "Gets or sets the currency code of the debit amount.\nExactly 3 letters (ISO 4217).", "maxLength": 3, "minLength": 3 }, "creditAmountCurrency": { "type": "string", "description": "The currency code for the credit amount, such as \"USD\", \"EUR\", etc.\nExactly 3 letters (ISO 4217).", "maxLength": 3, "minLength": 3 }, "debitAmount": { "type": "string", "description": "The amount of money to be transferred.\nEnsure the amount does not exceed the available balance in the debit account.", "maxLength": 18, "minLength": 1 } } }, "VirtualAccountDebitRequest": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountTransferRequestBase" }, { "type": "object", "description": "Represents a request to debit a virtual account.\nThe virtual account number (debitAccountNumber) is specified in the URL route.", "additionalProperties": false, "required": [ "creditAccountNumber" ], "properties": { "creditAccountNumber": { "type": "string", "description": "The account number of the recipient's account (destination/parent/settlement account).", "maxLength": 36, "minLength": 1 } } } ] }, "VirtualAccountTransferOfVirtualAccountSettlementTransfer": { "type": "object", "description": "Represents an transfer between virtual accounts", "additionalProperties": false, "required": [ "id", "status", "uniqueIdentifier", "linkedActivities" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the transfer" }, "status": { "type": "string", "description": "The current processing status of the transaction, e.g. Completed, Pending, Failed" }, "uniqueIdentifier": { "type": "string", "description": "Unique identifier specific to this instance of the transfer" }, "details": { "description": "Transfer data", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/VirtualAccountSettlementTransfer" } ] }, "linkedActivities": { "type": "array", "description": "List of related financial activities\n ", "items": { "$ref": "#/components/schemas/Activity" } } } }, "VirtualAccountSettlementTransfer": { "type": "object", "additionalProperties": false, "required": [ "creditAmount", "debitAmountCurrency", "debitAccountNumber", "creditAccountNumber", "valueDate" ], "properties": { "creditAmount": { "description": "Amount moved from settlement account to the account", "allOf": [ { "$ref": "#/components/schemas/ProvisionalCurrencyAmount" } ] }, "debitAmountCurrency": { "type": "string", "description": "Debit amount currency\n " }, "debitAccountNumber": { "description": "Unique identifier of a bank account from which funds are being withdrawn or debited", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "creditAccountNumber": { "description": "Unique identifier of a bank account that is set to receive funds", "allOf": [ { "$ref": "#/components/schemas/TransactionAccount" } ] }, "valueDate": { "type": "string", "description": "Date on which the transaction\n " } } }, "ProvisionalCurrencyAmount": { "type": "object", "description": "Currency amount where the amount may be null (e.g. cross-currency FX response before bank assigns rate).", "additionalProperties": false, "required": [ "currency" ], "properties": { "currency": { "type": "string", "description": "Currency ISO code" }, "amount": { "type": "string", "description": "Amount. May be null when not yet known (e.g. cross-currency FX response before bank assigns rate).", "nullable": true } } }, "VirtualAccountSettlementTransferRequestInternal": { "type": "object", "description": "Internal request model for virtual account settlement transfers.", "additionalProperties": false, "required": [ "debitCurrency", "creditAmount", "creditAccountNumber" ], "properties": { "debitCurrency": { "type": "string", "description": "The currency code for the debit amount (e.g., \"USD\", \"EUR\").\nExactly 3 letters (ISO 4217).", "maxLength": 3, "minLength": 3 }, "creditAmount": { "description": "The amount to be credited to the destination account (amount and currency).", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "creditAccountNumber": { "type": "string", "description": "The account number to which funds will be credited (destination account).\nMax length: 36 characters.", "maxLength": 36, "minLength": 1 } } }, "VirtualAccountSettlementTransferRequestExternal": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountSettlementTransferRequestInternal" }, { "type": "object", "description": "External request model for virtual account settlement transfers.", "additionalProperties": false, "required": [ "debtor", "debtorAgent", "creditorAccount", "chargesType", "creditorAgent" ], "properties": { "debtor": { "type": "string", "description": "The ordering customer information or reference\nMax length: 35 characters.", "maxLength": 35, "minLength": 1 }, "debtorAgent": { "type": "string", "description": "The ordering customer agent (e.g., bank identifier code).\nMax length: 35 characters.", "maxLength": 35, "minLength": 1 }, "creditorAccount": { "description": "Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction." }, "chargesType": { "type": "string", "description": "Specifies which party/parties will bear the charges associated with the processing of the transaction, e.g. 'OUR'\nMax length: 3 characters.", "maxLength": 3, "minLength": 1 }, "creditorAgent": { "description": "Financial institution servicing an account for the creditor." }, "intermediaryAgent": { "description": "Agent between the debtor's agent and the creditor's agent.", "nullable": true }, "remittanceInformation": { "type": "array", "description": "Remittance Information. Limit: up to 4 lines; each line max 35 characters.", "items": { "type": "string" } }, "debitAmount": { "description": "Optional. FX: debit amount; then only creditAmount.currency required.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] } } } ] }, "VirtualAccountTransferOfVirtualAccountWithdrawalTransfer": { "type": "object", "description": "Represents an transfer between virtual accounts", "additionalProperties": false, "required": [ "id", "status", "uniqueIdentifier", "linkedActivities" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the transfer" }, "status": { "type": "string", "description": "The current processing status of the transaction, e.g. Completed, Pending, Failed" }, "uniqueIdentifier": { "type": "string", "description": "Unique identifier specific to this instance of the transfer" }, "details": { "description": "Transfer data", "nullable": true }, "linkedActivities": { "type": "array", "description": "List of related financial activities\n ", "items": { "$ref": "#/components/schemas/Activity" } } } }, "VirtualAccountWithdrawalTransfer": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountSettlementTransfer" }, { "type": "object", "additionalProperties": false } ] }, "VirtualAccountWithDrawalTransferRequestInternal": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountSettlementTransferRequestInternal" }, { "type": "object", "additionalProperties": false } ] }, "VirtualAccountWithDrawalTransferRequestExternal": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountWithDrawalTransferRequestInternal" }, { "type": "object", "additionalProperties": false, "required": [ "debtor", "creditorAccount", "chargesType", "creditorAgent" ], "properties": { "debtor": { "type": "string", "description": "The ordering customer information or reference\nMax length: 35 characters.", "maxLength": 35, "minLength": 1 }, "debtorAgent": { "type": "string", "description": "The ordering customer agent (e.g., bank identifier code).\nMax length: 35 characters.", "maxLength": 35, "minLength": 1, "nullable": true }, "creditorAccount": { "description": "Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction." }, "chargesType": { "type": "string", "description": "Specifies which party/parties will bear the charges associated with the processing of the transaction, e.g. 'OUR'\nMax length: 3 characters.", "maxLength": 3, "minLength": 1 }, "creditorAgent": { "description": "Financial institution servicing an account for the creditor." }, "intermediaryAgent": { "description": "Agent between the debtor's agent and the creditor's agent.", "nullable": true }, "remittanceInformation": { "type": "array", "description": "Remittance Information. Limit: up to 4 lines; each line max 35 characters.", "items": { "type": "string" } }, "debitAmount": { "description": "Optional. FX: debit amount; then only creditAmount.currency required.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] } } } ] }, "VirtualAccountWithDrawalTransferRequestExternalV2": { "allOf": [ { "$ref": "#/components/schemas/VirtualAccountWithDrawalTransferRequestExternal" }, { "type": "object", "description": "V2 external withdrawal request with structured debtor information.", "additionalProperties": false, "properties": { "debtor": { "description": "Structured ordering customer information for v2.\nShadows the v1 string debtor property on the base type.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PartyInfo" } ] } } } ] }, "NotificationSubscription": { "type": "object", "additionalProperties": false, "required": [ "topic", "webhookUrl", "isActive", "createdUtc" ], "properties": { "subscriptionId": { "type": "string", "format": "guid", "nullable": true }, "topic": { "$ref": "#/components/schemas/NotificationsTopicType" }, "webhookUrl": { "type": "string", "format": "uri", "maxLength": 500, "minLength": 1 }, "isActive": { "type": "boolean" }, "createdUtc": { "type": "string", "format": "date-time" }, "updatedUtc": { "type": "string", "format": "date-time", "nullable": true }, "customHeaders": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } } }, "NotificationsTopicType": { "type": "string", "description": "", "x-enumNames": [ "Deposits" ], "enum": [ "Deposits" ] }, "SubscribeRequest": { "type": "object", "additionalProperties": false, "required": [ "callbackUrl", "topic" ], "properties": { "callbackUrl": { "type": "string", "maxLength": 500, "minLength": 1 }, "customHeaders": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "topic": { "$ref": "#/components/schemas/NotificationsTopicType" } } }, "ApiResponseOfNotificationSubscriptionOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/NotificationSubscription" } } } }, "ApiResponseOfBatchStatusOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/BatchStatus" } } } }, "BatchStatus": { "type": "object", "description": "Batch job status information", "additionalProperties": false, "required": [ "eventType", "jobId", "jobStatus", "summary" ], "properties": { "eventType": { "type": "string", "description": "The type of event (e.g., \"job.completed\", \"job.failed\")" }, "jobId": { "type": "string", "description": "Unique identifier for the batch job" }, "jobStatus": { "type": "string", "description": "Job status (e.g., \"Pending\", \"InProgress\", \"Completed\", \"Failed\")" }, "summary": { "description": "Summary of job execution statistics", "allOf": [ { "$ref": "#/components/schemas/BatchJobSummary" } ] } } }, "BatchJobSummary": { "type": "object", "description": "Summary statistics for a batch job", "additionalProperties": false, "required": [ "total", "completed", "failed" ], "properties": { "total": { "type": "integer", "description": "Total number of items in the batch", "format": "int32" }, "completed": { "type": "integer", "description": "Number of items successfully completed", "format": "int32" }, "failed": { "type": "integer", "description": "Number of items that failed", "format": "int32" } } }, "ApiResponseOfBatchJobResultOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/BatchJobResult" } } } }, "BatchJobResult": { "type": "object", "description": "Represents the persisted processing state and outcome of a single item within a submitted batch job.", "additionalProperties": false, "required": [ "id", "jobId", "externalItemId", "payloadJson", "status", "attempt", "httpStatus", "createdUtc" ], "properties": { "id": { "type": "string", "description": "Internal identifier for this item result." }, "jobId": { "type": "string", "description": "Identifier of the parent batch job that this item belongs to." }, "externalItemId": { "type": "string", "description": "Client supplied item identifier (mirrors the batch Items[i].Id provided at submission time)." }, "payloadJson": { "type": "string", "description": "Original request payload serialized as JSON for auditing and replay diagnostics." }, "status": { "type": "string", "description": "Current processing status of the item (e.g. Pending, InProgress, Completed, Failed, Cancelled)." }, "attempt": { "type": "integer", "description": "Number of processing attempts made for this item (incremented on retry).", "format": "int32" }, "httpStatus": { "type": "integer", "description": "HTTP status code returned by the target endpoint for the most recent attempt.", "format": "int32" }, "error": { "type": "string", "description": "Error message or diagnostic detail if processing failed; otherwise null.", "nullable": true }, "resultJson": { "type": "string", "description": "Serialized JSON response body produced by the target endpoint on success (or last attempt); may be null.", "nullable": true }, "createdUtc": { "type": "string", "description": "UTC timestamp when the item result record was created (queued).", "format": "date-time" }, "finishedUtc": { "type": "string", "description": "UTC timestamp when the item reached a terminal state (Completed, Failed, Cancelled); otherwise null.", "format": "date-time", "nullable": true } } }, "BatchJobItemStatus": { "type": "string", "description": "", "x-enumNames": [ "Pending", "InProgress", "Completed", "Failed", "Cancelled" ], "enum": [ "Pending", "InProgress", "Completed", "Failed", "Cancelled" ] }, "SystemTimeResponse": { "type": "object", "description": "Response model for system time endpoint", "additionalProperties": false, "required": [ "timestamp", "timeZone" ], "properties": { "timestamp": { "type": "string", "description": "Current server timestamp in ISO-8601 format (e.g., 2025-01-07T14:30:15-04:00)" }, "timeZone": { "type": "string", "description": "Current server time zone in IANA format (e.g., \"Atlantic Daylight Time\")" } } }, "ApiResponseOfTransactionStatusOf": { "type": "object", "additionalProperties": false, "properties": { "meta": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Meta" } ] }, "data": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/TransactionStatus" } } } }, "TransactionStatus": { "type": "object", "description": "Represents the status of a transaction in the Open Banking API.", "additionalProperties": false, "required": [ "type", "status", "transactionId", "debitAmount", "valueDate", "creditAmount" ], "properties": { "type": { "type": "string", "description": "The type of transaction (e.g., \"Outward Swift Payment MT103 API\")" }, "externalReference": { "type": "string", "description": "External reference number for the transaction", "nullable": true }, "status": { "type": "string", "description": "Current status of the transaction (e.g., \"Pending\", \"Completed\", \"Reversed\")" }, "remittanceInformation": { "type": "string", "description": "Free-text remittance information provided by the client, describing the purpose of the transaction.", "nullable": true }, "transactionId": { "type": "string", "description": "Unique transaction number" }, "debitAmount": { "description": "The amount debited from the account", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "valueDate": { "type": "string", "description": "The date when the transaction will be processed" }, "creditAmount": { "description": "The amount credited from the account", "allOf": [ { "$ref": "#/components/schemas/CurrencyAmount" } ] }, "exchangeRate": { "type": "number", "description": "Exchange rate applied to the transaction", "format": "decimal", "nullable": true } } } }, "securitySchemes": { "Authorization": { "type": "apiKey", "description": "JWT Bearer token. Example: Bearer {token}", "name": "Authorization", "in": "header" }, "Feature Permissions": { "type": "http", "description": "Feature-based permissions are claims contained in the JWT token. The token must include the specified permission claim to access the endpoint. These permissions are validated during token validation.", "in": "header", "scheme": "bearer", "bearerFormat": "jwt" } } } }