Stripe Setup Guide for DirectoryCraft

Connecting your own Stripe account to DirectoryCraft lets you collect payments directly from listing submissions. This guide walks through the complete Bring Your Own Keys (BYOK) setup, from account creation to your first successful test payment.

Prerequisites

Before starting, ensure you have:

• An active Stripe account (register at stripe.com if needed)
• At least one product created in Stripe, this can be one-time or recurring
• Admin access to your DirectoryCraft project

Understanding Test vs Live Mode

Stripe operates in two distinct environments. Keep these separate to avoid confusion:

Critical rule: Test keys only work with Stripe’s test checkout pages. Live keys only work with real checkouts. Mixing these modes is the most common source of “why isn’t this working” confusion.

Step 1: Add Your Secret Key

The secret key authenticates your DirectoryCraft project with Stripe’s API.

1. In Stripe, go to Developers → API keys
2. Copy your Secret key (not the Publishable key)
3. In DirectoryCraft, navigate to Integrations → Stripe
4. Paste the secret key

Security note: Secret keys are encrypted immediately upon saving. DirectoryCraft never displays them again. If you lose track, generate a new key in Stripe and update the integration.

Step 2: Configure the Webhook

Webhooks let Stripe notify DirectoryCraft when payment events occur. Without this, your platform cannot confirm successful payments.

Copy Your Webhook URL

From Integrations → Stripe in DirectoryCraft, copy the displayed webhook URL. It follows this pattern:

For Test: https://www.example.com/api/stripe/webhook/project-id/test

For Live: https://www.example.com/api/stripe/webhook/project-id/live

Add the Endpoint in Stripe

1. In Stripe, go to Developers → Webhooks
2. Click Add an endpoint
3. Paste your DirectoryCraft webhook URL
4. Select these required events:
   • checkout.session.completed
   • checkout.session.async_payment_succeeded
   • checkout.session.async_payment_failed
   • checkout.session.expire
5. Save the endpoint

Retrieve the Webhook Secret

After creating the endpoint:

1. Click into the endpoint details
2. Reveal and copy the Signing secret (starts with whsec_)
3. Return to DirectoryCraft → Integrations → Stripe
4. Paste the webhook secret and save

Like secret keys, webhook secrets are encrypted and hidden after initial entry.

Step 3: Enable Paid Submissions

With Stripe connected, configure which listings require payment:

1. Go to Submit Form → Settings
2. Enable Paid submissions
3. Select one or more Stripe Prices to offer as payment options

You can attach multiple Prices here — for example, a basic listing and a featured upgrade.

Step 4: Test Your Integration

Never skip testing. A complete test validates your entire flow before real customers encounter it.

Run a Test Checkout

1. Ensure your DirectoryCraft integration uses test keys
2. Submit a test listing through your public form
3. At checkout, use Stripe’s test card numbers:
   • 4242 4242 4242 4242 — successful payment
   • 4000 0000 0000 0002 — declined payment
4. Complete the checkout flow

Verify the Result

Return to your DirectoryCraft admin and check the submission. The payment status should update to Paid within seconds of checkout completion.

Post-Checkout Behavior

After payment, Stripe redirects users back to your site:

/submit?submission=SUBMISSION_ID

DirectoryCraft displays a success message and automatically redirects to your homepage after a brief delay. If payment fails or cancels, the user returns with success=false and sees appropriate messaging.

Troubleshooting Common Issues

Webhook delivery requirement: Stripe cannot deliver webhooks to URLs behind authentication barriers. If your project uses password protection or preview mode, temporarily disable it during integration setup, or whitelist Stripe’s IP ranges.

Going Live

Once testing succeeds completely:

1. In Stripe, toggle to Live mode
2. Generate new live API keys and live webhook endpoint
3. Update DirectoryCraft with live secret key and live webhook secret
4. Switch your Submit Form Prices to live Prices
5. Run one final live checkout with a real card (use a small amount, refund immediately)

Security Summary

DirectoryCraft never transmits your keys to browsers or third parties outside of direct Stripe API calls.