Skip to main content
CNAP uses Stripe Connect to enable marketplace payments, allowing workspace owners to monetize their applications. The payment system is designed to be secure, reliable, and transparent.

​
Key Features

  • Stripe Connect Integration - Each merchant workspace has its own Stripe account
  • Automated Customer Management - Customers are automatically created and linked to workspaces
  • Workspace-Based Billing - All installs are tied to workspace ownership, not individual users

​
How Payments Work

When customers purchase products through the marketplace, CNAP handles the entire payment flow automatically. The system validates the purchase, creates or finds the appropriate billing customer, processes payment through Stripe’s hosted checkout, and triggers deployment after successful payment.

​
Payment Flow Overview

The payment process includes several stages:
  1. Product discovery - Customers browse the marketplace and select products to deploy
  2. Checkout initiation - CNAP validates:
    • User is authenticated
    • User is a member of the target workspace
    • Product has valid Stripe configuration
    • User is not deploying to their own product’s workspace
    Any workspace member can initiate checkout, but the billing is tied to the customer’s workspace owner.
  3. Customer resolution - The system automatically finds or creates the appropriate Stripe customer based on the workspace owner
  4. Stripe checkout session - A Stripe checkout session is created with:
    • The product’s prices
    • Platform fee (percentage-based)
    • Success/cancel URLs
    • Customer ID
    • Metadata (userId, workspaceId, productId, regionId) The user is redirected to Stripe’s hosted checkout page.
  5. Payment processing - Stripe handles:
    • Payment method collection
    • 3D Secure authentication
    • Payment processing
    • Receipt generation
  6. Webhook and deployment - Stripe sends a checkout.session.completed webhook to CNAP, which triggers:
    • Install creation in the database
    • Product deployment to the cluster
    • Email notification to the customer and merchant
    The deployment workflow includes compensation logic to rollback changes if any step fails.

​
Stripe Customer Management

​
Why Workspace Owners?

CNAP associates Stripe customers with workspace owners rather than individual users for several important reasons:
Workspace owners have administrative and financial responsibility for their workspace. All purchases made by any workspace member should be billed to the workspace owner’s account.
If customer records were tied to individual users, different team members making purchases would create multiple customer records for the same workspace, fragmenting billing history and complicating accounting for the merchant.
Team members can come and go, but the workspace owner remains responsible. This prevents billing issues when employees leave or team structure changes.
By storing workspace ID in Stripe customer metadata, CNAP can quickly find the customer record using Stripe’s search API without maintaining a separate database table.

​
Customer Resolution Process

CNAP automatically determines the billing customer through this process:
  1. Search for existing customer - Check Stripe for a customer with metadata.workspaceId matching the buyer’s workspace
  2. Lookup workspace owner - If no customer exists, query the workspace to find the user with the owner role
  3. Create customer - Create a new Stripe customer with:
    • metadata.workspaceId: The buyer’s workspace ID (for lookup)
    • metadata.userId: The workspace owner’s user ID (not the person creating checkout)
    • email: The owner’s email address
    • name: The owner’s name (or derived from the owner’s email)
The Stripe customer is always the workspace owner, not the person initiating the checkout. This ensures billing responsibility stays with the workspace owner regardless of which team member makes the purchase.

​
Customer Metadata Schema

Stripe customers created by CNAP include the following metadata:
​
metadata.workspaceId
string
required
The customer’s workspace ID. This is the primary lookup key used to find existing customers when creating checkout sessions.
​
metadata.userId
string
The workspace owner’s user ID at the time of customer creation. This is used for reference but may become stale if workspace ownership changes.
Future implementations may update this field when workspace ownership changes.

​
Customer Lifecycle

  • Creation - Customers are created automatically during the first checkout from a workspace. The workspace owner’s details are looked up and stored in the Stripe customer record
  • Reuse - Subsequent checkouts from the same workspace reuse the existing customer record. This is achieved by searching Stripe for metadata.workspaceId
  • Persistence - Customer records are never deleted, even if an install fails. This allows safe reuse across multiple purchases and prevents unnecessary recreation
  • Updates - Customer details (email, name) are not automatically updated if the workspace owner changes. This is a known limitation for future improvement

​
Platform Fees

CNAP collects a platform fee on all transactions:
  • Payment mode - Fixed percentage calculated on total transaction amount
  • Subscription mode - Percentage of subscription amount collected on each billing cycle
  • Automatic collection - Stripe Connect’s application fee handles collection automatically with no additional configuration required

​
Error Handling and Reliability

The payment system includes several reliability features to handle edge cases:
If payment fails at Stripe’s checkout, no deployment is initiated. Customers can retry by creating a new checkout session.
If deployment fails after payment succeeds, the system includes compensation logic to rollback changes. Retryable failures (network issues, temporary cluster unavailability) are automatically retried for up to 10 years. Non-retryable failures (invalid configuration) cause the workflow to fail and compensation rolls back database changes.
This scenario may require manual intervention currently. Non-retryable errors may result in a customer paying without receiving their deployment.
Planned improvements:
  • Payment hold → deploy → capture flow
  • Automated refunds for deployment failures
  • Parent workflow for orchestration and monitoring
  • Customer notifications for stuck deployments
The system ensures idempotent operations to prevent duplicate charges or deployments:
  • Install creation - Stripe event ID used as idempotency key (idk_{event_id})
  • Customer creation - Search by workspace ID before creating
  • Workflow execution - Workflow IDs prevent duplicate executions

​
Stripe Account Setup

Each merchant workspace needs its own Stripe account to sell products:
  • Stripe Connect - Workspaces connect their Stripe accounts through CNAP’s settings
  • Account requirements - Stripe accounts must complete onboarding and have charges enabled before products can be sold
  • Independent accounts - Each workspace maintains its own Stripe account, keeping revenue and payouts separate

​
Best Practices

  • Stripe account setup - Merchant workspaces must complete Stripe onboarding with charges enabled before products can be sold
  • Price configuration - Ensure products have at least one Stripe price configured. CNAP validates this before allowing checkout

​
Troubleshooting

Cause: Merchant workspace hasn’t completed Stripe onboarding.Solution: Navigate to Settings → Stripe and complete the account connection flow.
Cause: Deployment workflow encountered a non-retryable error.Solution: Check your cluster status and contact CNAP support for assistance.

​
Future Enhancements

The following improvements are planned:
  • Payment hold flow - Authorize payment before deployment, capture only after success
  • Automated refunds - Automatically refund customers if deployment fails
  • Ownership transfer - Update Stripe customer metadata when workspace owner changes
  • Enhanced monitoring - Dashboard for stuck deployments and payment issues
  • Webhook async processing - Return 200 immediately, process deployment asynchronously