superun & Prompt.to.design Documentation

Overview

Stripe is a payment platform for accepting money online. With superun’s Stripe integration, add payments to your app — one-time checkout, subscriptions, and marketplace flows.

⚠️ Important： For WeChat Pay or Alipay, use the dedicated guides — not Stripe. Stripe fits international payments (cards, digital wallets, etc.). For China-local methods, use the dedicated payment docs.

You can set up Stripe entirely through chat. Chat-driven setup (recommended) Connect superun Cloud (or Supabase), set Stripe credentials under Build → Skill Library → Stripe (see below), then describe what you need in chat: “Add three subscription tiers: Basic $9/month, Pro$ 29/month, Enterprise $99/month"* *"Create one-time checkout for my ebook at$ 29” “Add a payment form on my product page” superun generates checkout UI, database tables, and payment logic — no manual code or webhooks unless you ask.

For one-time sales, ensure cart or product pages work.
- For subscriptions, enable auth on superun Cloud (or Supabase) so Stripe customers link to each user id.

Key points

Use the chat-driven flow for subscriptions and one-time payments.
Never paste Stripe secret keys in chat. Set STRIPE_API_KEY under Build → Skill Library → Stripe.
Webhooks are optional. If you use them, set STRIPE_WEBHOOK_SECRET so superun can verify events.
Debug in browser console → Network/Errors, superun Cloud → Logs, and Stripe Dashboard → Logs.
Always test in Stripe test mode before going live.

What is Stripe

Stripe provides payment APIs and tools:

Payment processing： Cards, digital wallets, local methods (Note： WeChat Pay and Alipay use dedicated guides)
Subscriptions： Recurring billing and subscription management
Marketplace： Multi-party payments and marketplace features
Connect： Platform payments for marketplaces
Billing： Invoices and billing management
Tax： Automatic tax calculation and compliance

💡 Tip： For WeChat Pay or Alipay, see the dedicated integration guides.

Key benefits

Global reach： Accept payments worldwide
Many payment methods： Cards, wallets, bank transfers, and more
Developer-friendly： Well-documented APIs and strong DX
Compliance： PCI DSS handling for sensitive payment data
Real-time： Instant processing and webhook notifications

Requirements

Before integrating Stripe:

Project must connect to superun Cloud (or Supabase). Learn about superun Cloud or Supabase integration
A Stripe account with products configured (for subscriptions)
A working frontend：
For one-off products, cart and checkout must work.
For subscriptions, login and pricing tiers.

Please note Stripe does not work in Preview alone. Deploy the project to test. Use Stripe test mode when trying payments. Test card: 4242 4242 4242 4242, any future expiry, any 3-digit CVC.

Stripe setup (no-code chat flow)

superun generates Stripe logic for you. After STRIPE_API_KEY (and optional STRIPE_WEBHOOK_SECRET) are set under Build → Skill Library → Stripe and the project is on superun Cloud (or Supabase), describe needs in chat — no manual coding.

Step 1: Prepare your project

superun Cloud (or Supabase) connected
Stripe keys set under Build → Skill Library → Stripe
(Optional) Price or product IDs from the Stripe Dashboard

Step 2: Describe payments in chat

Examples:“Create one-time checkout for my ‘Digital course’ at $29"* *"Set up an annual Premium plan at$ 99 tied to each user ID” “Add three tiers: Basic $9/mo, Pro$ 29/mo, Enterprise $99/mo” “Create a payment form on my product page”

Step 3: Review and apply

superun scaffolds payment components, database tables (with superun Cloud), and UI tied to user IDs. Review preview, then click Apply to deploy.

Subscriptions should link to authenticated user id in superun Cloud (or Supabase) for secure, role-based access.

Getting started

1. Create a Stripe account

Go to Stripe.com and sign up
Complete account setup
Verify business details
Activate the account (test mode is available immediately)

2. Get your API keys

In the Stripe Dashboard:

Go to Developers → API keys
Copy your publishable key (pk_test_ or pk_live_)
Copy your secret key (sk_test_ or sk_live_)
Keep secrets safe — never expose them in client code

Important security noticeNever paste your secret key into superun chat. Store it under Build → Skill Library → Stripe instead.

3. Configure Stripe in superun

Two ways to enable Stripe:

Option 1: Skill Library (recommended)

In your project, open Build
Open Skill Library and select Stripe
Paste your Stripe Secret Key in STRIPE_API_KEY (e.g. sk_test_... or sk_live_...)
(Optional) Paste Webhook signing secret in STRIPE_WEBHOOK_SECRET (e.g. whsec_...) if you use webhooks
Click Save Changes and wait until Stripe shows as enabled

