Skip to main content

​
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

1

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.
2

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

FeatureSandboxProduction
Blockchain networksTestnets (Sepolia)Mainnets (Ethereum, Base)
Real fundsNoYes
WebhooksSupportedSupported
SettlementSimulatedReal on-chain settlement
API hostapi.sandbox.pay.grain.incapi.pay.grain.inc

​
Next Steps

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