proxmox/docs/03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md

DBIS OMNL → Indonesia / BNI E2E Integration Blueprint

Last updated: 2026-03-29
Purpose: Detailed end-to-end integration blueprint for moving value from OMNL as central-bank / settlement authority to Indonesian beneficiary banks, with FX, correspondent banking, messaging, reconciliation, and optional Chain 138 settlement augmentation.

1. Scope

This blueprint covers the full production path for:

• OMNL as settlement and banking ledger authority
• Indonesian beneficiary institutions such as Bank Kanaya and BNI-connected flows
• FX conversion and revaluation
• domestic and correspondent-bank settlement
• HYBX sidecar orchestration
• optional Chain 138 anchoring / settlement confirmation

This document is intentionally broader than the current deployed slice. It defines everything required to make the system fully production-complete.

2. Participant model

Mandatory participant classes

1. OMNL / central bank rail

   • source of settlement authority
   • operator of Fineract ledger
   • owner of reserve, treasury, and reporting policy

2. HYBX / sidecar integration layer

   • compliance
   • posting
   • settlement orchestration
   • reconciliation
   • audit package generation

3. Indonesian beneficiary bank

   • Bank Kanaya in current repo-backed materials
   • BNI or BNI-connected domestic banking path for broader production rollout

4. Global correspondent / liquidity banks

   • USD / EUR / multicurrency correspondents
   • nostro / vostro counterparties
   • statement and confirmation providers

5. Chain 138 settlement lane

   • optional but strategically important if on-ledger finality is part of the regulated operating model

6. Depository / custody / liquidity-control layers

   • depository / CSD role for asset-register and settlement-touch scenarios
   • global custodian role for safekeeping, statements, and asset servicing
   • FX pricing / dealing engine for rate ownership and booking policy
   • liquidity pooling and aggregation engine plus source adapters for funding decisions

3. Full end-to-end stages

Stage 0 — Static setup

Required before live value movement:

• OMNL tenant and credentials frozen
• participant offices created
• beneficiary offices mapped
• GL chart complete
• FX reserve / revaluation accounts complete
• FX pricing hierarchy and quote-locking policy frozen
• liquidity source inventory and prioritization policy frozen
• depository / custody operating model frozen for any in-scope asset-backed or safekeeping flow
• payment types and maker-checker policy frozen
• sidecar-to-Fineract auth contract frozen
• external bank routing matrix frozen
• regulatory package template frozen

Stage 1 — Payment or settlement initiation

Possible initiators:

• OMNL treasury operator
• HYBX sidecar
• external banking system
• Mojaloop switch if later included
• ISO 20022 or MT gateway

Required artifacts:

• instruction id
• end-to-end id
• message id
• correlation id
• counterparty and beneficiary identifiers
• amount, currency, value date
• purpose / regulatory narrative

Stage 2 — Compliance and sanctions controls

Required checks:

• KYC / KYB status
• sanctions and watchlist screening
• limit checks
• liquidity and prefunding check
• source-of-liquidity selection and approval
• market conduct / rate authorization check
• jurisdictional eligibility

Required outputs:

• compliance decision
• reason codes
• approval / rejection metadata
• audit payload hash

Stage 3 — FX pricing and trade capture

Required capabilities:

• direct or triangulated rate determination
• XAU-based triangulation where required by current OMNL methodology
• rate-source reference
• trade timestamp and value date
• spread / fee logic
• approved trader / operator identity
• pricing-engine or dealer ownership of the approved quote

Required records:

• source currency
• destination currency
• quoted amount
• settlement amount
• rate
• fee / spread component
• realized vs unrealized P&L handling
• quote id and liquidity-decision reference

Stage 4 — OMNL accounting and posting

Required journal-entry families:

1. source debit
2. beneficiary or settlement credit
3. due-to / due-from interoffice leg where applicable
4. FX reserve / treasury leg where applicable
5. realized FX gain/loss leg where applicable
6. accrued fee leg where applicable

Mandatory OMNL data points:

• officeId
• glAccountId
• transactionDate
• currencyCode
• comments
• transaction reference

