Stripe setup

This page is primarily for administrators and developers configuring billing.

1. Create or access a Stripe account

1. Sign in to Stripe Dashboard.
2. Confirm you can switch between test and live mode.

2. Get API keys (test and live)

1. Open Developers -> API keys.
2. Copy and store these values for both test and live mode:

• Publishable key (pk_test_... or pk_live_...)
• Secret key (sk_test_... or sk_live_...)

3. Configure webhook endpoint

1. Open Developers -> Webhooks.
2. Create endpoint: https://<your-domain>/api/stripe/webhook.
3. For local development, you can forward Stripe events to localhost using Stripe CLI.

4. Select required webhook events

At minimum, subscribe to:

• invoice.payment_succeeded
• invoice.payment_failed
• customer.subscription.updated
• customer.subscription.deleted

5. Copy webhook signing secret

1. Open your webhook endpoint details in Stripe.
2. Copy the signing secret (whsec_...).
3. Save it as Stripe:WebhookSecret in app configuration.

6. Prepare pricing in Aisman first

Before go-live, finish your pricing setup inside Aisman:

• Define tiers, included features, add-ons, currencies, and region-specific overrides in the pricing admin UI.
• Use the admin page as the source of truth for pricing data; Stripe products and prices are synchronized from Aisman.
• Verify which prices are tax-exclusive and which region prices are tax-inclusive before going live.
• Activate only the tiers, features, and add-ons you want customers to see.
• The pricing admin area is restricted to the master pricing role.

Avoid creating a second manual price catalog in Stripe unless you are troubleshooting a sync problem.

7. Understand checkout mode

• Aisman uses embedded Stripe Checkout inside the pricing flow.
• Automatic tax is enabled during checkout.
• Subscription checkout can include the selected tier together with supported add-ons.
• Checkout uses the embedded Stripe components experience rather than sending users to a separate hosted checkout page.

8. Add Stripe values to appsettings.json

Set configuration values in appsettings.json (or environment-specific secure configuration):

{
  "Stripe": {
    "SecretKey": "sk_test_...",
    "PublishableKey": "pk_test_...",
    "WebhookSecret": "whsec_...",
    "Currency": "usd",
    "GracePeriodDays": 3
  }
}

Do not commit real live secrets to source control.

9. Test in Stripe test mode

1. Run checkout in test mode.
2. Use Stripe test cards.
3. Verify webhook delivery and app-side subscription updates.
4. Confirm payment failure and retry scenarios are handled.

10. Go-live checklist

Before switching to production:

1. Replace all test keys with live keys.
2. Confirm webhook endpoint and live signing secret.
3. Sync and verify live products and prices from Aisman.
4. Re-test an end-to-end purchase in live-safe conditions.
5. Monitor first live events in Stripe and application logs.

Related docs

• Aisman/Documents/stripe-setup.md in the main application project (detailed implementation notes)
• Output processing for post-agent processing workflow