IntegrationsStripe

Stripe Integration

Clacky provides a test Stripe API integration for development and testing purposes. This allows you to experiment with payment processing features without setting up your own Stripe account initially.

Test Environment

The platform offers a test version of the Stripe API that you can use during development:

  • Purpose: Development and testing only
  • Limitations: Test mode transactions are not real and do not process actual payments
  • Data: Test data will be periodically cleared
  • Rate Limits: Shared test environment may have usage restrictions

Important Note

⚠️ For Production Use: If you need to deploy your application to production or process real payments, you must use your own Stripe account with your own API keys.

Setting Up Your Own Stripe Account

To use Stripe in production, you’ll need to create and configure your own Stripe account.

1. Create a Stripe Account

Follow these steps to get started:

  1. Visit Stripe’s official website
  2. Click “Start now” or “Sign up”
  3. Provide your email address and create a password
  4. Complete the registration process

2. Account Verification

To activate your account for live transactions:

  1. Business Information: Provide details about your business
  2. Identity Verification: Submit required identification documents
  3. Bank Account: Connect a bank account for payouts
  4. Tax Information: Complete tax documentation (varies by country)

Verification typically takes 1-3 business days, though it may vary depending on your location and business type.

3. Get Your API Keys

Once your account is created:

  1. Log in to your Stripe Dashboard
  2. Navigate to Developers → API keys
  3. You’ll find two types of keys:
    • Test keys: For development and testing (starts with pk_test_ and sk_test_)
    • Live keys: For production use (starts with pk_live_ and sk_live_)

4. Configure Your Application

To use your own Stripe keys in Clacky:

  1. Store your API keys securely as environment variables
  2. Never commit API keys to your code repository
  3. Use test keys during development
  4. Switch to live keys only when deploying to production

Example environment configuration:

# .env.local
STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here
STRIPE_SECRET_KEY=sk_test_your_key_here

5. Configure Webhook Callback URLs

After deploying your application, you need to configure webhook endpoints in Stripe to receive real-time event notifications (such as successful payments, subscription updates, etc.).

Why Webhooks Are Important

Webhooks allow Stripe to notify your application when events happen in your Stripe account, such as:

  • Successful payments
  • Failed payment attempts
  • Subscription status changes
  • Refund processing
  • Dispute notifications

Setting Up Webhooks

  1. Deploy Your Application: First, deploy your application to get your production URL
  2. Log in to Stripe Dashboard: Go to Stripe Dashboard
  3. Navigate to Webhooks: Click Developers → Webhooks
  4. Add Endpoint: Click “Add endpoint” button
  5. Enter Your Callback URL:
    • For production: https://your-domain.com/integration/webhook/stripe
    • For development: https://your-dev-domain.com/integration/webhook/stripe
    • Replace with your actual deployed domain and webhook endpoint path
  6. Select Events: Choose which events you want to receive, or select “Listen to all events”
  7. Add Endpoint: Click “Add endpoint” to save

Important Notes

  • Different URLs for Test and Live Mode: Configure separate webhook endpoints for test mode and live mode
  • Webhook Signing Secret: After creating the webhook, Stripe will provide a signing secret (starts with whsec_). Store this securely: 
    STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
  • Verify Webhook Signatures: Always verify webhook signatures in your code to ensure requests are from Stripe
  • Handle Idempotency: Your webhook handler should be idempotent (safe to process the same event multiple times)

Testing Webhooks Locally

For local development, use the Stripe CLI to forward webhook events:

# Install Stripe CLI
stripe listen --forward-to localhost:3000/api/stripe/webhook

Webhook Configuration Resources

Official Documentation

For comprehensive guidance on setting up and using Stripe:

Frequently Asked Questions

Can I use the test environment for production?

No, the test environment is strictly for development and testing purposes. You must use your own Stripe account with live API keys for production applications.

What happens to my test data?

Test data created using the platform’s test environment may be periodically cleared. Always use your own Stripe test account for important development work.

How do I switch from test to production?

  1. Complete your Stripe account verification
  2. Update your environment variables with your live API keys
  3. Test thoroughly in your own Stripe test mode before going live
  4. Deploy your application with live keys

Is there a cost to create a Stripe account?

Creating a Stripe account is free. Stripe charges transaction fees only when you process real payments. Check Stripe’s pricing page for detailed information.

Which countries does Stripe support?

Stripe is available in 45+ countries. Visit Stripe’s global availability page to check if your country is supported.

GitLabUsage