API Documentation

Bancorix exposes two independent API surfaces. This guide covers authentication, request structure, key resources, and links to the interactive Swagger specifications.

Core API Swagger (Dev) → Console API Swagger (Dev) →

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>

Token lifetimes: Access tokens expire after 15 minutes. Refresh tokens are valid for 7 days. Use 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

Authentication

POST /api/auth/loginPOST /api/auth/refreshPOST /api/auth/logout

Documents

GET /api/documentsPOST /api/documentsGET /api/documents/{id}POST /api/documents/{id}/transition

Accounts

GET /api/accountsPOST /api/accountsGET /api/accounts/{id}/balance

Customers

GET /api/customersPOST /api/customersGET /api/customers/{id}

General Ledger

GET /api/gl/entriesGET /api/gl/balancesGET /api/gl/trial-balance

Fees

POST /api/fees/simulateGET /api/fees/pricing-plans

Full endpoint reference with request/response schemas is available in the interactive Swagger UI.

Console API (BFF) — Controller Groups

Document Types

Schema definitions, field metadata, allowed transitions per document type

Console Documents

Document list with console-specific projections, bulk operations, task assignment

Reference Data

Currencies, payment systems, countries, document type enumerations

GL Console

Chart of accounts, posting rules, GL entry browser with filters

Console Customers

Customer profiles, KYC status, account associations

Fee Management

Pricing plans, fee schedules, fee rules, fee simulation

Console Workflows

Workflow definitions, state machines, transition history

System Config

System settings, tenant configuration, calendar management

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=desc

Response includes totalCount, page, pageSize, and hasNextPage in the response envelope.

Webhooks

Bancorix can push real-time events to your endpoint on workflow transitions, payment status changes, and KYC decisions. Webhook delivery is configurable per tenant via system settings.

Webhook configuration is managed via POST /api/config/webhooks. Contact support to enable webhook delivery for your tenant.

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 Collection

Sandbox 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 (275+ 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

Request Sandbox Access