# Medimine bank-transfer workflow: integration contract

This describes the later secure backend. The current Sites page is an in-memory synthetic review. Its buttons/checkboxes are not authentication, bank verification, corporate authority or production endpoints. Never connect real funds/documents to its client-side approval flags.

## Ownership and access

- `participant`: only their own account, purpose-specific profile, applications, approved instructions, evidence metadata and private documents.
- `clinical_practitioner`: assigned clinical profiles/encounters only; verified credentials and clinical consent; no routine corporate or bank-statement access.
- `finance_verifier`: authorised orders, submitted evidence, receiving-bank credit reconciliation and payment decisions; no routine medical history.
- `corporate_issuer`: actual issuer, reviewed agreements, allotments/member register and authorised issuance; payment confirmation alone is insufficient.
- `training_reviewer`: authorised completion records; cannot create equity.
- `administrator`: configuration/role management and audited exceptions. Prefer maker/checker separation for sensitive payments and ownership documents.

Use existing main-application authentication and verified contacts rather than a second plaintext password store. Enforce per-record ownership on every endpoint. Require CSRF protection, rate limits, input validation, and controlled private downloads.

## Durable records

| Record | Minimum relevant fields / constraints |
| --- | --- |
| accounts | immutable ID, verified contact references, authentication source, account status |
| profiles | account, purpose/role, consent version/time, guardian/authority where required; clinical data isolated |
| task_versions | source row, classification, service/offer status, approved terms version, active/disabled reason |
| applications | account, profile, task/version, location/project component, purpose, eligibility status, review actor/time |
| orders | approved legal entity, application, quote/contract, integer minor amount, BDT currency, unique payment reference, expiry |
| payment_evidence | order, minimal transfer metadata, private object reference, checksum, evidence state |
| bank_credits | receiving account, unique bank-entry identity/reference, actual amount/currency/value date, reviewer/source |
| payment_reviews | evidence/order, matched bank credit, decision, reason, actor, time, previous/new status |
| receipts | unique number, unique confirmed-payment relation, immutable issuance snapshot, private PDF/hash, status |
| approved_instruments | issuer, instrument type, agreement version, eligibility/offer review, legal basis/approval or exemption reference |
| allotments / holdings | issuer, member, approved allocation/class/quantities, register reference, corporate approval, filing due/status |
| completion_records | learner, programme/session, completion criteria and authorised reviewer/time |
| issued_documents | unique issuer/document number, approved source record/version, template/execution approval, hash, private file, status |
| audit_events | actor, action, record, request/idempotency ID, time, before/after/status, reason |
| reversals / refunds | linked original payment/receipt, actual settlement status, amount, reason, actor, time; no silent deletion |

Store monetary values as integers in minor units. Use database transactions and unique constraints for bank-credit use and receipt/issue relations. Do not derive paid status from an editable form amount or browser storage. Multiple instalments/overpayments require a reviewed allocation ledger rather than pretending every transfer fully pays an order.

## API actions

| Action | Server requirement |
| --- | --- |
| POST /applications | authenticated owner; enabled task/version; minimum required profile/consent; return opaque application ID |
| PATCH /profiles/{id} | owning account/authorised clinical role; approved fields; purpose/consent requirements; audit |
| POST /applications/{id}/quote | authorised operator; approved service/offer terms and issuer; server-supplied price; immutable order version |
| GET /orders/{id}/bank-instructions | owner; approved order/eligibility; configured authorised beneficiary; no instructions for disabled/unclassified offer |
| POST /orders/{id}/payment-evidence | owner; private upload controls; reference/amount/date metadata; status under_review only |
| POST /finance/payment-reviews/{id}/verify | authenticated finance verifier; independent receiving-bank credit; exact order purpose/currency/amount handling; duplicate detection; audit |
| POST /finance/payment-reviews/{id}/reject | authorised verifier; reason; keep evidence/history; no receipt |
| POST /corporate/allotments | corporate authority; actual issuer/instrument and approved member allocation; register and filing workflow |
| POST /corporate/documents/{id}/approve | authorised issuer; appropriate agreement/holding/allotment or approved contractual instrument; execution/template review |
| POST /training/completions/{id}/approve | authorised completion reviewer; applicable programme requirements |
| GET /documents/{id} | owner or authorised officer; private document version; no guessed-ID public access |
| GET /verify/{opaqueToken} | minimal issuer/type/number/issue/status metadata only; no medical details, full bank data, identity uploads or full document |
| POST /finance/refunds-or-reversals | authorised accounting workflow; linked original record; actual settlement tracking; document status updates audited |

Receipt and document generation are server jobs after committed, authorised events; callers do not choose arbitrary `paid=true`, `role=admin`, amounts or template values. Use idempotency keys and unique constraints so retries return the same receipt/document. A certificate cannot be issued by a public GET request or a payment screenshot.

## Payment state transitions

`awaiting_transfer -> evidence_submitted -> under_review -> verified -> receipt_issued`.

Exceptions: `needs_information`, `rejected`, `partially_paid`, `overpaid`, `refund_pending`, `refunded`, `reversed`. Approved quotes/offers and profile requirements precede requesting funds. Financial and corporate approval state remain separate. Once issued, receipt snapshots cannot be edited in place.

## Document routes

- Service/contribution receipts: after verified funds; booking, service-credit or contribution acknowledgement where appropriate.
- Share certificate: after applicable verified payment plus actual approved allotment/holding, member-register records and authorised execution. Track statutory filing/readiness clocks; company policy may add additional release checks.
- Contractual investment document: only for the actual approved instrument; does not claim equity shares. Unknown HAO/DPS/scheme classification blocks collection and issuance.
- Training completion certificate: after authorised completion and applicable fee settlement, separately from enrolment.
- Adviser application: no default investment fee, no share/investment certificate solely for being an adviser.

## Evidence and hosting

Keep medical/identity/bank evidence out of the public static directory. Limit file types/sizes, validate actual content, generate storage filenames, scan where appropriate, and serve through authorised endpoints. Do not ask for bank PINs, OTPs or passwords. Confirm clinical platform licensing, Bangladesh patient-data hosting and current consent/privacy requirements before real clinical records are enabled.

## Required activation configuration

No actual beneficiary, price, share class/quantity, return/duration promise, registration number, signature, or legal template is configured by this prototype. Supply approved company/account details, task/quote schedules, legal classification/terms, refund rules, issuer/execution templates, role assignments and clinical-hosting arrangements. Keep collection disabled until relevant inputs and permissions are confirmed.