Stage 5 — External banking message exchange

5.1 Domestic Indonesia path

For Bank Kanaya / BNI-style domestic beneficiary credit:

• payment or settlement instruction generated
• local beneficiary validation completed
• beneficiary account / institution reference resolved
• domestic reporting obligations attached

5.2 Correspondent-bank path

For global-bank and cross-border settlement:

• route to correspondent or settlement bank selected
• nostro / vostro account chosen
• prefunding / cover logic confirmed
• message dispatched and acknowledged
• custody / safekeeping instructions attached where the flow involves held assets or global-custodian reporting

Stage 6 — Funds movement and settlement confirmation

Required evidence:

• bank acceptance / status message
• credit confirmation or rejection
• statement extract or advice
• confirmation of beneficiary-bank receipt
• unresolved exception queue if delayed
• custody statement / servicing reference where applicable

Stage 7 — Reconciliation and package generation

Required reconciliations:

1. sidecar request vs OMNL journal
2. OMNL journal vs office balances
3. FX trade blotter vs accounting postings
4. external bank confirmations vs OMNL settlement state
5. on-chain event vs OMNL event where chain leg exists
6. asset register / custody statement vs settlement state where depository flows apply
7. liquidity decision vs selected funding source vs actual settlement usage

Required evidence outputs:

• transaction package snapshot
• journal detail
• recent journal entries
• computed balances
• payload hash files
• ISO / SWIFT message archive references
• prudential and BI/OJK crosswalks

4. Required message families

ISO 20022

Message	Role in flow
pain.001	customer or enterprise initiation
pacs.008	FI-to-FI customer credit transfer
pacs.009	interbank settlement
pacs.002	status
camt.052	intraday report
camt.053	statement
camt.054	debit/credit notification

SWIFT Fin / legacy

Message	Role in flow
MT103	customer transfer
MT202 / MT202 COV	bank transfer / cover
MT910	credit confirmation where needed
MT950	statement where legacy paths require it

Internal / platform-specific

Message	Role
sidecar transfer envelope	canonical business payload
OMNL journal response	accounting confirmation
settlement reference manifest	cross-system correlation
chain settlement event	optional on-ledger finality evidence

5. BNI-specific and Indonesia-specific requirements

What must exist for a BNI-connected production path

1. BNI counterparty profile

   • institution identifiers
   • beneficiary validation rules
   • account structure
   • allowed currency pairs
   • reporting obligations

2. Domestic payment / settlement route definition

   • whether BNI is:
     • direct beneficiary bank
     • intermediary settlement bank
     • correspondent / nostro bank
   • final message set per route

3. Indonesia regulatory obligations

   • BI reporting crosswalk
   • OJK prudential bridge
   • FX reporting obligations
   • large exposure / related-party handling
   • settlement finality memo

4. Operational controls

   • cut-off times
   • business dates / value dates
   • holiday calendars
   • exception and return handling
   • maker-checker approvals

Current state

• Bank Kanaya path is documented in repo-backed material.
• BNI-specific live endpoint, auth, and correspondent contract are not yet evidenced in this workspace.
• Therefore the BNI lane is a required integration blueprint item, not a completed deployment.

6. Required funds-movement model

6.1 OMNL-only book transfer

Used when both parties settle on OMNL books.

Required:

• interoffice mapping
• due-to / due-from treatment
• no external correspondent required

6.2 OMNL to domestic beneficiary bank

Required:

• beneficiary institution mapping
• outbound settlement message
• inbound confirmation
• domestic regulatory reference

6.3 OMNL to global correspondent / global bank

Required:

• nostro selection
• cover / prefunding policy
• message dispatch
• statement reconciliation
• confirmation of receipt / finality

7. Required sidecar integrations

mifos-fineract-sidecar

Required responsibilities:

• canonical transfer ingest
• compliance check invocation
• OMNL posting
• transaction status tracking
• audit payload preservation

server-funds-sidecar

Required responsibilities:

