Skip to main content

​
Overview

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

​
Payment Flow

1

Product Discovery

Users browse the marketplace and select a product to deploy.
2

Checkout Initiation

When a user clicks “Deploy”, 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

CNAP automatically determines the billing customer:
  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.
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

User completes payment on Stripe’s checkout page. Stripe handles:
  • Payment method collection
  • 3D Secure authentication
  • Payment processing
  • Receipt generation
6

Webhook & Deployment

Stripe sends a checkout.session.completed webhook to CNAP, which triggers:
  1. Install creation in the database
  2. Product deployment to the cluster
  3. 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 workspaceId in Stripe customer metadata, CNAP can quickly find the customer record using Stripe’s search API without maintaining a separate database table.

​
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
  • Implementation: Stripe Connect’s application_fee handles collection automatically

​
Error Handling & Reliability

If payment fails at Stripe’s checkout, no deployment is initiated. Users can retry by creating a new checkout session.
If deployment fails after payment succeeds:
This scenario requires manual intervention currently. The system uses workflows with infinite retries for transient failures, but non-retryable errors may result in a customer paying without receiving their deployment.
Current Behavior:
  • Retryable failures (network issues, temporary cluster unavailability): Infinite retry for up to 10 years
  • Non-retryable failures (invalid configuration): Workflow fails and compensation rolls back database changes
Planned Improvements:
  1. Implement payment hold → deploy → capture flow
  2. Automated refunds for deployment failures
  3. Parent workflow for orchestration and monitoring
  4. Customer notifications for stuck deployments
The system ensures idempotent operations:
  • Install Creation: Stripe event ID used as idempotency key (idk_{event_id})
  • Customer Creation: Search by workspaceId before creating
  • Workflow Execution: Workflow IDs prevent duplicate executions

​
Best Practices

Stripe Account Setup

Merchant workspaces must complete Stripe onboarding with charges_enabled: true before products can be sold.

Price Configuration

Ensure products have at least one Stripe price configured. CNAP validates this before allowing checkout.

​
Technical Architecture

​
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:
  1. Payment Hold Flow: Authorize payment before deployment, capture only after success
  2. Automated Refunds: Automatically refund customers if deployment fails
  3. Ownership Transfer: Update Stripe customer metadata when workspace owner changes
  4. Enhanced Monitoring: Dashboard for stuck deployments and payment issues
  5. Webhook Async Processing: Return 200 immediately, process deployment asynchronously
Have feedback on the payment system? Discuss on Discord!
⌘I