Skip to main content

​
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. 
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:
1

Loads the SDK script

Injects /vendor/cubist-pay-client-sdk.umd.js into the page and waits for window.CubePaySDK to become available.
2

Initializes the SDK

Calls CubePaySDK.init() with your merchant ID, the container element, and optional configuration (RPC endpoints, theme variables).
3

Returns the SDK instance

The initialized SDK instance is cached. All subsequent calls reuse it without re-initialization.

​
Configuration Options

The SDK reads configuration from environment variables automatically. You can customize behavior through these settings:
OptionEnvironment VariableDescription
Merchant IDNEXT_PUBLIC_CUBEPAY_MERCHANT_IDRequired. 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: 
.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);
}
Override --tint and --system-blue to change the primary accent color of the payment modal to match your brand.

​
Next Steps

Create your first Payment Session.