@payclave/sdk-js

Vanilla JavaScript SDK for Payclave — non-custodial crypto checkout for merchants.

Funds always move directly from the customer wallet to the merchant wallet. Payclave never custodies funds.

Published on npm as @payclave/sdk-js.

Install

npm install @payclave/sdk-js
# or
bun add @payclave/sdk-js

Quickstart

import { createPayclaveClient } from "@payclave/sdk-js"

const payclave = createPayclaveClient({
  publicKey: "pk_test_...",
})

// Create a checkout session, then redirect the browser to it.
await payclave.redirectToCheckout({
  amount: "25.00",
  reference: "order_123",
})

The recommended production flow is for your backend to create the session with a secret key, then your frontend opens the hosted checkout URL. Use @payclave/sdk-js from the browser only when a public-key flow is acceptable.

API

createPayclaveClient(options)

| Option | Type | Description | | ------------ | -------------------------- | ------------------------------------------------------------------------ | | publicKey | string | pk_test_... or pk_live_.... Required. | | apiBaseUrl | string | Override the API base URL. Defaults to https://api.payclave.com. | | fetcher | (url, init) => Response | Custom fetch implementation (testing, polyfills, custom headers). | | redirect | (url: string) => void | Custom redirect handler. Defaults to window.location.assign in browsers. | | timeoutMs | number | Per-request timeout. Aborts and rejects with code: "TIMEOUT". |

Returns { createCheckoutSession, redirectToCheckout }.

createCheckoutSession(input) / redirectToCheckout(input)

| Field | Type | Description | | ---------------- | ------------- | ----------------------------------------------------------------- | | amount | string | Positive decimal with up to 18 fractional digits, e.g. "25.00". | | reference | string | Your order reference. Sent as externalReference. | | idempotencyKey | string? | Sent as Idempotency-Key header. Safe to retry the same request with the same key. | | signal | AbortSignal?| Cancel the request. |

redirectToCheckout additionally calls the configured redirect (or window.location.assign) with the hosted checkout URL.

mountPayclaveButton(target, options)

Mounts an unstyled <button> into the target element. Useful when you don't have a framework.

import { mountPayclaveButton } from "@payclave/sdk-js"

const target = document.getElementById("pay")!
const mounted = mountPayclaveButton(target, {
  publicKey: "pk_test_...",
  amount: "25.00",
  reference: "order_123",
  label: "Pay $25",
  className: "btn btn-primary",
  onError: (err) => console.error(err),
})

// Later:
mounted.destroy()

The button also dispatches a payclave:error CustomEvent on target when checkout fails.

Errors

All client- and server-side failures throw a PayclaveError:

import { PayclaveError } from "@payclave/sdk-js"

try {
  await payclave.createCheckoutSession({ amount: "25.00", reference: "o_1" })
} catch (err) {
  if (err instanceof PayclaveError) {
    err.code      // "VALIDATION_ERROR" | "NETWORK_ERROR" | "TIMEOUT" | "ABORTED" | ...
    err.status    // HTTP status, or 0 for client/transport errors
    err.requestId // Server request ID, when available
    err.details   // Server-provided detail payload, when available
    err.cause     // Underlying error (transport failure, etc.)
  }
}

Built-in client codes: INVALID_PUBLIC_KEY, INVALID_AMOUNT, INVALID_REFERENCE, INVALID_RESPONSE, NETWORK_ERROR, TIMEOUT, ABORTED, REDIRECT_UNAVAILABLE. Server-supplied codes are passed through unchanged.

SDK identification

Every request includes X-Payclave-Client: payclave-sdk-js/<version> so the API can correlate bug reports to SDK versions.

License

MIT — see LICENSE.