Stripe

Overview

Stripe is a payment processing platform that enables your Emergent app to accept payments, manage subscriptions, and handle complex billing scenarios. This guide walks you through integrating Stripe into your project using Emergent's natural language interface.

Note

Stripe integration requires a Stripe account. You can create one at stripe.com and use test mode during development at no cost.

Prerequisites

Before integrating Stripe, ensure you have:

A Stripe account (test mode credentials work for development)
Your Stripe Publishable Key (starts with
```
pk_
```
)
Your Stripe Secret Key (starts with
```
sk_
```
)
A clear understanding of what payment flows your app needs (one-time payments, subscriptions, etc.)

Integration Steps

Tell Emergent about your payment needs

Describe your payment requirements in natural language. Be specific about what you want to accomplish:

Example prompts:

"Add Stripe payment processing. Users should be able to purchase credits for $10, $25, or $50."
"Integrate Stripe subscriptions with three tiers: Basic ($9/month), Pro ($29/month), and Enterprise ($99/month)."
"Add a checkout flow where users can buy individual products from a catalog."

Emergent's agents will generate the appropriate Stripe integration code, including client-side checkout components and server-side payment endpoints.

Use the managed Stripe sandbox or provide your own keys

Emergent provides a managed Stripe sandbox that automatically injects read-only

STRIPE_*

keys (

STRIPE_MODE

STRIPE_PUBLISHABLE_KEY

STRIPE_SECRET_KEY

STRIPE_WEBHOOK_SECRET

, and

STRIPE_ACCOUNT_ID

) into your project.

To use the managed sandbox, claim it and complete KYC. Going live is platform-handled after KYC.

Alternatively, you can unlink the sandbox and provide your own Stripe keys (BYOK).

Warning

Never commit secret keys to your codebase. Use Emergent's environment variable system to keep credentials secure.

The agent will configure the required credentials as secure environment variables accessible to your backend code.

Test the payment flow

Ask Emergent to test the integration:

Test the Stripe checkout flow

The agents will verify that:

Checkout sessions are created correctly
Payment confirmation is handled correctly
Success and cancellation redirects work as expected

Use Stripe's test card numbers to simulate successful and failed payments during testing.

Configure webhooks - BYOK only

If you're using the managed Stripe sandbox, webhook handling is already configured by Emergent. You don't need to manually configure a webhook in the Stripe Dashboard.

If you're using your own Stripe keys (BYOK), configure webhook handling for your integration.

Tell Emergent:

Set up Stripe webhooks to handle payment confirmation and subscription events

The agent will:

Create the webhook endpoint in your backend
Parse and verify Stripe webhook signatures
Update your database based on payment events
Provide the webhook URL to add in your Stripe Dashboard → Developers → Webhooks

Publish to production

Managed Stripe sandbox:
After KYC approval, Emergent handles the transition from sandbox to live Stripe credentials.

BYOK:
When you're ready to go live:

Update the webhook endpoint in your Stripe Dashboard to point to your production domain.
Ensure your custom domain is configured, if using one.
Provide your live Stripe keys after the first publish in the secrets panel(Preview → Manage → Secrets) and then re-publish

Common Payment Patterns

For simple product purchases or one-off charges:

Add a "Buy Now" button that charges $49.99 for premium access

Emergent will create a Stripe Checkout session that handles the entire payment flow, including success/cancel redirects.

For recurring billing:

Create a subscription system with monthly and annual billing options

The agents will set up Stripe subscription products, handle plan changes, and manage billing cycles.

For metered or consumption-based pricing:

Set up usage-based billing where users are charged $0.10 per API call

This creates a metered billing system that reports usage to Stripe and bills accordingly.

For simple no-code payment collection:

Generate a Stripe payment link for a $199 consulting package

Returns a shareable URL that you can use in emails, marketing pages, or chat messages.

Refining Your Integration

After the initial setup, you can refine the integration with natural language:

"Add a customer portal where users can manage their subscription and update payment methods"
"Show a payment history page with all past invoices"
"Add a discount code field to the checkout"
"Send a confirmation email after successful payment"
"Store customer payment info for future purchases"

Security Best Practices

Use webhooks

Don't rely solely on client-side success callbacks. Webhooks provide authoritative, server-verified payment confirmation.

Validate amounts server-side

Never trust payment amounts from the client. Always define prices and calculations in backend code.

Test failure scenarios

Use Stripe's test cards to simulate declined payments, insufficient funds, and fraud scenarios.

Handle idempotency

Stripe operations should be idempotent to prevent duplicate charges if requests are retried.

Troubleshooting

Issue	Solution
Payments succeed but webhooks aren't received	Verify your webhook URL is publicly accessible and correctly configured in the Stripe Dashboard. In Emergent, your app runs as a cloud preview with a public URL, you can use that URL directly for webhook testing rather than forwarding to localhost. Ask Emergent: `Set up webhook testing for Stripe`
Invalid API key errors	Double-check that you're using the correct key type (publishable keys for frontend, secret keys for backend) and that they match your Stripe account mode (test vs. live). Note that the managed sandbox injects read-only keys; to use your own, unlink the sandbox first.
Checkout session expires too quickly	Stripe Checkout sessions expire after 24 hours by default. If users abandon checkout frequently, consider storing session state and allowing them to resume, or create a new session on return.
Currency or region issues	Stripe supports 135+ currencies but availability varies by country. Tell Emergent which currencies and regions you need to support: `Configure Stripe to accept EUR and GBP in addition to USD`

Next Steps

Info

Stripe's pricing is pay-as-you-go with no monthly fees. You're charged a percentage of each successful transaction. Check Stripe's pricing page for current rates in your region.