Skip to main content
The Payments API enables developers to integrate Stripe-powered payment processing into their projects. This includes subscription management, one-time payments, customer portals, and comprehensive payment analytics.

​
Architecture Overview

The payment system is designed with a multi-tenant architecture where each project can have its own Stripe configuration:

​
API Groups

​
Payments (Aggregated)

Cross-project payment data for developers to view all subscriptions and transactions across their projects.
EndpointMethodDescription
/api/v1/payments/subscriptionsGETList all subscriptions across projects
/api/v1/payments/transactionsGETList all payment transactions across projects
/api/v1/payments/projectsGETList projects with payment configuration status
/api/v1/payments/statsGETGet aggregated payment statistics

​
Stripe Configuration

Developer-facing endpoints for configuring Stripe credentials per project.
EndpointMethodDescription
/api/v1/payments/stripe/projects/{project_id}/configGETGet Stripe configuration
/api/v1/payments/stripe/projects/{project_id}/configPUTCreate or update Stripe configuration
/api/v1/payments/stripe/projects/{project_id}/configDELETEDeactivate Stripe configuration
/api/v1/payments/stripe/projects/{project_id}/webhook-urlsGETGet webhook URLs for Stripe dashboard
/api/v1/payments/stripe/projects/{project_id}/validate-credentialsPOSTValidate Stripe API credentials
/api/v1/payments/stripe/projects/{project_id}/subscriptionsGETList project subscriptions
/api/v1/payments/stripe/projects/{project_id}/paymentsGETList project payment transactions

​
Stripe Checkout

Create Stripe checkout sessions for subscription or one-time payments.
EndpointMethodDescription
/api/v1/payments/stripe/checkout-sessionPOSTCreate checkout session

​
Stripe Webhooks

Receive and process webhook events from Stripe.
EndpointMethodDescription
/api/v1/payments/stripe/webhooks/{project_id}/{mode}POSTHandle Stripe webhook events

​
Stripe Subscriptions (End User)

End-user facing endpoints for managing their own subscriptions.
EndpointMethodDescription
/api/v1/payments/stripe/my-subscriptionGETGet current subscription
/api/v1/payments/stripe/my-paymentsGETGet payment history
/api/v1/payments/stripe/customer-portalPOSTCreate customer portal session
/api/v1/payments/stripe/cancel-subscriptionPOSTCancel subscription
/api/v1/payments/stripe/update-subscriptionPOSTChange subscription plan

​
Authentication

Payment endpoints use different authentication methods based on the user type:
User TypeAuth MethodHeader
DeveloperOAuth2 Bearer TokenAuthorization: Bearer {jwt}
End UserHTTP Bearer TokenAuthorization: Bearer {jwt}
WebhookStripe SignatureStripe-Signature: {signature}

​
Test vs Live Mode

All Stripe endpoints support both test and live modes:
  • Test Mode: Uses test API keys (prefix sk_test_ / pk_test_), simulated payments
  • Live Mode: Uses live API keys (prefix sk_live_ / pk_live_), real payments
The test_mode query parameter controls which mode is used (defaults to true for safety).

​
Quick Start

​
1. Configure Stripe Credentials

First, add your Stripe API keys to your project: 
curl -X PUT https://api.devkit4ai.com/api/v1/payments/stripe/projects/{project_id}/config \
  -H "Authorization: Bearer {developer_jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "test_secret_key": "sk_test_...",
    "test_publishable_key": "pk_test_...",
    "test_webhook_secret": "whsec_..."
  }'

​
2. Get Webhook URLs

Configure webhooks in your Stripe dashboard: 
curl https://api.devkit4ai.com/api/v1/payments/stripe/projects/{project_id}/webhook-urls \
  -H "Authorization: Bearer {developer_jwt}"

​
3. Create Checkout Session

Create a checkout session for end users: 
curl -X POST https://api.devkit4ai.com/api/v1/payments/stripe/checkout-session \
  -H "Authorization: Bearer {end_user_jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "price_id": "price_...",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
  }'

​
Webhook Events

The following Stripe webhook events are processed:
EventAction
checkout.session.completedCreate subscription record
customer.subscription.createdStore subscription details
customer.subscription.updatedUpdate subscription status
customer.subscription.deletedMark subscription cancelled
invoice.paidRecord successful payment
invoice.payment_failedRecord failed payment

Stripe Integration Tutorial

Step-by-step guide to integrating Stripe

Cloud Admin Payments

View payment analytics in Cloud Admin

Security Best Practices

Secure your payment integration

Environment Variables

Configure payment settings