Прескокни до содржината
Kordiva Docs

Business Merchant webhooks

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

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

Kordiva sends signed lifecycle events to an eligible Business merchant backend for MK, BA, RS and AL legal entities and sole traders. Individual MoR uses separate responsibilities and is not this channel. This guide describes the integration; package download alone does not activate server features or approve LIVE commerce.

Stripe → Kordiva processing → canonical Kordiva state
       → signed Kordiva Business event → merchant backend

For standard Kordiva-hosted Business commerce, merchants do not create or process their own Stripe webhook. Kordiva handles Stripe events and records canonical state; your backend receives Kordiva events. Keep Stripe secrets out of your merchant integration. A browser success URL is navigation, not payment proof.

Use verifyMerchantWebhook from @kordiva/sdk/merchant-webhooks. The existing @kordiva/sdk/webhooks P-256 agentic order-signature verifier is a separate contract; it remains documented in payment confirmation and agentic webhooks.

Events

Дел „Events“

| Type | Canonical meaning | | --- | --- | | payment.succeeded | A canonical Business order/invoice payment is recorded as paid. Check the bound customer, order/subscription, amount and currency. | | payment.refunded | Canonical refund state/amount advanced. This does not promise the customer’s bank-credit date or expose a refund-creation API. | | subscription.created | Subscription became active/trialing. Distinct from renewal; trialing/activation alone does not prove an invoice was paid. | | subscription.renewed | A later billing-period invoice was paid, with a strictly earlier paid period as evidence. Initial/replayed initial payment is excluded. | | subscription.updated | Canonical subscription fields changed; inspect the snapshot or read current state. | | subscription.past_due | Actual canonical transition into past_due, not an arbitrary raw provider failure message. | | subscription.canceled | Actual canonical canceled state, not merely a future cancellation request. |

cancelAtPeriodEnd: true schedules cancellation; it is not already canceled. A later canonical canceled transition is separate. Events are immutable snapshots and may arrive out of order. Do not overwrite current state using arrival order; reconcile through subscription reads when needed.

Payload version and identity

Дел „Payload version and identity“

The current payload version is 2026-10-01. An illustrative subscription payment event:

merchant-event.json
{
  "id": "33333333-3333-4333-8333-333333333333",
  "version": "2026-10-01",
  "type": "payment.succeeded",
  "environment": "LIVE",
  "occurredAt": "2026-10-01T12:00:00.000Z",
  "organizationId": "44444444-4444-4444-8444-444444444444",
  "storeId": "55555555-5555-4555-8555-555555555555",
  "customer": { "id": "66666666-6666-4666-8666-666666666666", "ref": "user_123", "email": "buyer@example.com" },
  "subscription": {
    "id": "22222222-2222-4222-8222-222222222222",
    "status": "active",
    "billingInterval": "MONTH",
    "billingIntervalCount": 1,
    "amount": 1000,
    "currency": "EUR",
    "currentPeriodStart": null,
    "currentPeriodEnd": null,
    "cancelAtPeriodEnd": false
  },
  "payment": {
    "id": "77777777-7777-4777-8777-777777777777",
    "orderId": null,
    "status": "paid",
    "amount": 1000,
    "currency": "EUR",
    "refundedAmount": 0
  }
}

| Field | Use | | --- | --- | | id | Stable Kordiva event UUID; durable deduplication key. | | version, type | Contract version and one of the supported event types. | | environment | TEST or LIVE; verify against receiver configuration. | | occurredAt | Canonical event timestamp; different from each delivery signature timestamp. | | organizationId, storeId | Tenant scope; check your expected values before accepting. | | customer.id | Kordiva customer/mapping reference, nullable. | | customer.ref | Opaque merchant-owned customerRef bound server-side, such as user_123; nullable. | | customer.email | Contact/search data, nullable; never canonical customer identity. | | subscription | Event-dependent canonical subscription snapshot. | | payment | Event-dependent canonical order/invoice payment snapshot; integer minor-unit money and ISO currency. |

Not every event includes both subscription and payment. A synthetic TEST event may contain only the envelope/customer fields and test: true. It is a delivery/signature test, not proof of a financial transaction. No raw Stripe payload, card/bank data or signing secret belongs in this envelope. An email change must not change your customerRef identity.

CMS setup

Дел „CMS setup“
  1. Select the Business store, then Settings → API keys. Authorized Business administrators see the Developers / Webhooks card on that page.
  2. Select the correct TEST/LIVE mode before creating an endpoint. Credentials, endpoint records and delivery history are isolated by environment.
  3. Enter the Public HTTPS endpoint, choose Events, and select Add endpoint. Use your backend receiver, with a publicly reachable HTTPS destination. Private/internal hosts, embedded credentials and redirects are not supported.
  4. Save the displayed key ID and signing secret immediately in protected server configuration; the signing credential is shown only once. Never put it in a client bundle or share it with customer requests.
  5. In TEST, Send TEST event queues a synthetic event using the endpoint’s first selected type. This button is not available in LIVE. Verify it and record it without fulfilling a real purchase.
  6. Open Delivery history to inspect event ID, delivery status, attempt count and last HTTP status. A queued test is not proof of acceptance; confirm a delivered status and your own durable inbox record.
  7. Rotate key invalidates the old credential immediately. Save the replacement when shown and coordinate receiver configuration. Pending retries retain event identity/body but use the current key; no old-key grace period is promised.
  8. Disable pauses pending deliveries; Enable allows them to resume. New events while the endpoint is disabled are not retroactively backfilled. Delete removes the endpoint and its associated delivery records; do not use deletion as a pause.

The SDK verifies events; it does not expose endpoint registration or key-management methods. Use these existing CMS controls. API keys for outbound Store API requests and webhook signing credentials are separate secrets.

Delivery and retries

Дел „Delivery and retries“
  • Delivery is at least once. The event ID and exact outbound body bytes remain stable across retries; signature timestamp/key/signature can change. An old occurredAt can be legitimate on a retry; the verifier checks the current signature timestamp window.
  • Return HTTP 2xx only after safely recording/deduplicating the event in durable storage. A 2xx acknowledgement ends delivery; do not acknowledge before a crash could lose the event.
  • Transport failures and HTTP 408, 425, 429 or 5xx retry with bounded exponential backoff. There are at most eight network attempts, not unlimited retries.
  • Other 4xx and redirects are terminal. Fix receiver/authentication problems rather than expecting endless retries; redirects are not followed.
  • Disabled endpoints pause. Temporarily ineligible merchant contexts are deferred rather than repeatedly attempted; permanently retired/invalid contexts stop delivery. An unrelated tenant does not block other deliveries.
  • Record event.id uniquely and enqueue effects atomically. Duplicates, concurrent requests and out-of-order arrival must not create duplicate receipts/access changes. Use canonical reads for reconciliation rather than inferring payment from navigation.

See the raw-body verification and handler pattern. Business refunds remain the legal seller’s supported flow; Individual MoR refunds are a separate Kordiva-controlled process. No SDK refund mutation is added.

Дел „Related guides“

SDK overview · Installation · Checkout · Subscriptions · Business refunds · API reference