> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spacepay.solutions/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Integration

> Quick setup and simplified development with SpacePay's official SDK

# SDK Integration

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

For full SDK package details, see [SpacePay Client SDK on npm](https://www.npmjs.com/package/@spacepay/client-sdk).

## Installation

```bash theme={null}
yarn add @spacepay/client-sdk
```

<Note>
  **Requirements**: Node.js 18+ or modern browsers with Fetch API support.
</Note>

## Basic Usage

```typescript theme={null}
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

<Card title="SDK Benefits" icon="check">
  * **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
</Card>

## Client Configuration

You can configure the client with additional options:

```typescript theme={null}
const client = createBackendClient({
  publicKey: "pk_test_your_public_key",
  secretKey: "sk_test_your_secret_key",
  apiBaseUrl: "https://api.spacepay.solutions", // 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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="API Integration" icon="terminal" href="/developer-docs/api-integration">
    For maximum control, integrate directly with SpacePay's REST APIs.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-docs/webhooks">
    Set up real-time payment notifications.
  </Card>

  <Card title="Testing" icon="flask" href="/developer-docs/testing">
    Learn about test environments and scenarios.
  </Card>

  <Card title="Support" icon="question-circle" href="/trust-operations/support">
    Get help with your integration from our support team.
  </Card>
</CardGroup>