LicenseChain

Mirror SDK

Official SDK for LicenseChain Pay Mirror Payload (strict mode). Package name: @licensechain/mirror-sdk (distributed by LicenseChain until public npm publish).

Use this SDK on your seller backend to build checkout payloads, verify redirect signatures, and confirm purchases with Pay. Full checkout API details: Pay Mirror API.

Capabilities

  • buildMirrorPayload() โ€” AES-256-GCM encrypted CLIENT_EMAIL plus redirect URLs and order TOKEN.
  • buildMirrorCheckoutUrl() โ€” https://pay.licensechain.app/checkout/{'{'}productId{'}'}?payload=....
  • verifyCallbackSignature() โ€” HMAC-SHA256 over the redirect query string (fail closed).
  • verifyPurchase() โ€” POST /api/checkout/mirror/validate with license + email.
  • Reference examples ship with the package for JavaScript, PHP, Python, Go, and Rust.

Limitations

  • Does not create orders or enforce business rules โ€” your seller backend must approve the sale first.
  • Does not charge subscription renewals โ€” use POST /api/checkout/mirror/subscription/charge from your backend.
  • Server-side only โ€” never embed callbackSecret in browser or mobile app bundles.
  • Strict mode only โ€” unsigned or legacy checkout flows are out of scope.

Integration rules (seller backend)

Before calling buildMirrorPayload or redirecting to Pay, your API may reject the request (for example listing not verified, or wrong product). Return a clear message to the client โ€” do not collapse these into a generic โ€œpayment failedโ€ string.

If a BFF route wraps your checkout preparation API, propagate upstreamMessage (and useful 4xx status) instead of masking the root cause: 

{`const body = await res.json() as { error?: string; upstreamMessage?: string };
if (!res.ok) {
  const msg =
    typeof body.upstreamMessage === "string" && body.upstreamMessage.trim() !== ""
      ? body.upstreamMessage.trim()
      : (body.error ?? "Failed to prepare checkout");
  throw new Error(msg);
}`}
Layer Responsibility
Seller API / BFF Auth, order creation, business rules, correct API base URL
Mirror SDK Payload encryption, checkout URL, callback verify, Pay verifyPurchase

Environment (seller site)

Integrators need the product callbackSecret (Dashboard or Core API POST /v1/products) and HTTPS thanksPage / cancelUrl for buildMirrorPayload(). Pay checkout stays at https://pay.licensechain.app.

Do not put third-party payment partner secret keys on your seller website for Mirror checkout โ€” Pay hosts payment collection. Test vs live follows the Pay product and Dashboard configuration.

Payload fields Pay reads

  • THANKS_PAGE โ€” success redirect
  • CANCEL_URL โ€” cancel redirect
  • TOKEN โ€” your order / session id
  • Encrypted CLIENT_EMAIL โ€” buyer email (AES-256-GCM with the product callback secret)

Security: callbackSecret

The product callbackSecret is used to:

  • Encrypt Mirror payload fields on your server.
  • Verify redirect signature query parameters.
  • Verify Pay merchant webhooks (x-lc-pay-signature โ€” different message format than redirect HMAC).

Never expose callbackSecret in frontend bundles, mobile apps, or public tickets. Build payloads and verify signatures only on trusted server routes. Rotate via product PATCH/PUT if leaked.

Related: Pay merchant webhooks, Pay Mirror API, Security best practices.

Strict mode flow

  1. Seller backend creates order / validates listing (return 4xx with a clear message on failure).
  2. Build payload with TOKEN, THANKS_PAGE, CANCEL_URL, and encrypted CLIENT_EMAIL.
  3. Redirect buyer to Pay checkout.
  4. On return, verify callback signature server-side (fail closed โ€” do not trust LCG / status alone).
  5. Call validate API; fulfill only when verified: true.

Install & usage

The package name is @licensechain/mirror-sdk (MIT, Node.js / TypeScript). It is not yet published on the public npm registry. Obtain the SDK package (folder or .tgz) from LicenseChain via the Dashboard or support, then install from that artifact: 

# From an extracted package directory
npm install ./LicenseChain-Mirror-SDK

# Or from a provided tarball
npm install ./licensechain-mirror-sdk-1.0.0.tgz

After public npm publish, the same package will install with npm install @licensechain/mirror-sdk. Until then, do not rely on the public registry โ€” that install currently fails with 404. 

{`import {
  buildMirrorPayload,
  buildMirrorCheckoutUrl,
  verifyCallbackSignature,
  verifyPurchase
} from "@licensechain/mirror-sdk";

const { payloadBase64Url } = buildMirrorPayload({
  thanksPage: "https://seller.example.com/thanks",
  cancelUrl: "https://seller.example.com/cancel",
  callbackSecret: process.env.MIRROR_CALLBACK_SECRET,
  token: "order_8f2a9f0c61",
  clientEmail: "buyer@example.com"
});

const checkoutUrl = buildMirrorCheckoutUrl(
  "https://pay.licensechain.app",
  "YOUR_PAY_PRODUCT_ID",
  payloadBase64Url
);

// Redirect customer to checkoutUrl, then on return:
const isValid = verifyCallbackSignature(callbackUrl, process.env.MIRROR_CALLBACK_SECRET);
if (!isValid) throw new Error("Invalid callback signature");

const validation = await verifyPurchase({
  apiBaseUrl: "https://pay.licensechain.app",
  license: "LC-XXXX-XXXX",
  email: "buyer@example.com"
});
if (!validation.verified) throw new Error("Purchase not verified");`}

Related