JavaScript SDK
Drop-in crypto checkout widget for any website. One script tag, 20 lines of code, and you are accepting cryptocurrencies across 5 EVM networks with WalletConnect, QR codes, and same-day fiat settlement.
The SpacePay JavaScript SDK is a lightweight browser script that renders a full crypto checkout experience inside your page. It handles wallet connection, QR code display, blockchain monitoring, exchange rate locking, and settlement — with zero backend changes required for the customer-facing flow.
Unlike redirect-based integrations, the widget mounts directly inside your page. The customer never leaves your domain. The URL bar never changes. Your checkout conversion rate benefits accordingly.
Installation
Two installation methods are available: CDN (recommended for vanilla HTML sites) and npm (for bundled projects).
Option A: CDN script tag
<!-- Add to <head> or before </body> --> <script src="https://js.spacepay.co.uk/v2/spacepay.js" async ></script>
Option B: npm package
npm install @spacepay/client-sdk # or yarn add @spacepay/client-sdk
Basic Usage
Initialise the SDK once when your page loads, then call createCheckout when the customer clicks your payment button:
// Initialise once on page load
SpacePay.init({
publishableKey: "pk_live_YOUR_PUBLISHABLE_KEY",
});
// Call when customer clicks "Pay with crypto"
document.getElementById("pay-button").addEventListener("click", () => {
SpacePay.createCheckout({
amount: 149.99,
currency: "GBP",
reference: "ORDER-8827",
description: "Annual Pro Plan",
onSuccess: (payment) => {
console.log("Payment confirmed:", payment.id);
window.location.href = "/order/success";
},
onError: (error) => {
console.error("Payment failed:", error.message);
},
onExpire: () => {
console.log("Payment window expired");
},
});
});The widget mounts as a modal overlay on top of your page. On mobile, it renders as a full-screen bottom sheet. The customer selects their preferred cryptocurrency, connects their wallet or scans a QR code, and approves the transaction. When the blockchain confirms, onSuccess fires automatically.
Using the npm package
import { SpacePay } from "@spacepay/client-sdk";
const spacepay = new SpacePay("pk_live_YOUR_PUBLISHABLE_KEY");
button.addEventListener("click", async () => {
await spacepay.checkout({
amount: 99.00,
currency: "USD",
reference: "ORDER-001",
onSuccess: (payment) => handleSuccess(payment),
});
});Configuration Reference
| Option | Type | Required | Description |
|---|---|---|---|
| amount | number | Yes | Payment amount in the specified currency |
| currency | string | Yes | ISO 4217 code: GBP, USD, EUR, etc. |
| reference | string | Yes | Your unique order/invoice ID |
| description | string | No | Shown to the customer in the widget |
| tokens | string[] | No | Restrict to specific cryptocurrencies |
| onSuccess | function | No | Called with payment object on confirmation |
| onError | function | No | Called with error object on failure |
| onExpire | function | No | Called when rate-lock window expires |
| theme | object | No | Override widget colours and styling |
| locale | string | No | Widget language. Defaults to browser locale. |
Styling the Widget
Pass a theme object to match the widget to your brand. The widget inherits your page font by default:
SpacePay.createCheckout({
amount: 49.99,
currency: "GBP",
reference: "ORDER-9910",
theme: {
primaryColor: "#6366f1", // your brand colour
backgroundColor: "#ffffff", // widget background
textColor: "#111827", // primary text
borderRadius: "12px", // widget corner radius
fontFamily: "Inter, sans-serif",
darkMode: false, // force dark or light
},
onSuccess: (payment) => console.log(payment),
});TypeScript Types
The npm package includes full TypeScript definitions. Key types:
import type {
CheckoutOptions,
PaymentConfirmation,
PaymentError,
SpacePayTheme,
} from "@spacepay/client-sdk";
const options: CheckoutOptions = {
amount: 149.99,
currency: "GBP",
reference: "ORDER-8827",
theme: {
primaryColor: "#2563eb",
} satisfies SpacePayTheme,
onSuccess: (payment: PaymentConfirmation) => {
console.log(payment.id, payment.txHash, payment.settledAmount);
},
onError: (error: PaymentError) => {
console.error(error.code, error.message);
},
};Widget Events
In addition to callback options, the SDK emits DOM custom events you can listen to from anywhere in your page:
window.addEventListener("spacepay:open", () => {
analytics.track("checkout_opened");
});
window.addEventListener("spacepay:confirmed", (e) => {
const { paymentId, reference, amount } = e.detail;
analytics.track("purchase", { revenue: amount });
});
window.addEventListener("spacepay:closed", () => {
// Widget dismissed by user without paying
analytics.track("checkout_abandoned");
});Frequently Asked Questions
Does the JavaScript SDK work with vanilla HTML, not just frameworks?
Yes. The SpacePay JavaScript SDK is a standalone browser script. Add a single <script> tag, call SpacePay.init, and you are done. No build step, no framework required.
Is the publishable key safe to include in frontend code?
Yes. The publishable key (pk_live_...) can only create checkout sessions and is designed for frontend use. It cannot access account data, trigger withdrawals, or perform any sensitive operations. Never use your secret key in frontend code.
Does the widget support WalletConnect and MetaMask?
Yes. The widget supports WalletConnect v2, MetaMask browser extension, Coinbase Wallet, Trust Wallet, Phantom, and 300+ other wallets. A QR code is always shown as a fallback for mobile scanning.
Can I customise the widget's appearance?
Yes. Pass a theme object to createCheckout to override primaryColor, backgroundColor, textColor, borderRadius, and fontFamily. Dark mode is supported automatically via prefers-color-scheme.
Does the SDK have TypeScript support?
Yes. The npm package ships with full TypeScript type definitions for CheckoutOptions, PaymentConfirmation, PaymentError, and SpacePayTheme. Framework-specific packages (React, Vue) are also TypeScript-native.
Ready to add crypto checkout?
Full SDK reference, changelog, and a live playground are in the docs.
View JS SDK Docs