Payment Setup & Configuration

Dev Kit for AI provides built-in Stripe integration for subscription-based monetization of your AI-powered applications. This guide covers the complete setup process from Stripe account creation to production deployment.

Payment Architecture Overview

The payment system follows a secure, project-scoped design where each project maintains its own Stripe configuration:

Key Design Principles

Project-Scoped Credentials

Each project stores its own Stripe API keys separately, enabling different Stripe accounts per project or shared accounts with proper isolation.

Test/Live Mode Separation

Maintain separate credentials for test and live environments, with mode-specific webhook endpoints for proper event routing.

Encrypted Storage

All Stripe credentials are encrypted at rest in the Cloud API database—never exposed in logs or API responses.

Webhook Verification

All incoming webhooks are verified using Stripe’s signature verification to prevent spoofed events.

Prerequisites

Before configuring payments, ensure you have:

Active Stripe Account

Create a Stripe account if you don’t have one. You can use the same account for multiple projects or create separate accounts per project.

Dev Kit Project

A project created in Cloud Admin with at least one API key.

Stripe Products & Prices

Create your subscription products and prices in the Stripe Dashboard. Note the Price IDs (e.g., price_1234...) for use in checkout sessions.

Obtaining Stripe Credentials

API Keys

Navigate to the Stripe API Keys page to find your credentials:

Test Mode
Live Mode

Test mode keys are prefixed with sk_test_ and pk_test_. Use these during development and testing.

Test mode processes simulated transactions only. No real payments are made.

Live mode keys are prefixed with sk_live_ and pk_live_. Use these for production payments.

Live mode processes real transactions. Handle these credentials with extreme care.

You’ll need:

Secret Key (sk_test_... or sk_live_...) — Used server-side for API calls. Never expose this in client code.
Publishable Key (pk_test_... or pk_live_...) — Used client-side for Stripe.js (optional, if implementing custom checkout UI).

Webhook Signing Secret

Webhook secrets are generated when you create a webhook endpoint in Stripe. You’ll get these from Cloud Admin after configuring your project (the webhook URLs are provided automatically).

Configuring Payments in Cloud Admin

Step 1: Navigate to Project Payments

Open your project in Cloud Admin and navigate to the Payments tab: (((REPLACE_THIS_WITH_IMAGE: console-project-payments-tab-overview.png: Cloud Admin project payments tab showing configuration options and empty state)))

Step 2: Add Stripe Credentials

Click Configure Payments to open the configuration form: (((REPLACE_THIS_WITH_IMAGE: console-payment-config-form.png: Payment configuration form with fields for Stripe API keys and webhook secrets)))

Select Mode

Choose Test Mode initially to safely test your integration without processing real payments.

Enter Secret Key

Paste your Stripe Secret Key (sk_test_... for test mode). This is used for all server-side Stripe operations.

Validate Credentials

Click Validate to verify your API key works. The system makes a test API call to Stripe to confirm validity.

Save Configuration

Once validated, click Save to store your encrypted credentials.

Step 3: Configure Webhook Endpoints

After saving your Stripe configuration, Cloud Admin displays your webhook URLs:

Test Mode: https://api.devkit4ai.com/api/v1/payments/stripe/webhooks/{project_id}/test
Live Mode: https://api.devkit4ai.com/api/v1/payments/stripe/webhooks/{project_id}/live

Alternative domain: https://api.vibecoding.ad/api/v1/payments/stripe/webhooks/{project_id}/{mode}

Copy the appropriate URL and add it to your Stripe webhook configuration:

Open Stripe Webhooks

Navigate to Stripe Webhooks and click Add endpoint.

Enter Endpoint URL

Paste the webhook URL from Cloud Admin.

Select Events

Choose the events to listen for. Recommended events:

checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed
charge.refunded

Copy Signing Secret

After creating the endpoint, copy the Signing Secret (whsec_...) and add it to your Cloud Admin payment configuration.

Credential Validation

The Cloud API provides automatic credential validation to ensure your Stripe configuration is correct before going live:

Validation Checks

The validation endpoint performs these checks:

Check	Description
API Key Format	Verifies the key matches Stripe key format (`sk_test_` or `sk_live_`)
Authentication	Confirms the key authenticates successfully with Stripe
Permissions	Verifies the key has necessary permissions for payment operations

If validation fails, double-check that you copied the complete key including the sk_ prefix.

Local Development with Stripe CLI

For local development and testing, use the Stripe CLI to forward webhook events to your local environment:

Install Stripe CLI

macOS
Linux
Windows

brew install stripe/stripe-cli/stripe

# Download and extract
curl -L https://github.com/stripe/stripe-cli/releases/download/v1.19.0/stripe_1.19.0_linux_x86_64.tar.gz | tar xz
sudo mv stripe /usr/local/bin/

# Using scoop
scoop install stripe

# Login to Stripe (opens browser)
stripe login