superun configures Stripe from these credentials.

Option 2: Enable via chat

Ask superun in chat:

Enable Stripe payment processing for my project

Or:

Add Stripe integration with test keys

superun walks you through setup. When prompted, add keys via Build → Skill Library.

Manual payment setup (advanced)

Recommended： Use the chat-driven flow above for the simplest path. The sections below are for advanced users who implement payments manually or customize generated code.

Install the Stripe SDK

Enabling Stripe in superun includes the SDK; you can also install manually:

npm install @stripe/stripe-js

Initialize Stripe

import { loadStripe } from '@stripe/stripe-js';

// Initialize Stripe
const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

One-time payments

Create a PaymentIntent

// Server-side: Create payment intent
const createPaymentIntent = async (amount, currency = 'usd') => {
  const response = await fetch('/api/create-payment-intent', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: amount * 100, // Amount in cents
      currency,
    }),
  });

  const { clientSecret } = await response.json();
  return clientSecret;
};

Process payment

import { Elements, CardElement, useStripe, useElements } from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (event) => {
    event.preventDefault();

    if (!stripe || !elements) {
      return;
    }

    setLoading(true);

    // Create payment intent
    const clientSecret = await createPaymentIntent(50); // $50.00

    // Confirm payment
    const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
      payment_method: {
        card: elements.getElement(CardElement),
      },
    });

    if (error) {
      console.error('Payment failed:', error);
    } else if (paymentIntent.status === 'succeeded') {
      console.log('Payment succeeded:', paymentIntent);
      // Handle successful payment
    }

    setLoading(false);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement
        options={{
          style: {
            base: {
              fontSize: '16px',
              color: '#424770',
              '::placeholder': {
                color: '#aab7c4',
              },
            },
          },
        }}
      />
      <button disabled={!stripe || loading}>
        {loading ? 'Processing...' : 'Pay $50.00'}
      </button>
    </form>
  );
};

// Wrap your app with Elements
const App = () => {
  return (
    <Elements stripe={stripePromise}>
      <CheckoutForm />
    </Elements>
  );
};

Subscriptions

Create a subscription

// Create a subscription
const createSubscription = async (priceId, customerId) => {
  const response = await fetch('/api/create-subscription', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId,
      customerId,
    }),
  });

  const { subscription } = await response.json();
  return subscription;
};

Subscription management

// Cancel a subscription
const cancelSubscription = async (subscriptionId) => {
  const response = await fetch('/api/cancel-subscription', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId,
    }),
  });

  const { subscription } = await response.json();
  return subscription;
};

// Update subscription
const updateSubscription = async (subscriptionId, newPriceId) => {
  const response = await fetch('/api/update-subscription', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId,
      newPriceId,
    }),
  });

  const { subscription } = await response.json();
  return subscription;
};

Customer management

Create a customer

// Create a customer
const createCustomer = async (email, name) => {
  const response = await fetch('/api/create-customer', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email,
      name,
    }),
  });

  const { customer } = await response.json();
  return customer;
};

Customer portal

// Create customer portal session
const createPortalSession = async (customerId) => {
  const response = await fetch('/api/create-portal-session', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId,
    }),
  });

  const { url } = await response.json();
  return url;
};

// Redirect to customer portal
const handleManageSubscription = async () => {
  const url = await createPortalSession(customerId);
  window.location.href = url;
};

Advanced integration: Webhooks and superun Cloud

For complex payment setups such as subscriptions and role-based access, superun recommends superun Cloud (or Supabase) to handle Stripe securely — webhooks, subscription state, and access by payment tier.

For basic payments, webhooks are optional. superun can process payments without them; webhooks improve realtime updates and subscription management.

Set up webhooks

Step 1: Connect superun Cloud

Getting started is straightforward:

Go to Build → Skill Library
Find superun Cloud and click Enable
Follow the setup flow for your cloud project
Once connected, superun Cloud supports secure payments, subscriptions, webhooks, customer storage, and error handling.

Step 2: Get the webhook endpoint URL

After superun generates a webhook handler, get the endpoint URL from:

superun Cloud → Functions → your webhook function
Or ask in chat: “What is my Stripe webhook endpoint URL?”

Step 3: Configure webhooks in Stripe Dashboard

Go to Stripe Dashboard → Developers → Webhooks → Add endpoint
Enter the webhook URL from step 2
Select events to listen for:

payment_intent.succeeded
payment_intent.payment_failed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted

Copy the webhook signing secret (whsec_...)

Step 4: Store the webhook secret securely

Save the signing secret in superun Cloud environment variables, or ask superun in chat to configure it safely.

If you are unsure how to name the secret, ask superun in free consultation mode.

