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

# Initialize the SDK

> Set up the Payment SDK service in your application

## SDK Service

The Payment SDK uses a singleton service that handles script loading, initialization, and payment execution. Import and use it directly in your components.

```typescript theme={null}
import { cubePayService } from "@/services/cubepay-sdk";
```

The service:

* **Lazy-loads** the SDK bundle on first use (no upfront script loading)
* **Initializes once** and reuses the same instance across your app
* Creates a **Shadow DOM** inside the `#cubepay-sdk-root` element for style isolation

## Initialization Flow

When you call `executePayment()` for the first time, the service automatically:

<Steps>
  <Step title="Loads the SDK script">
    Injects `/vendor/cubist-pay-client-sdk.umd.js` into the page and waits for `window.CubePaySDK` to become available.
  </Step>

  <Step title="Initializes the SDK">
    Calls `CubePaySDK.init()` with your merchant ID, the container element, and optional configuration (RPC endpoints, theme variables).
  </Step>

  <Step title="Returns the SDK instance">
    The initialized SDK instance is cached. All subsequent calls reuse it without re-initialization.
  </Step>
</Steps>

## Configuration Options

The SDK reads configuration from environment variables automatically. You can customize behavior through these settings:

| Option      | Environment Variable              | Description                                    |
| ----------- | --------------------------------- | ---------------------------------------------- |
| Merchant ID | `NEXT_PUBLIC_CUBEPAY_MERCHANT_ID` | **Required.** Identifies your merchant account |

## Theme Customization

The SDK applies CSS custom properties to the payment modal. Override these in your `#cubepay-sdk-root` element to match your brand:

```css theme={null}
.cubepay-sdk-root {
  --tint: #2563eb;
  --background: #ffffff;
  --background-secondary: #f8fafc;
  --background-tertiary: #f1f5f9;
  --label: #0f172a;
  --label-secondary: #475569;
  --label-tertiary: #64748b;
  --label-quaternary: #94a3b8;
  --system-blue: #2563eb;
  --separator: rgba(15, 23, 42, 0.08);
}
```

<Tip>
  Override `--tint` and `--system-blue` to change the primary accent color of the payment modal to match your brand.
</Tip>

## Next Steps

Create your first [Payment Session](/payment-sdk/integration-guide/create-payment-session).