Skip to main content

​
SDK Integration

The SpacePay SDK provides a simple way to integrate payments with minimal code and built-in functionality.

​
Installation

yarn add @spacepay/client-sdk
Requirements: Node.js 18+ or modern browsers with Fetch API support.

​
Basic Usage

import { createBackendClient } from "@spacepay/client-sdk/backend";

// Initialize the client
const client = createBackendClient({
  publicKey: "pk_test_your_public_key",
  secretKey: "sk_test_your_secret_key", // never expose this on the frontend
});

// Create a payment
async function createPayment() {
  try {
    const payment = await client.createPayment({
      orderId: "order_123",
      amount: 250, // 250 cents = $2.50 (API minimum for fixed payments)
      currency: "USD",
      redirectUrl: "https://merchant.example.com/checkout/success", // Optional
      customMetadata: '{"cartId":"abc123","promo":"SUMMER24"}', // Optional
    });

    console.log("Payment URL:", payment.paymentUrl);
    console.log("Payment ID:", payment.paymentId);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

// Get payment details
async function getPayment(paymentId: string) {
  try {
    const payment = await client.getPaymentDetails(paymentId);
    console.log("Payment status:", payment.status);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

​
SDK Features

SDK Benefits

  • Lightweight: No heavy dependencies, minimal bundle size
  • Type-safe: Full TypeScript support with comprehensive type definitions
  • Universal: Works in Node.js 18+ and modern browsers
  • Modern: Uses native fetch API and modern JavaScript features
  • Robust: Built-in error handling, timeout management, and retry logic

​
Client Configuration

You can configure the client with additional options: 
const client = createBackendClient({
  publicKey: "pk_test_your_public_key",
  secretKey: "sk_test_your_secret_key",
  apiBaseUrl: "https://api.spacepay.co.uk", // optional, shown for reference
  timeoutMs: 30000, // optional, default: 30000
});

​
Payment Status Values

The SDK returns payment statuses with the following values:
  • pending - Payment created, waiting for funds
  • processing - Payment detected, confirming on blockchain
  • completed - Payment confirmed and settled
  • failed - Payment failed or rejected
  • expired - Payment expired without completion
  • cancelled - Payment was cancelled

​
Error Handling

The SDK provides structured error handling: 
import { ApiError } from "@spacepay/client-sdk";

try {
  const payment = await client.createPayment({
    orderId: "order_123",
    amount: 250,
    currency: "USD",
  });
} catch (error) {
  if (error instanceof ApiError) {
    console.error("API Error:", error.message);
    console.error("Status:", error.status);
    console.error("Request ID:", error.requestId);
  } else {
    console.error("Unexpected error:", error);
  }
}

​
Next Steps

API Integration

For maximum control, integrate directly with SpacePay’s REST APIs.

Webhooks

Set up real-time payment notifications.

Testing

Learn about test environments and scenarios.

Support

Get help with your integration from our support team.