@kordiva/sdk — Node.js server client

Published release: SDK 0.1.3 is publicly available on npm. Package installation does not activate new backend features.

@kordiva/sdk

Public npm package · TEST/LIVE rules · API reference

Use this package when your own Node.js backend must read a Kordiva store catalog or create a checkout. It is not a browser library. Downloading the package is public; calling the API requires an eligible store and a matching Store API key from CMS → Settings → API Keys.

pnpm add @kordiva/sdk@0.1.3

TEST: read products and create an isolated checkout

import { Kordiva } from "@kordiva/sdk";

const client = new Kordiva({
  baseUrl: process.env.KORDIVA_API_ORIGIN!,
  storeId: process.env.KORDIVA_STORE_ID!,
  apiKey: process.env.KORDIVA_TEST_API_KEY!,
  environment: "TEST",
});

const catalog = await client.products.list({ limit: 20 });
const productId = catalog.items[0]?.id;
if (!productId) throw new Error("No approved products");
const test = await client.checkout.createTest({
  productId,
  testSaleMarket: "AU", // only an approved TEST market; not LIVE approval
});
// Return only test.url to your authenticated front end.

LIVE: hosted checkout and verified payment status

Use a different LIVE key, an approved store and product, and an authenticated merchant backend.

const live = new Kordiva({
  baseUrl: process.env.KORDIVA_API_ORIGIN!,
  storeId: process.env.KORDIVA_STORE_ID!,
  apiKey: process.env.KORDIVA_LIVE_API_KEY!,
  environment: "LIVE",
});

const session = await live.checkout.createHosted({
  lineItems: [{ productId: approvedProductId, quantity: 1 }],
  idempotencyKey: savedCartAttemptKey,
  checkoutLanguage: "en",
});
// Persist session.sessionId, savedCartAttemptKey, and the authenticated
// buyer/cart owner in durable server storage BEFORE returning checkoutUrl.
const payment = await live.payments.confirm({
  sessionId: savedSessionId,
  idempotencyKey: savedCartAttemptKey,
});
const paid = payment.status === "paid" &&
  payment.isPaid === true && Boolean(payment.orderId);

The LIVE code is an integration illustration, not a standalone runnable app: supply the authorized product, stable attempt key, saved session ID and persistent storage yourself. A checkout URL or success redirect is not payment proof. Only fulfill after verified payment and applicable product/Individual entitlement checks. The SDK does not automatically retry POSTs or guarantee exactly-once checkout creation.

What else is supported? products.get(), categories.list(), attributes.list(), and Business shippingMethods.list(). The optional @kordiva/sdk/webhooks is an approved agentic order-signature verifier, not an outgoing payment webhook or a Stripe verifier. Kordiva processes its own Stripe events; standard merchants use server-side payments.confirm() for LIVE checkout. TEST payment confirmation is checked in Kordiva TEST order evidence rather than the LIVE-only API.

Continue with the tested backend example, payment-status route, authentication, and security checklist.

Business integration

Recurring checkout and subscription reads → Signed Business events → Raw-body verification → Business refunds → API reference. Individual MoR follows its separate refund process.

0.1.3 also exposes client.subscriptions.get(id), client.subscriptions.list({ customerRef: "user_123" }) and client.checkout.createSubscription(input). Business HMAC verification uses verifyMerchantWebhook from @kordiva/sdk/merchant-webhooks; the P-256 agentic verifier above remains separate. The SDK has no public refund/change/cancel mutation.