API Documentation
Bancorix exposes two independent API surfaces. This guide covers authentication, request structure, key resources, and links to the interactive Swagger specifications.
Overview
Bancorix exposes two independent REST APIs built on a dual-surface architecture (ADR-028). This separation ensures that back-office improvements never break partner integrations, and external API evolution does not affect console operations.
Core API
Port 5000 • External integrations
For partner systems, third-party integrations, and programmatic access to platform operations — payments, accounts, documents, GL data, and customer management.
Open Swagger (Dev) →Console API (BFF)
Port 5001 • Back-office operations
Backend-for-Frontend for the operations console. Provides schema-driven form metadata, console-specific projections, bulk operations, and dashboard data unavailable on the Core API.
Open Swagger (Dev) →Authentication
Both APIs use JWT Bearer authentication. Obtain a token from the login endpoint, then include it in the Authorization header on all requests.
POST /api/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "your-password",
"tenantId": "your-tenant-id"
}Authorization: Bearer <access_token>POST /api/auth/refresh to obtain a new access token before expiry.
Base URLs
| Environment | Core API | Console API |
|---|---|---|
| Development | https://api-dev.bancorix.com | https://console-dev.bancorix.com |
| UAT | https://api-uat.bancorix.com | https://console-uat.bancorix.com |
| Production | https://api.bancorix.com | https://console.bancorix.com |
Core API — Key Resources
POST /api/auth/loginPOST /api/auth/refreshPOST /api/auth/logoutGET /api/auth/me GET /api/documentsPOST /api/documentsGET /api/documents/{id}GET /api/documents/search GET /api/accountsPOST /api/accountsGET /api/accounts/{id}/balanceGET /api/accounts/{id}/bankdetailsGET /api/accounts/{id}/statement GET /api/customersPOST /api/customersGET /api/customers/{id} GET /api/transactionsPOST /api/transactionsPOST /api/transactions/{id}/postPOST /api/transactions/{id}/reverse GET /api/workflowsPOST /api/workflows/instances/startPOST /api/workflows/instances/{id}/execute GET /api/balances/summaryGET /api/reference/currenciesGET /api/reference/transaction-types Full endpoint reference with request/response schemas is available in the interactive Swagger UI.
Console API (BFF) — Controller Groups
Request Structure
All requests must include the following headers:
Authorization: Bearer <token>
Content-Type: application/json
X-Tenant-Id: <tenant-id>Multi-tenant context is resolved from the JWT claims. The X-Tenant-Id header is required only when a user operates across multiple tenants.
Error Handling
Errors follow RFC 7807 Problem Details format:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
"type": "https://bancorix.com/errors/validation",
"title": "Validation failed",
"status": 422,
"errors": {
"amount": ["Amount must be greater than zero"]
}
}| HTTP Status | Meaning |
|---|---|
| 400 | Bad request — malformed JSON or missing required fields |
| 401 | Unauthorized — missing or expired token |
| 403 | Forbidden — authenticated but insufficient permissions |
| 404 | Not found — resource does not exist in this tenant context |
| 409 | Conflict — state machine violation or concurrent modification |
| 422 | Validation error — business rule or schema violation |
| 500 | Internal server error — contact support |
Pagination
List endpoints support cursor-based pagination via query parameters:
GET /api/documents?page=1&pageSize=50&sortBy=createdAt&sortDir=descResponse includes totalCount, page, pageSize, and hasNextPage in the response envelope.
Events & Webhooks
Inbound provider events — payment status changes, incoming payments, KYC decisions, delivery receipts — are ingested through the dedicated integration engine with signature verification, deduplication, and dead-letter handling, then reflected on the corresponding documents and workflow states available via the Core API.
Postman Collection
A complete Postman collection with pre-configured environments (Dev, UAT, Production) is available on request. The collection includes authentication flows, common document operations, GL queries, and fee simulation examples.
Request Postman CollectionSandbox Access
We can provision a sandbox tenant with pre-loaded reference data, sample documents, and an operational workflow for hands-on technical evaluation. The sandbox is fully isolated and includes:
- Pre-seeded Chart of Accounts (393 accounts)
- Sample customer records (Individual and Corporate)
- Example payment documents in various workflow states
- Fee schedules across Standard, Premium, and Corporate pricing plans
- Admin credentials and role-based test users