# Forward webhooks to Cloud API (test mode)
stripe listen --forward-to https://api.devkit4ai.com/api/v1/payments/stripe/webhooks/{project_id}/test

Replace {project_id} with your actual project UUID from Cloud Admin. Alternative API domain: https://api.vibecoding.ad/...

The CLI will display a webhook signing secret (whsec_...). Use this temporary secret in your local development environment, or configure it in Cloud Admin for testing.

Trigger Test Events

# Trigger a checkout completion event
stripe trigger checkout.session.completed

# Trigger a subscription creation
stripe trigger customer.subscription.created

# Trigger a payment success
stripe trigger invoice.paid

Security Best Practices

Never Expose Secret Keys

Stripe secret keys (sk_*) should only be stored in Cloud Admin and used server-side. Never include them in:

Client-side JavaScript
Mobile app code
Git repositories
Logs or error messages

Use Test Mode for Development

Always use test mode (sk_test_*) during development. Switch to live mode only after thorough testing. Test mode:

Processes simulated transactions
Uses test card numbers
Generates test webhook events

Verify Webhook Signatures

Cloud API automatically verifies all incoming webhooks using the signing secret. This prevents:

Replay attacks
Spoofed events
Unauthorized subscription modifications

Rotate Credentials Regularly

Periodically rotate your Stripe API keys and webhook secrets, especially if you suspect compromise. Update them in Cloud Admin immediately.

Configuration API Reference

For programmatic configuration, Cloud Admin uses these Cloud API endpoints:

Get Configuration

Retrieve current Stripe configuration status for a project

Update Configuration

Create or update Stripe credentials for a project

Delete Configuration

Deactivate Stripe configuration for a project

Get Webhook URLs

Get the webhook endpoint URLs for Stripe dashboard

Validate Credentials

Test Stripe API credentials before saving

Switching to Live Mode

When you’re ready to accept real payments:

Complete Test Mode Verification

Ensure all payment flows work correctly in test mode:

New subscriptions
Plan changes (upgrade/downgrade)
Cancellations
Webhook events processing

Add Live Credentials

In Cloud Admin, switch to Live Mode and add your live Stripe API key (sk_live_...).

Configure Live Webhook

Create a new webhook endpoint in Stripe for your live mode URL and add the signing secret to Cloud Admin.

Verify Live Configuration

Use the validation feature to confirm your live credentials work correctly.

After switching to live mode, all transactions process real payments. Double-check your pricing configuration in Stripe before going live.

Next Steps

Subscription Management

Learn about the complete subscription lifecycle and billing workflows

Monitor Payments

View subscriptions and transactions in Cloud Admin

End-User Billing

Implement billing UI components in your Starter Kit application

Payments API Reference

Complete API documentation for all payment endpoints

Welcome

Core Concepts

Features

Payment Setup & Configuration

Payment Architecture Overview

Key Design Principles

Project-Scoped Credentials

Test/Live Mode Separation

Encrypted Storage

Webhook Verification

Prerequisites

Obtaining Stripe Credentials

API Keys

Webhook Signing Secret

Configuring Payments in Cloud Admin

Step 1: Navigate to Project Payments

Step 2: Add Stripe Credentials

Step 3: Configure Webhook Endpoints

Credential Validation

Validation Checks

Local Development with Stripe CLI

Install Stripe CLI

Trigger Test Events

Security Best Practices

Configuration API Reference

Get Configuration

Update Configuration

Delete Configuration

Get Webhook URLs

Validate Credentials

Switching to Live Mode

Next Steps

Subscription Management

Monitor Payments

End-User Billing

Payments API Reference

Welcome

Core Concepts

Features

​Payment Architecture Overview

​Key Design Principles

Project-Scoped Credentials

Test/Live Mode Separation

Encrypted Storage

Webhook Verification

​Prerequisites

​Obtaining Stripe Credentials

​API Keys

​Webhook Signing Secret

​Configuring Payments in Cloud Admin

​Step 1: Navigate to Project Payments

​Step 2: Add Stripe Credentials

​Step 3: Configure Webhook Endpoints

​Credential Validation

​Validation Checks

​Local Development with Stripe CLI

​Install Stripe CLI

​Login and Forward Webhooks

​Trigger Test Events

​Security Best Practices

​Configuration API Reference

Get Configuration

Update Configuration

Delete Configuration

Get Webhook URLs

Validate Credentials

​Switching to Live Mode

​Next Steps

Subscription Management

Monitor Payments

End-User Billing

Payments API Reference

Payment Architecture Overview

Key Design Principles

Prerequisites

Obtaining Stripe Credentials

API Keys

Webhook Signing Secret

Configuring Payments in Cloud Admin

Step 1: Navigate to Project Payments

Step 2: Add Stripe Credentials

Step 3: Configure Webhook Endpoints

Credential Validation

Validation Checks

Local Development with Stripe CLI

Install Stripe CLI

Login and Forward Webhooks

Trigger Test Events

Security Best Practices

Configuration API Reference

Switching to Live Mode

Next Steps