Shadow Balance Management (SBL) APIs
Shadow Balance API Architecture Overview​
The Shadow Balance (SBL) service is the always-on, real-time balance engine inside ImPAI.
It maintains authoritative available, current, and reserved balances for all connected accounts and ensures consistent, validated balance information for upstream and downstream systems.
Operating 24/7, the SBL service plays a critical role in Instant Payments (e.g. SCT Inst) by ensuring that funds are available before a transaction is initiated or processed.
It acts as a high-performance balance ledger that synchronizes with the core banking system while supporting external clients through well-defined REST APIs.
These APIs enable:
- Real-time reservation creation, modification, and release
- Immediate visibility into account balances
- Safe and deterministic payment processing
- Consistent interaction with payment engines and internal systems
Service Categories​
| Category | Purpose |
|---|---|
| Reservation Services | Create, update, or release fund reservations used by payment flows. |
| Balance Inquiry Services | Retrieve current, available, and reserved balances in real time. |
| Lifecycle Tracking | Monitor reservation state changes for reconciliation or reporting. |
| Backoffice Integration | Support internal batch processes or system-driven balance operations. |
Each category exposes structured, consistent REST endpoints that ensure reliable integration with both internal systems and external client applications.
Where SBL APIs Fit Into the Payment Lifecycle​
Shadow Balance operations are fundamental to safe payment execution.
The diagram below shows where SBL interacts with the Instant Payment lifecycle — particularly around fund checks, reservation lock-in, and post-processing release.
| Legend | |
| Light Blue | API groups that perform a specific functional role in SCT Inst |
| Underlined Blue | Clickable — opens thecorresponding API documentation section |
| Light Green | Core execution stage that interacts with clearing & settlement systems |
List of Available Endpoints​
| Method | Endpoint | Description | Use Cases |
|---|---|---|---|
| POST | /api/sbl/v1 | Creates or updates a reservation, increasing or decreasing the hold amount depending on Debit/Credit type. | Incoming Instant Payments • Outgoing Instant Payments • External Systems |
| POST | /api/sbl/v1 | Releases a previously created reservation. Updates the hold balance. | Cancel payments • Expire reservations • Unlock funds |
What the Shadow Balance Service Tracks​
The SBL service manages a unified balance model that exposes consistent, real-time fund information.
Data Component Description Core Balance Balance synchronized from the core banking system. Hold / Reserved Balance Funds reserved for pending or in-flight payment operations. Available Balance Resulting balance taking reservations into account (Available = Core − Holds). Reservation Lifecycle Status timestamps, debit/credit flag, hold amount, and expiration logic.
ImPAI’s internal systems — including payment initiation, validation, approval, and exception handling — rely on on an SBL system to guarantee that funds are secured before any processing continues.