Handle webhooks

// webhook handler
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).end();
  }

  const sig = req.headers['stripe-signature'];
  const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    console.error('Webhook signature verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('Payment succeeded:', paymentIntent.id);
      // Update your database, send confirmation email, etc.
      break;

    case 'customer.subscription.created':
      const subscription = event.data.object;
      console.log('Subscription created:', subscription.id);
      // Activate user's premium features
      break;

    case 'customer.subscription.updated':
      const updatedSubscription = event.data.object;
      console.log('Subscription updated:', updatedSubscription.id);
      // Update subscription status
      break;

    case 'customer.subscription.deleted':
      const deletedSubscription = event.data.object;
      console.log('Subscription cancelled:', deletedSubscription.id);
      // Deactivate user's premium features
      break;

    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  res.json({ received: true });
}

Advanced features

Payment methods

// Save payment method for future use
const savePaymentMethod = async (customerId, paymentMethodId) => {
  const response = await fetch('/api/save-payment-method', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId,
      paymentMethodId,
    }),
  });

  const { paymentMethod } = await response.json();
  return paymentMethod;
};

// List customer's payment methods
const getPaymentMethods = async (customerId) => {
  const response = await fetch(`/api/payment-methods/${customerId}`);
  const { paymentMethods } = await response.json();
  return paymentMethods;
};

Invoices

// Create an invoice
const createInvoice = async (customerId, items) => {
  const response = await fetch('/api/create-invoice', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId,
      items,
    }),
  });

  const { invoice } = await response.json();
  return invoice;
};

// Send invoice to customer
const sendInvoice = async (invoiceId) => {
  const response = await fetch('/api/send-invoice', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      invoiceId,
    }),
  });

  const { invoice } = await response.json();
  return invoice;
};

Marketplace payments

// Create a connected account
const createConnectedAccount = async (email, country) => {
  const response = await fetch('/api/create-connected-account', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email,
      country,
    }),
  });

  const { account } = await response.json();
  return account;
};

// Create account link for onboarding
const createAccountLink = async (accountId) => {
  const response = await fetch('/api/create-account-link', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      accountId,
    }),
  });

  const { url } = await response.json();
  return url;
};

Test your integration

Test mode setup

Use Stripe test mode before going live
Switch to test mode in the Stripe Dashboard (toggle top-right)
Use test API keys (pk_test_ and sk_test_)

Test cards

Use these test card numbers:

Success： 4242 4242 4242 4242
- Any future expiry (e.g. 12/25)
- Any 3-digit CVC (e.g. 123)
Declined： 4000 0000 0000 0002
Requires authentication： 4000 0025 0000 3155
Insufficient funds： 4000 0000 0000 9995

Important： Stripe integration does not work in Preview alone. Deploy your app to test.

Test scenarios

// Test different payment scenarios
const testCards = {
  success: '4242424242424242',
  declined: '4000000000000002',
  requiresAuth: '4000002500003155',
  insufficientFunds: '4000000000009995',
};

// Test webhook events
const testWebhook = async () => {
  const response = await fetch('/api/test-webhook', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      eventType: 'payment_intent.succeeded',
      data: { /* test data */ },
    }),
  });

  const result = await response.json();
  return result;
};

Security best practices

Environment variables

# .env.local
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Server-side validation

// Always validate on the server
const validatePayment = async (paymentIntentId) => {
  const paymentIntent = await stripe.paymentIntents.retrieve(paymentIntentId);
  
  if (paymentIntent.status !== 'succeeded') {
    throw new Error('Payment not completed');
  }
  
  return paymentIntent;
};

Webhook security

// Verify webhook signatures
const verifyWebhook = (payload, signature, secret) => {
  try {
    const event = stripe.webhooks.constructEvent(payload, signature, secret);
    return event;
  } catch (err) {
    throw new Error('Invalid webhook signature');
  }
};

Common patterns

Payment form component

