IT & integrations

Integrate cash import, settlement and local notice records with exact guards

Use the source-defined finance operations, stable identities and independent readbacks without confusing a local notice record with external delivery.

Current source · Supported scoped normal APIs executed against isolated fictional data, actual root UI confirmation and independently inspected stored records · 16 min read

Before you begin

Authenticate with an existing scoped account against the intended approved environment. Never include tokens or unmasked account numbers in screenshots or support exports.
Use the separate treasury and bank evidence controls in real operation. The observed payloads were confined to expressly fictional loopback training; no external transport exists.

1. Read scoped account and advice identities before writing

GET /api/v1/facility/{facilityId}/rcm/finance/bank-accounts/ provides masked account identifiers, beneficiary tri-state, named review state and Draft/active status. GET /api/v1/facility/{facilityId}/rcm/finance/{adviceId}/ provides the advice allocations and both balance identities. The exercised account is deliberately fictional, Draft and unverified. A real integration must establish its independent prerequisites rather than infer approval from a returned ID.

**Read advice before any fictional bank row exists · 2026-10-18**Actual MANSOQ current frontend, isolated fictional Polyclinic, Chrome1728×921. Before import the actual UI shows advice900SAR, cash ledger0SAR and Conserved, plus the explicitly fictional Draft account with Unknown beneficiary and Incomplete dual control. The zero is an empty-ledger arithmetic result, not proof of a known bank balance or bank receipt; the page warning separately says cash unknown until evidence arrives.
**Advice distributed900**: The advice contains reported paid600 and adjustment300, preserved separately in the stored advice allocation.
**Empty cash arithmetic**: Zero and Conserved here are not evidence that a real account was checked.
**Beneficiary unknown**: No beneficiary verification has occurred.
**Dual control incomplete**: The fixture remains Draft and must not be treated as approved settlement instructions.

2. Import the exact statement line once

POST /api/v1/facility/{facilityId}/rcm/finance/cash-receipt/ with bank_account, bank_reference, statement_reference, value_date, posting_date, amount, currency and counterparty_name. The observed mock import used600.00SAR on2026-10-18 and returned201 with is_returned.value=unknown. Re-importing the exact same identity returned the same bank transaction ID; reusing that bank reference/date with601.00 was refused400 bank_receipt_collision, preserving the original row. Import does not confirm that a real bank did not return the credit.

**Recognize the current facility-permission rendering mismatch · 2026-10-18**Actual MANSOQ current frontend, isolated fictional Polyclinic, Chrome1728×921. After normal API import/allocation of fictional600SAR, this existing Facility Admin sees1 unnotified receipt with unknown treasury return status and no confirmation button. Normal API access for the same actor reaches exact-reference validation rather than403. The current page uses global hasPermission without passing facility object permissions, so this is a UI mismatch, not evidence of a backend treasury denial.
**One unnotified receipt**: Count of local allocated receipt groups requiring notice, not a bank balance.
**Mock allocation600**: A deliberately fictional statement exercise.
**Return status unknown**: The UI did not render the control for this Facility Admin even though the facility API permits it.
**Queue ownership unknown**: A local receipt does not establish escalation ownership.

3. Allocate once with amounts carried separately

POST /api/v1/facility/{facilityId}/rcm/finance/settle/ with config_package, bank_transaction and allocations. Each allocation uses allocated_amount, optional advice/claim, fee_amount, deduction_amount, is_suspense and a written reason; named fees and deductions have their own fields. The exercised allocation named the advice only, allocated600.00, fee0 and deduction0. Its normal response conserved600. A second1.00 allocation was refused400 ledger_conservation because total distribution would become601. The service does not create a negative suspense plug. This fixture did not project cash to a claim.

**Interpret separate advice and cash identities after the exercise · 2026-10-18**Actual MANSOQ current frontend, isolated fictional Polyclinic, Chrome1728×921. Final UI readback retains advice900SAR conserved and a separate fictional cash600SAR conserved. Stored advice still reports paid600 plus adjustment300. The mocked bank allocation names the advice only; no claim cash projection occurred. The account remains Draft, beneficiaryUnknown and dual controlIncomplete. Neither green conservation badge establishes real bank evidence, legal collectibility or payer acknowledgement.
**Advice900 conserved**: Paid600 and adjustment300 remain separate facts.
**Fictional cash600 conserved**: Cash allocation is600, not900; a conserved ledger is an arithmetic identity.
**Advice variance zero**: Within-ledger conservation is not the300 difference between advice header and cash.
**Beneficiary still unknown**: No real beneficiary approval or activation was asserted.
**Dual control incomplete**: The exercise did not approve the fictional account.