• treasury approval and release
• limit checks
• prefunding and source-of-funds orchestration
• status / approval / exception workflow
• handoff to liquidity pooling and source-adapter decisions

off-ledger-2-on-ledger-sidecar

Required responsibilities:

• translate approved off-ledger event into on-ledger settlement action
• attach rates, conversion basis, and settlement refs
• record chain transaction linkage
• preserve depository / custody / liquidity references where those roles are in scope

Additional required control layers

Required responsibilities:

• FX pricing / dealing engine owns quote generation or approved rate ingest
• liquidity pooling and aggregation engine owns funding-source selection
• liquidity source adapters normalize bank-line, correspondent, internal-pool, and optional on-chain liquidity access
• depository / CSD layer owns asset-register and settlement-touch behavior for in-scope instruments
• global custodian layer owns safekeeping, statements, and asset-servicing obligations

Optional or later

• mt103-hardcopy-sidecar
• card-networks-sidecar
• securitization-engine-sidecar
• Mojaloop connector

8. Required Chain 138 integration

If on-ledger settlement is in scope, the following must be true:

1. settlement contract path is frozen
2. instrument selection is frozen
3. reserve / oracle dependencies are frozen
4. sidecar correlation id maps to chain tx hash
5. evidence package includes chain settlement proof
6. depository / CSD touch point is frozen where asset-backed flows exist
7. custody / safekeeping statement linkage is frozen where custody applies
8. liquidity-source decision reference is preserved in the evidence package

9. Reconciliation requirements

Mandatory reconciliation layers

1. Accounting reconciliation

   • OMNL JEs vs intended posting matrix

2. FX reconciliation

   • rate source vs booked rate
   • realized / unrealized P&L correctness

3. Bank reconciliation

   • statement / advice vs OMNL settlement state

4. Operational reconciliation

   • sidecar correlation IDs vs journal refs vs package refs

5. On-ledger reconciliation

   • chain tx vs off-ledger settlement event

6. Custody / depository reconciliation

   • asset register vs custody statement vs settlement state

7. Liquidity reconciliation

   • selected funding source vs liquidity decision vs actual settlement usage

10. Full production-complete gate

The OMNL → Indonesia / BNI → global-bank flow is only fully complete when:

1. one domestic Indonesia beneficiary flow is live and repeatable
2. one BNI-connected path is live and repeatable
3. one global correspondent-bank flow is live and repeatable
4. FX pricing, accounting, and revaluation are frozen and audited
5. all required ISO/SWIFT messages are archived and correlated
6. reconciliation package is reproducible
7. if chain settlement is in scope, the chain leg is included in the same evidence package

11. Current blockers

• no live BNI endpoint/auth contract captured in repo-backed state
• no live global correspondent-bank endpoint/auth contract captured in repo-backed state
• treasury / funds sidecar lane not yet validated end to end
• on-ledger settlement leg not yet included in the canonical transaction
• participant / office / treasury model not yet frozen across all counterparties
• depository / custody operating model not yet frozen
• FX pricing engine and liquidity aggregation ownership not yet frozen

12. Execution order

1. freeze participant / office / GL / nostro-vostro model
2. freeze depository / custody / FX / liquidity-control layers
3. freeze OMNL operator runbook
4. validate server-funds-sidecar
5. validate off-ledger-2-on-ledger-sidecar
6. acquire and document BNI / correspondent-bank endpoint and auth contracts
7. run one domestic Indonesia beneficiary-bank flow
8. run one correspondent-bank flow
9. add Chain 138 settlement leg if in scope
10. generate and sign the final evidence package

Related artifacts

• DBIS_OMNL_INDONESIA_BNI_E2E_EXECUTABLE_TASK_LIST.md
• DBIS_RTGS_FX_TRANSACTION_CATALOG.md
• DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md
• HYBX_BATCH_001_OPERATOR_CHECKLIST.md
• BANK_KANAYA_OFFICE_RUNBOOK.md
• PvP_MULTILATERAL_NET_SETTLEMENT_BANK_KANAYA.md
• FX_AND_VALUATION.md
• INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md
• SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md