Installation & Setup

Prerequisites

A Grain merchant account with a Merchant ID
A server-side API key for creating payment sessions
Node.js 18+ (for Next.js applications)

Get Your Credentials

Get your Merchant ID

Log in to the Grain Dashboard and navigate to Settings > API Keys. Copy your Merchant ID — this is used to initialize the client-side SDK.

Get your API key

From the same page, copy your API Key. This is your server-side secret used to create payment sessions.

Never expose your API key in client-side code. It should only be used in server-side route handlers or backend services.

Configure Environment Variables

Add the following to your .env file:

# Required
NEXT_PUBLIC_CUBEPAY_MERCHANT_ID=your-merchant-id    # Client-side: SDK initialization
CUBEPAY_API_KEY=your-api-key                         # Server-side: session creation

# Optional
CUBEPAY_API_HOST=https://api.pay.grain.inc           # API host (defaults to production)

Add the SDK Mount Point

The Payment SDK renders its payment modal inside a dedicated DOM element. Add this to your root layout:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <div id="cubepay-sdk-root" className="cubepay-sdk-root" />
      </body>
    </html>
  );
}

The SDK creates a Shadow DOM inside this element, so its styles are fully isolated from your application. No CSS conflicts.

Load the SDK Bundle

The client-side SDK is distributed as a UMD bundle. Place it in your public directory:

public/
  vendor/
    cubist-pay-client-sdk.umd.js

The SDK service loads this script lazily on first use — no manual script tags needed.

Environment Comparison

Feature	Sandbox	Production
Blockchain networks	Testnets (Sepolia)	Mainnets (Ethereum, Base)
Real funds	No	Yes
Webhooks	Supported	Supported
Settlement	Simulated	Real on-chain settlement
API host	`api.sandbox.pay.grain.inc`	`api.pay.grain.inc`

Next Steps

Proceed to Initialize the SDK to set up the SDK service and process your first payment.

Home

Get Started

Payment SDK

Grain Dashboard

Support & Resources

Installation & Setup

Prerequisites

Get Your Credentials

Configure Environment Variables

Add the SDK Mount Point

Load the SDK Bundle

Environment Comparison

Next Steps

​Prerequisites

​Get Your Credentials

​Configure Environment Variables

​Add the SDK Mount Point

​Load the SDK Bundle

​Environment Comparison

​Next Steps

Prerequisites

Get Your Credentials

Configure Environment Variables

Add the SDK Mount Point

Load the SDK Bundle

Environment Comparison

Next Steps