Skip to content
Kordiva Docs

React & Next.js

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

@kordiva/react — a ready Buy button

Section titled “@kordiva/react — a ready Buy button”

Install @kordiva/react and @kordiva/checkout into your React 18.2+/19 or Next.js app:

Терминал
pnpm add @kordiva/react@0.1.3 @kordiva/checkout@0.1.3

CheckoutButton requests a checkout URL from your own authenticated backend, checks the trusted Kordiva host, disables duplicate pending clicks and redirects. It does not handle card details or treat the redirect as a successful payment. Keep @kordiva/sdk and Store API keys on your Node backend, not in client components. The full tested example below posts to /api/checkout.

  1. Keep @kordiva/sdk and all secrets in a Node server route. Do not import that client into a component marked 'use client'.
  2. Use the checkout handler from the checkout guide in app/api/checkout/route.ts, exporting its configured result as POST. Supply your existing customer session and cart authorization. Select the Node runtime for server crypto use.
  3. Render the tested BuyButton below. Keep attempt stable for the authorized cart. Supply a trusted allowedOrigins list from application configuration and an onError handler that shows a useful retry/reconciliation message.
  4. The button disables while opening checkout, blocks duplicate clicks during the pending action and validates the returned origin. It never treats navigation as payment success.

The browser callback posts to your own /api/checkout; it never sends a Kordiva key. Protect that route with same-origin/session checks and per-user limits. SSR does not create sessions. React is a peer dependency; no Next.js-specific dependency is required by the component.

react.ts
"use client";
import { createElement } from "react";
import type { CheckoutNavigationOptions } from "@kordiva/checkout";
import { CheckoutButton } from "@kordiva/react";
/** Keep attempt stable for the server-authorized cart, including uncertain results. */
export function BuyButton({
  attempt,
  allowedOrigins,
  checkoutOptions,
  onError,
}: {
  attempt: string;
  allowedOrigins: string[];
  checkoutOptions?: CheckoutNavigationOptions;
  onError: (error: Error) => void;
}) {
  return createElement(CheckoutButton, {
    allowedOrigins,
    checkoutOptions,
    onError,
    onCheckout: async () => {
      const response = await fetch("/api/checkout", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ attempt }),
      });
      if (!response.ok) throw new Error("Checkout unavailable");
      return response.json();
    },
  });
}

How the shopper sees payment success

Section titled “How the shopper sees payment success”

CheckoutButton opens checkout; it does not mark an order paid. Kordiva handles the Stripe webhook. After return, your UI can check an authenticated GET /api/payment-status?attempt=... endpoint on your own backend. Your server verifies cart ownership and calls the LIVE-only payments.confirm() with stored references. Display paid only after verified confirmation; otherwise pending, expired or an unavailable state. Poll your own endpoint briefly (for example every five seconds for up to one minute), with durable backend reconciliation for slow/abandoned payments. See the tested Node status example.

Local TEST and browser boundaries

Section titled “Local TEST and browser boundaries”

checkoutOptions={{ environment: 'TEST', allowLocalTest: true }} is an explicit development-only choice for the isolated local TEST link. Omit it for the normal HTTPS flow. Your exact origin allowlist is still required. A LIVE /q/ link over HTTP is rejected even with this opt-in.

Importing @kordiva/sdk or its webhook export into a browser entry is blocked by package exports, before construction. Use only the browser helpers in client components; do not place literal secrets in props or application source. Next.js App Router may use its bundled React runtime; standalone React SSR and framework builds are validated separately.

Section titled “Related guides”

SDK · Checkout · Security · API

Business integration

Section titled “Business integration”

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