4. Require separate named treasury confirmation

POST /api/v1/facility/{facilityId}/rcm/finance/confirm-bank-receipt/ requires bank_transaction and the exact statement_reference, plus the distinct can_confirm_rcm_bank_receipt facility authorization. Unknown return status refused the attempted notice400 payment_notice_not_evidenced. The observed root then used the actual UI control; wrong reference was refused and the correct mock reference stored is_returned=no with named actor, timestamp and audit event. A boolean alone is not treasury evidence. The UI’s Facility Admin object-permission mismatch is documented in the companion guide.

**Read exact-reference refusal without changing the receipt · 2026-10-18**Actual MANSOQ current frontend, isolated fictional Polyclinic, Chrome1728×921. Actual root UI confirmation with a deliberately wrong fictional reference was refused: Treasury confirmation must identify the recorded bank statement line exactly. The600SAR receipt and unknown return state remained. This is a local reference guard, not real bank verification.
**Wrong mock reference**: The entered reference does not match the retained mock statement line.
**Confirmation action**: This normal UI action produced the visible refusal.
**Exact refusal reason**: Correct the source reference; do not mark the receipt confirmed manually.
**Receipt still unnotified**: A refused confirmation does not clear the queue.

**Verify the saved local treasury attestation · 2026-10-18**Actual MANSOQ current frontend, isolated fictional Polyclinic, Chrome1728×921. Actual root UI confirmation of the exact fictional reference saved a named treasury attestation and displays Treasury confirmed. Independent persisted-record inspection verifies root actor, exact reference, confirmation timestamp and one audit event. There is still1 unnotified receipt: confirmation alone does not create a notice or send anything externally.
**Saved treasury badge**: Persisted confirmation actor/time are independently verified.
**Still unnotified**: A confirmation is not a local notice record or payer acknowledgement.
**Receipt identity retained**: The original fictional bank reference remains unchanged.
**600SAR retained**: Confirmation does not change the imported amount.

5. Record the notice with stable identity and verify the local boundary

POST /api/v1/facility/{facilityId}/rcm/finance/payment-notice/ with advice, bank_transaction, notice_identifier, amount, currency, payment_received_on and optional correlation_id/submitted_at. The observed mock600.00 notice created201, same identifier repeated200 deduplicated=true and same notice ID. A different identity covering already-notified600 was refused400 payment_notice_not_evidenced. Date, currency, actual allocation, unreturned attestation and remaining unnotified cash are separately checked. This source operation records a local notice/audit event; its audit action name does not prove transport. In this run submitted_at was omitted and independently remainedNULL; no external send occurred.

**Read the local notice queue after recording one notice · 2026-10-18**Actual MANSOQ current frontend, isolated fictional Polyclinic, Chrome1728×921. After the supported local payment-notice API records one600SAR notice, the actual UI receipt-without-notice queue drops1→0. Independent DB inspection confirms exactly one notice, submitted_atNULL, and no transport. Duplicate identity deduplicated; a new identity covering already-notified cash was refused. This is local queue state only, not delivery, payer acceptance or real cash.
**No locally unnotified receipt**: The count changed after the local record was created.
**Owners remain unknown**: Completing a local notice does not configure operational escalation.
**Local record queue**: No external transport or payer response is shown here.

6. Read independently after mutations and preserve both ledgers

Re-read GET /api/v1/facility/{facilityId}/rcm/finance/{adviceId}/balance-identities/ and suspense/. Verify bank/advice identity, allocation count, conserved amounts, exact treasury actor/time and notice identity against independent persisted records. The actual exercise stored exactly one mocked bank row, one600SAR advice-only cash allocation and one local600SAR notice while original advice900/paid600/adjustment300 remained. The queue became0, but queue owners, beneficiary approval and external delivery remained unestablished.

Observed outcomes and unexecuted paths

The normal API guards exercised were exact import deduplication, conflicting import refusal, unknown-return notice refusal, excess second distribution refusal, exact-reference UI refusal, successful named mock confirmation, notice identity deduplication and second-identity refusal. Real bank statement verification, three-person bank-account change approval, active-account lifecycle, cash-before-advice suspense, fee/deduction attribution, returned-payment and compensating reversal remain distinct workflows; this guide does not claim they were executed.

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.