Stripe Integration Payments

Overview

secure.checkout.best uses a per-merchant Stripe model. This means:

Key Benefits

How It Works

Getting Your Stripe API Keys

Your API keys are found in your Stripe Dashboard:

1. Go to dashboard.stripe.com
2. Click Developers in the left sidebar
3. Click API keys
4. Copy both keys (click "Reveal" for the secret key)

API Key Types

Connecting Your Stripe Account

To connect Stripe to your store:

https://secure.checkout.best/stripe/connect?store_id=550e8400-e29b-41d4-a716-446655440000&return_url=https://yoursite.com/dashboard

Check Connection Status

{
  "store_id": "550e8400-e29b-41d4-a716-446655440000",
  "has_stripe": true,
  "is_live_mode": true
}

Webhook Setup Required

Webhooks notify our checkout system when a payment succeeds or fails. Each merchant must configure their own webhook in their Stripe dashboard.

Step 1: Create Webhook in Stripe

1. Log in to your Stripe Dashboard
2. Navigate to Developers → Webhooks
3. Click "Add endpoint"
4. Enter this URL:
   https://secure.checkout.best/webhook/stripe
5. Select events to listen to:
   • payment_intent.succeeded (required)
   • payment_intent.payment_failed (recommended)
6. Click "Add endpoint"

Step 2: Copy Webhook Signing Secret

1. After creating the webhook, click on it to view details
2. Click "Reveal" next to the Signing secret
3. Copy the secret (starts with whsec_)

Step 3: Add Secret to Your Store

1. Go to the Merchant Portal
2. Click on your store → Payments tab
3. Find the Webhook Configuration section
4. Paste your webhook signing secret
5. Click "Save Webhook Secret"

Test Your Webhook

In Stripe's webhook details page, click "Send test webhook" and select payment_intent.succeeded. You should see a successful delivery response.

Troubleshooting

API Endpoints

Public Endpoints

Internal Endpoints

These require the X-Internal-Secret header:

BMOS Integration

For BuildMyOnlineStore integration, add a "Connect Payments" button in the merchant dashboard:

Redirect to Stripe Connection

@app.route('/dashboard/connect-payments/<storefront_id>')
def connect_payments(storefront_id):
    storefront = Storefront.query.get_or_404(storefront_id)
    
    return redirect(
        f"https://secure.checkout.best/stripe/connect"
        f"?store_id={storefront.checkout_best_store_id}"
        f"&return_url={url_for('dashboard', _external=True)}"
    )

Check Payment Status

import requests

def check_stripe_status(checkout_best_store_id):
    response = requests.get(
        f"https://secure.checkout.best/api/internal/stores/{checkout_best_store_id}/stripe-status",
        headers={"X-Internal-Secret": os.environ["CHECKOUT_BEST_SECRET"]}
    )
    return response.json()

# Usage
status = check_stripe_status(storefront.checkout_best_store_id)
if status.get("has_stripe"):
    print("Store can accept payments!")
else:
    print("Store needs to connect Stripe")

Payment Flow

Test vs Live Mode

Test Card Numbers

When using test mode, use these card numbers:

Troubleshooting

Common Issues

"Store not connected to Stripe"

The merchant hasn't entered their Stripe API keys yet. Redirect them to the connection form.

"Invalid API key"

The keys may have been regenerated in Stripe Dashboard. The merchant needs to re-enter their current keys.

"Payment failed"

Check the Stripe Dashboard for the specific error. Common causes:

• Card declined by bank
• Insufficient funds
• Expired card
• Incorrect CVC

Payments not showing in dashboard

Make sure you're viewing the correct mode (Test vs Live) in your Stripe Dashboard.

Security

Security Measures