@demystify/finance-contracts

Zod schemas for every cross-boundary type of Demystify Pay + Demystify Sign — money, payments, payouts, mandates, profiles, bank connections, envelopes, outbound webhooks, GL journals, core events, the error envelope, and the canonical RBAC role set.

The single source of truth for the SDK, both services, and every consuming product.

• Governed by: doc 44 §5, doc 45 §6
• Status: published. Installable by Finocket / Asher Work / Miatz — see docs/46-INTEGRATION-GUIDE.md.
• Invariant: regulated custody stays with the licensed partner; this repo never holds funds or signing keys.

The rule this package exists to enforce

Request AND response are contracts. An endpoint whose response is ad-hoc JSON is an endpoint a consumer has to reverse-engineer from a curl transcript. Every request schema here has a matching *Result.

Layout

| Path | What | |---|---| | primitives.ts | Money (integer minor units, never a float), PositiveMoney, DidScope, Uuid, IdempotencyKey, Timestamp | | errors.ts | ErrorEnvelope, the closed ErrorCode catalogue, and the status each maps to | | roles.ts | FINANCE_ROLES / SIGN_ROLES — the canonical access.* grants | | payments/ | status.ts (the normalised vocabulary), collect.ts, payout.ts, mandate.ts, profile.ts | | sign/ | document-type.ts (incl. the IT-Act First Schedule guard), envelope.ts | | bank/ | Account Aggregator consent, accounts, transactions, statement import | | webhooks/ | events.ts (the outbound event catalogue) + signature.ts (HMAC scheme, retry policy) | | gl/ | journal.ts — the Finocket GL bridge's balanced double-entry DTO |

Two things worth knowing before you use it

Money is an integer in minor units. { amountMinor: 150000, currency: "INR" } is ₹1,500.00. There is no float anywhere in this package, because a float rupee amount cannot represent ₹0.01 exactly and a ledger that cannot round-trip its own amounts is not a ledger. Money permits zero (a UPI collection genuinely carries a zero MDR fee); PositiveMoney does not, and is what every instruction that actually moves value uses.

Outbound ≠ inbound webhooks. webhooks/ here is what Demystify sends to a product. services/webhooks is the separate service that ingests provider callbacks from Razorpay, Cashfree and Digio. They share nothing but the word, and conflating them is how a consumer ends up verifying the wrong signature.