Payments API

MyClaude processes payments through Stripe Connect Express. The platform never handles raw card data -- all payment processing is delegated to Stripe (PCI DSS Level 1 certified). Orders are created exclusively by Stripe webhooks, never by client-side code.

Purchase flow

The complete purchase sequence involves four components: the buyer's browser, the MyClaude API, Stripe, and the webhook handler.

Buyer clicks "Buy"
    |
    v
POST /stripe/checkout  (Bearer token + productId)
    |
    +-- Verify auth token
    +-- Verify product exists, is published, is paid
    +-- Verify buyer has not already purchased
    +-- Verify seller has active Stripe account
    +-- Calculate platform fee (8%)
    +-- Create Stripe Checkout Session
    |
    v
302 Redirect to Stripe Checkout
    |
    v
Buyer completes payment on stripe.com
    |
    v
Stripe fires webhook: checkout.session.completed
    |
    v
POST /stripe/webhooks  (Stripe signature verification)
    |
    +-- Verify webhook signature
    +-- Re-verify price against database
    +-- Create order in Firestore (atomic, idempotent)
    +-- Update product stats (purchaseCount)
    +-- Update seller stats (totalRevenue, totalSales, +50 XP)
    +-- Update buyer stats (productsBought, +10 XP)
    |
    v
Buyer returns to product page
    |
    v
Download button appears (order verified server-side)

Create checkout session

Create a Stripe Checkout Session for purchasing a paid product. Returns a URL that redirects the buyer to Stripe's hosted checkout page.

POST /stripe/checkout

Auth: Required (Bearer token) Rate limit: 10/min (strict)

Request body

{
  "productId": "abc123"
}

Response

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Validation checks

The server performs these checks before creating a checkout session:

Platform fee

The platform fee is calculated server-side as a constant:

Platform fee = 8% of product price
Seller receives = 92% of product price

The fee is set as application_fee_amount on the Stripe PaymentIntent with transfer_data.destination pointing to the seller's connected account.

Errors

Stripe Connect onboarding

Create a Stripe Connect Express account for the authenticated user, or generate a login/onboarding link if an account already exists.

POST /stripe/connect

Auth: Required (Bearer token) Rate limit: 5/min (strict)

Request body

None.

Response (new account)

{
  "url": "https://connect.stripe.com/express/onboarding/...",
  "accountId": "acct_1234567890"
}

Response (existing account, fully onboarded)

{
  "url": "https://connect.stripe.com/express/login/..."
}

Response (existing account, onboarding incomplete)

{
  "url": "https://connect.stripe.com/express/onboarding/...",
  "accountId": "acct_1234567890"
}

Behavior by account state

The created Stripe Express account is configured with card_payments and transfers capabilities. The firebaseUid is stored in the account metadata for webhook reconciliation.

Errors

Stripe callback

Redirect endpoint called by Stripe after the user completes (or abandons) Connect onboarding. This is not called by API consumers directly.

GET /stripe/callback?account_id=acct_...&uid=...

Auth: None (redirect handler)

Behavior

1. Retrieves the Stripe account and verifies metadata.firebaseUid matches the uid parameter.
2. Updates the user profile with stripeAccountId and stripeOnboarded status.
3. Redirects the user to /sales?stripe=success or /sales?stripe=error.

Stripe webhooks

Receives and processes events from Stripe. Webhook signature verification is mandatory -- unsigned or tampered events are rejected.

POST /stripe/webhooks

Auth: Stripe webhook signature (stripe-signature header) Rate limit: None (Stripe-initiated)

Handled events

Order creation (checkout.session.completed)

Orders are created inside a Firestore transaction with the Stripe session ID as the document ID, making the operation idempotent. If Stripe retries the webhook, duplicate orders are detected and skipped.

The server re-verifies the product price against the database and cross-checks with session.amount_total from Stripe. If amounts diverge (e.g., price changed between checkout creation and webhook delivery), the discrepancy is logged but the order is still created using Stripe's actual charged amount.

Order document structure:

{
  "buyerUid": "uid_buyer",
  "sellerUid": "uid_seller",
  "productId": "abc123",
  "productTitle": "Code Review Skill",
  "productCategory": "skills",
  "amount": 999,
  "platformFee": 80,
  "sellerAmount": 919,
  "currency": "usd",
  "stripeSessionId": "cs_live_...",
  "stripePaymentIntentId": "pi_...",
  "status": "completed",
  "createdAt": "2026-03-24T12:00:00.000Z",
  "updatedAt": "2026-03-24T12:00:00.000Z"
}

All monetary values are in cents (e.g., 999 = $9.99).

Refund processing (charge.refunded)

When a charge is refunded through Stripe:

1. The order status is updated to "refunded" with a refundedAt timestamp.
2. Seller stats are decremented (totalSales, totalRevenue).
3. Buyer stats are decremented (productsBought).
4. The seller receives a notification about the refund.

Refund processing is also idempotent -- already-refunded orders are skipped.

Error handling

Pricing model

The 8% platform fee is a server-side constant. It is never read from environment variables or client-side configuration.

Security guarantees

Related pages

• API Overview -- Auth model, rate limits, error format
• Downloads API -- Post-purchase download flow
• Products API -- Product operations
• Creator Monetization -- Revenue and payout details for creators
• Security Model -- Platform security architecture