const PaymentForm = ({ amount, onSuccess, onError }) => {
  const stripe = useStripe();
  const elements = useElements();
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (event) => {
    event.preventDefault();

    if (!stripe || !elements) {
      return;
    }

    setLoading(true);

    try {
      const { error, paymentIntent } = await stripe.confirmCardPayment(
        clientSecret,
        {
          payment_method: {
            card: elements.getElement(CardElement),
          },
        }
      );

      if (error) {
        onError(error);
      } else if (paymentIntent.status === 'succeeded') {
        onSuccess(paymentIntent);
      }
    } catch (err) {
      onError(err);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement />
      <button disabled={!stripe || loading}>
        {loading ? 'Processing...' : `Pay ${amount}`}
      </button>
    </form>
  );
};

Subscription status component

const SubscriptionStatus = ({ customerId }) => {
  const [subscription, setSubscription] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchSubscription = async () => {
      try {
        const response = await fetch(`/api/subscription/${customerId}`);
        const data = await response.json();
        setSubscription(data.subscription);
      } catch (error) {
        console.error('Error fetching subscription:', error);
      } finally {
        setLoading(false);
      }
    };

    fetchSubscription();
  }, [customerId]);

  if (loading) return <div>Loading...</div>;

  if (!subscription) return <div>No active subscription</div>;

  return (
    <div>
      <h3>Subscription Status: {subscription.status}</h3>
      <p>Current Period: {subscription.current_period_start} - {subscription.current_period_end}</p>
      <p>Amount: ${subscription.items.data[0].price.unit_amount / 100}</p>
    </div>
  );
};

Debugging and troubleshooting

Check console logs

Step 1

Open Developer Tools (Chrome: right-click → Inspect → Console).

Step 2

Look for errors and payment event logs.

Step 3

Copy error messages and ask superun in chat for help debugging.

View superun Cloud logs

Step 1

Go to Build → Skill Library → superun Cloud

Step 2

Open Logs or Functions → Logs

Step 3

Check webhook errors and payment processing issues.

Verify webhook events in Stripe

Step 1

Go to Stripe Dashboard → Developers → Webhooks

Step 2

Click your webhook endpoint

Step 3

Open Events to confirm Stripe is sending data correctly.

Use superun free consultation

Step 1

Switch to free consultation and ask follow-up questions.

Step 2

Describe the issue step by step: “My payment form does not show” “Subscription was not created” “Webhook is not working”

Step 3

Use the rubber duck approach — explain the problem aloud to clarify it.

Common issues

Q: Payment failed with “Your card was declined” A: This may be because:

Using test cards in live mode (or the reverse)
Insufficient funds (use test card 4242 4242 4242 4242)
Card not enabled for online payments
Incorrect card details
Bank blocked the transaction

Q: Webhook not received A: Check:

Webhook URL is reachable from the internet
Endpoint returns HTTP 200
Webhook signing secret is correct
Correct events selected in Stripe Dashboard
You are testing on a deployed build (not Preview only)

Q: Test payment does not work A: Ensure:

Test API keys (pk_test_ and sk_test_)
Correct test card (4242 4242 4242 4242)
Amount in cents (e.g. $10.00 = 1000)
App is deployed (Stripe does not work in Preview alone)
Stripe test mode is on in the Dashboard

Q: Subscription webhook did not fire A: Verify:

Subscription was created successfully
Webhook events include subscription types
Endpoint handles events correctly
Webhook secret is stored correctly in superun Cloud

Need help?

See our FAQ for common Stripe integration issues and troubleshooting tips.

​Overview

​Key points

​What is Stripe

​Key benefits

​Requirements

​Stripe setup (no-code chat flow)

​Getting started

​1. Create a Stripe account

​2. Get your API keys

​3. Configure Stripe in superun

​Option 1: Skill Library (recommended)

​Option 2: Enable via chat

​Manual payment setup (advanced)

​Install the Stripe SDK

​Initialize Stripe

​One-time payments

​Create a PaymentIntent

​Process payment

​Subscriptions

​Create a subscription

​Subscription management

​Customer management

​Create a customer

​Customer portal

​Advanced integration: Webhooks and superun Cloud

​Set up webhooks

​Handle webhooks

​Advanced features

​Payment methods

​Invoices

​Marketplace payments

​Test your integration

​Test mode setup

​Test cards

​Test scenarios

​Security best practices

​Environment variables

​Server-side validation

​Webhook security

​Common patterns

​Payment form component

​Subscription status component

​Debugging and troubleshooting

​Common issues

Need help?

Overview

Key points

What is Stripe

Key benefits

Requirements

Stripe setup (no-code chat flow)

Getting started

1. Create a Stripe account

2. Get your API keys

3. Configure Stripe in superun

Option 1: Skill Library (recommended)

Option 2: Enable via chat

Manual payment setup (advanced)

Install the Stripe SDK

Initialize Stripe

One-time payments

Create a PaymentIntent

Process payment

Subscriptions

Create a subscription

Subscription management

Customer management

Create a customer

Customer portal

Advanced integration: Webhooks and superun Cloud

Set up webhooks

Handle webhooks

Advanced features

Payment methods

Invoices

Marketplace payments

Test your integration

Test mode setup

Test cards

Test scenarios

Security best practices

Environment variables

Server-side validation

Webhook security

Common patterns

Payment form component

Subscription status component

Debugging and troubleshooting

Common issues