Skip to main content

​
Bearer Token Authentication

All server-side Grain API requests require your API key passed as a Bearer token in the Authorization header. 
curl -X POST https://api.pay.grain.inc/payment-sessions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": "50.00", "currency": "USD"}'

const response = await fetch("https://api.pay.grain.inc/payment-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CUBEPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "50.00", currency: "USD" }),
});

​
Credential Types

Grain uses two types of credentials for different contexts:
CredentialUseScope
API Key (CUBEPAY_API_KEY)Server-side onlyCreate payment sessions, authenticate with the Grain API
Merchant ID (NEXT_PUBLIC_CUBEPAY_MERCHANT_ID)Client-sideInitialize the SDK, identify your merchant account
Session Token (paymentSessionToken)Client-side, per sessionAuthorize SDK operations and session retrieval for a specific payment
Your API key is a server-side secret. Never expose it in client-side code, public repositories, or frontend bundles. If you suspect a key has been compromised, rotate it immediately in the Grain Dashboard.

​
Session Token Authentication

When you create a payment session, the API returns a paymentSessionToken. This short-lived token is scoped to a single session and used for:
  • Opening the SDK payment modal (sdk.open())
  • Retrieving session details (GET /api/payment-sessions)
// Server creates the session
const session = await createPaymentSession({ amount: "50.00", currency: "USD" });

// Client uses the session token
const result = await sdk.open({
  paymentSessionId: session.paymentSessionId,
  paymentSessionToken: session.paymentSessionToken,
});
Session tokens expire automatically and cannot be reused across sessions. Each POST /payment-sessions call returns a fresh token.

​
Rotate API Keys

1

Generate a new key

In the Grain Dashboard, go to Settings > API Keys and generate a new key.
2

Update your application

Replace CUBEPAY_API_KEY in your environment variables and deploy.
3

Revoke the old key

Once your application is running with the new key, revoke the old one in the dashboard.

​
Next Steps

Explore the full list of Endpoints available in the Payment SDK API.