@demystify/finance-sdk

The typed client every Demystify product integrates once — Demystify Pay (collect, pay out, mandate, refund) and Demystify Sign (envelopes), plus the verifier for the webhooks we send you.

Full walkthroughs with runnable curl per flow: docs/46-INTEGRATION-GUIDE.md.

Install

npm install @demystify/finance-sdk

The SDK re-exports every contract, so this one dependency is all you need.

Use

import { createDemystifyFinanceClient } from "@demystify/finance-sdk";

const demystify = createDemystifyFinanceClient({
  baseUrl: process.env.DEMYSTIFY_FINANCE_URL!,
  // A demystify-core (D1) access token with audience `demystify-finance`.
  // Pass a function when tokens are short-lived — it is called per request.
  token: () => getDemystifyAccessToken(),
});

const payment = await demystify.payments.create({
  profileId,
  money: { amountMinor: 150000, currency: "INR" },   // ₹1,500.00
  orderRef: "INV-2026-0042",
  idempotencyKey: "INV-2026-0042",
});

redirect(payment.checkoutUrl!);

demystifyOrgId is filled from your token, so you never repeat it. The service re-derives it from the verified claim regardless — that is where the actual tenant isolation lives.

Four things that will save you a bad afternoon

Money is an integer in minor units. 150000 is ₹1,500.00. There are no floats in this API.

Always pass idempotencyKey on anything that moves money. If the connection drops after we receive your payroll batch but before you read the response, retrying with the same key returns the original batch instead of paying everyone twice.

Verify webhooks with the RAW body. Read the bytes before any body parser touches them — re-serialising parsed JSON reorders keys and changes whitespace, and the signature will not match. This is the single most common integration bug with any signed webhook.

import { verifyWebhookSignature } from "@demystify/finance-sdk";

app.post("/webhooks/demystify", express.raw({ type: "application/json" }), async (req, res) => {
  const event = await verifyWebhookSignature({
    rawBody: req.body.toString("utf8"),
    signatureHeader: req.header("x-demystify-signature"),
    secret: process.env.DEMYSTIFY_WEBHOOK_SECRET!,
  });

  // `event.id` is stable across retries — dedupe on it and return 200 for a repeat.
  if (await alreadyProcessed(event.id)) return res.sendStatus(200);

  if (event.type === "settlement.completed") {
    await postJournal(event.data);   // narrowed by `type`
  }
  res.sendStatus(200);
});

Branch on error.code, not on the status. Two different 403s (a missing role vs. a cross-org payload) need different fixes, and a 422 it_act_excluded_document is a legal outcome to show a user — never a retry.

import { DemystifyApiError } from "@demystify/finance-sdk";

try {
  await demystify.envelopes.create({ documentType: "will", /* … */ });
} catch (error) {
  if (error instanceof DemystifyApiError && error.code === "it_act_excluded_document") {
    return showToUser("A will cannot be signed electronically under Indian law.");
  }
  if (error instanceof DemystifyApiError && error.isRetryable) {
    return retryWithSameIdempotencyKey();
  }
  throw error;
}

Surface

| Resource | Methods | |---|---| | payments | create, get, createLink, refund | | payouts | createBeneficiary, create, createBatch, approveBatch, get | | mandates | create, debit, cancel | | envelopes | create, send, get, void | | — | verifyWebhookSignature |

Responses are validated against the contracts on the way in, so a shape drift on our side becomes a loud failure at the call site rather than an undefined three frames later.