Business API за претплати

Објавено издание: SDK 0.1.3 е јавно достапен на npm. Инсталацијата не активира серверски функции.

Англискиот технички текст подолу е авторитативен за оваа меѓународна Business интеграција. Методите, полињата и безбедносните правила се исти за MK, BA, RS и AL; ова не е Individual MoR. English guide.

This API is for eligible Business legal entities and sole traders in MK, BA, RS and AL. It is separate from Individual MoR. Use an authorized store-specific server key with its matching TEST/LIVE environment. Country does not change SDK method names or identity rules; LIVE eligibility still requires the applicable account and payment approval.

Create recurring checkout

Create an active recurring Checkout Link in CMS first. Its product, price, currency and interval are the authority; the API request does not accept a replacement amount or interval.

business-subscriptions.ts

import { Kordiva, type SubscriptionCheckoutInput } from "@kordiva/sdk";

/** Node server configuration only. A matching LIVE store key is required. */
export function businessClient() {
  return new Kordiva({
    baseUrl: process.env.KORDIVA_API_ORIGIN!,
    storeId: process.env.KORDIVA_STORE_ID!,
    apiKey: process.env.KORDIVA_LIVE_API_KEY!,
    environment: "LIVE",
  });
}

/** The caller must authenticate the customer and load this attempt from its
 * durable server-owned records. Never pass arbitrary browser input as trustedAttempt.
 */
export async function startRecurringCheckout(
  client: Kordiva,
  trustedAttempt: SubscriptionCheckoutInput,
) {
  const checkout = await client.checkout.createSubscription({
    checkoutLinkId: trustedAttempt.checkoutLinkId,
    customerRef: trustedAttempt.customerRef, // for example: "user_123"
    idempotencyKey: trustedAttempt.idempotencyKey,
    orderRef: trustedAttempt.orderRef,
    successUrl: trustedAttempt.successUrl,
    returnUrl: trustedAttempt.returnUrl,
  });
  // Persist checkout.sessionId against the authenticated owner BEFORE returning its URL.
  // A return URL is navigation; verified Business events/canonical reads establish state.
  return checkout;
}

/** Caller must authorize this subscription/customer before returning data to a shopper. */
export function readSubscription(client: Kordiva, ownedSubscriptionId: string) {
  return client.subscriptions.get(ownedSubscriptionId);
}

export function findCustomerSubscriptions(
  client: Kordiva,
  customerRef: string,
) {
  return client.subscriptions.list({
    customerRef,
    status: "active",
    limit: 25,
    offset: 0,
  });
}

This is an integration example: replace the UUID with your approved recurring Checkout Link and bind customerRef from your authenticated server-side account. Never trust a browser query parameter, supplied email or arbitrary customerRef as identity. Kordiva binds that opaque reference through the server-created checkout into canonical subscription state. Use stable references without sensitive personal information.

checkoutLinkId is a UUID. customerRef is 1–128 characters; idempotencyKey is 8–128. Optional orderRef is 1–128 characters; optional successUrl/returnUrl must be HTTPS without embedded credentials. The method maps to POST /business/v1/stores/:storeId/subscription-checkouts, returns sessionId, checkoutUrl, expiresAt, customerRef and orderRef, and is LIVE-only. It rejects a TEST client; subscription reads and synthetic webhook setup still support TEST.

Keep the same key and identical request for an uncertain attempt; changing its input can conflict. Do not start a second checkout merely because a request timed out. Browser success/return URLs are navigation, not payment or activation proof. Verify signed Business events and reconcile canonical subscription reads before changing access. subscription.created can represent trialing and is not evidence of an initial paid invoice.

Billing intervals

Set these on the recurring Checkout Link, not in createSubscription:

| Schedule | billingInterval | billingIntervalCount | | --- | --- | --- | | Monthly | MONTH | 1 | | Every six months | MONTH | 6 | | Yearly | YEAR | 1 |

Во CMS, секој Business линк за претплата може да избере дозволена валута според регистрираната организација, независно од главната/каталошката валута на продавницата. Се користи заедничката политика: MK дозволува MKD/EUR/USD; BA Business дозволува EUR/USD/BAM; RS/AL дозволуваат EUR/USD.

Внесете го периодичниот износ директно во избраната валута: линк од EUR 29.00 наплатува EUR 29.00 плус применливиот конфигуриран данок, и кога каталогот е во MKD. Kordiva не го конвертира автоматски износот или каталошките цени. Промена на валутата важи само за идни checkout сесии/цени; постојните претплати и историските фактури ја задржуваат првичната валута. TEST ја применува истата политика. API ја користи зачуваната валута на линкот; повикувачот не ја менува по барање. Изборот на валута не потврдува банкарско порамнување.

Read one subscription

Use the readSubscription helper above (client.subscriptions.get(id)).

Maps to GET /business/v1/stores/:storeId/subscriptions/:id. The subscription UUID must belong to the key’s store and environment. A foreign/missing record is not exposed. Your application must also enforce its own customer authorization before returning subscription details to a shopper; a merchant API key is not a shopper login.

List and filter

Use findCustomerSubscriptions(client, "user_123") above (client.subscriptions.list({ customerRef: "user_123" })).

Maps to GET /business/v1/stores/:storeId/subscriptions. The result contains items, total, limit and offset.

| Filter | Meaning | | --- | --- | | customerRef | Recommended opaque merchant-owned customer identity; 1–128 characters. | | email | Valid email convenience/search filter; contact data, not canonical identity. | | status | active, trialing, past_due, unpaid, incomplete, incomplete_expired, canceled or paused. | | limit | Integer 1–100; default 25. | | offset | Integer 0–10000; default 0. |

Reads are scoped to the authenticated store/environment; filters never widen tenant access. TEST canonical records may have null email, billing dates and cancellation fields; email-filtered TEST lists are empty because sandbox records do not persist that email. Do not infer missing TEST data from browser or Stripe metadata.

Each subscription exposes Kordiva id, customerRef, customerEmail, status, billingInterval, billingIntervalCount, amount, currency, currentPeriodStart, currentPeriodEnd, cancelAtPeriodEnd, canceledAt and endedAt. amount is an integer in minor currency units; currency is an uppercase ISO code. For example, 1000 with EUR is EUR 10.00. Catalog legacy decimal prices use a different representation. Nullable fields mean the canonical value is unavailable, not an invented zero or date.

The public subscription API is read-only apart from creating a checkout attempt. There is no SDK subscription cancellation/change method and no SDK refund mutation in this version. Use the supported CMS/support flows; follow the separate Business refunds and Individual refund model.

Related guides

SDK overview · Installation · Checkout · Business webhooks · Verification · API reference