Skip to main content

​
HTTP Error Responses

All API errors return a JSON response with an error message. 
{
  "error": "The 'amount' field is required."
}

​
Status Codes

StatusDescriptionResolution
400Invalid request — malformed body, missing fields, or invalid valuesCheck that amount is a positive number and currency is provided
401Unauthorized — API key is missing, invalid, or revokedVerify your CUBEPAY_API_KEY environment variable
500Internal server errorRetry with exponential backoff
502Bad gateway — upstream payment service unavailableThe Grain API is temporarily unreachable. Retry shortly

​
SDK Errors

These errors are thrown by the client-side SDK service during payment execution.

​
CubePayClosedError

Thrown when the user closes the payment modal without completing the transaction. This is not a failure — it indicates the user chose to cancel. 
try {
  const result = await cubePayService.executePayment({ amount: 50, currency: "USD" });
} catch (error) {
  if (error.name === "CubePayClosedError") {
    // User cancelled — handle gracefully
    return;
  }
  throw error;
}

​
Initialization Errors

Error MessageCauseResolution
NEXT_PUBLIC_CUBEPAY_MERCHANT_ID is not setMissing merchant ID environment variableAdd the variable to your .env file
Missing CubePay container element with id 'cubepay-sdk-root'Mount point not in the DOMAdd <div id="cubepay-sdk-root" /> to your layout
Failed to load Cubist Pay SDK scriptSDK bundle not found or failed to loadVerify public/vendor/cubist-pay-client-sdk.umd.js exists
Failed to load Cubist Pay SDKwindow.CubePaySDK not available after script loadedCheck the browser console for script errors

​
Session Creation Errors

Error MessageCauseResolution
Amount must be a positive numberInvalid amount (zero, negative, NaN, Infinity)Validate the amount before calling executePayment
Failed to create payment sessionServer returned a non-2xx responseCheck server logs for the upstream API error
Payment service unavailableNetwork error or API timeoutRetry the request

​
Webhook Error Handling

Your webhook endpoint should always return 200 regardless of internal processing status: 
export async function POST(request: Request) {
  try {
    const body = await request.json();
    await processWebhook(body);
  } catch (error) {
    // Log but don't return an error status
    console.error("Webhook processing failed:", error);
  }

  // Always acknowledge receipt
  return NextResponse.json({ jsonrpc: "2.0", result: "ok" });
}
Returning a non-2xx status causes the payment service to retry webhook delivery. Always return 200 to prevent duplicate processing.

​
Debugging Tips

The SDK logs initialization steps and errors to the browser console. Open DevTools and filter for “CubePay” or “cubepay” messages.
Missing or incorrect environment variables are the most common cause of SDK failures. Double-check that NEXT_PUBLIC_CUBEPAY_MERCHANT_ID is set on the client and CUBEPAY_API_KEY is set on the server.
When CUBEPAY_API_KEY is absent and NODE_ENV is not production, the SDK returns mock data. This is useful for isolating whether an issue is in your code or the API integration.
Use the browser Network tab to inspect requests to /api/payment-sessions. Check that the request body is valid JSON and the response contains paymentSessionId and paymentSessionToken.