Stripe Integration Payments

Each merchant store uses their own independent Stripe account. This guide explains how to connect your Stripe account to start accepting payments directly to your bank account.

Overview

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

Direct Payments: 100% of customer payments go directly to your Stripe account. There are no platform fees or intermediaries.

Key Benefits

Feature	Description
Direct deposits	Payments go straight to your bank account via Stripe
Full control	Manage refunds, disputes, and payouts in your Stripe dashboard
Your branding	Customers see your business name on their statements
Independent account	Your Stripe account is completely separate from other merchants

How It Works

Create a Stripe Account

Get Your API Keys

Copy your Publishable Key and Secret Key from Stripe Dashboard

Connect to Your Store

Enter your keys in the Stripe connection form

Start Accepting Payments

Customers can now pay on your store, with funds going to your Stripe account

Getting Your Stripe API Keys

Your API keys are found in your Stripe Dashboard:

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

API Key Types

pk_live_ or pk_test_ Publishable Key

Used in the browser to collect payment details. Safe to expose publicly.

sk_live_ or sk_test_ Secret Key

Used to create charges and manage your account. Keep this secret!

Security: Your Secret Key is encrypted before being stored. It is never exposed in logs, API responses, or anywhere else. Only our payment system uses it to process transactions.

Connecting Your Stripe Account

To connect Stripe to your store:

GET /stripe/connect?store_id=YOUR_STORE_ID

Opens the Stripe connection form where you enter your API keys.

Query Parameters

Parameter	Description
store_id	Your store's unique ID (required)
return_url	URL to redirect after successful connection (optional)

Example

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

Check Connection Status

GET /stripe/status/{store_id}

Check if your store has Stripe connected.

Response

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

API Endpoints

Public Endpoints

Endpoint	Method	Description
/stripe/connect	GET	Stripe key entry form
/stripe/status/{store_id}	GET	Check if Stripe is configured
/stripe/success/{store_id}	GET	Success page after connection

Internal Endpoints

These require the X-Internal-Secret header:

Endpoint	Method	Description
/api/internal/stores/{id}/stripe-status	GET	Get Stripe status for a store

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

Customer Adds to Cart

Widget creates cart using merchant's store ID

Checkout Session Created

Secure token generated for checkout page

Payment Form Loads

Stripe.js initialized with merchant's publishable key

PaymentIntent Created

Server creates PaymentIntent using merchant's secret key

Payment Confirmed

Funds go directly to merchant's Stripe account

Test vs Live Mode

Mode	Key Prefix	Real Money?	When to Use
Test	pk_test_, sk_test_	No	Development, testing checkout flow
Live	pk_live_, sk_live_	Yes	Production, real customer payments

Test Card Numbers

When using test mode, use these card numbers:

Card Number	Result
4242 4242 4242 4242	Successful payment
4000 0000 0000 0002	Card declined
4000 0000 0000 9995	Insufficient funds

Tip: Use any future expiration date, any 3-digit CVC, and any ZIP code when testing.

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

Encryption: All Stripe secret keys are encrypted using Fernet (AES-128-CBC) before being stored in the database. The encryption key is stored separately as an environment variable.

Security Measures

Measure	Description
Encrypted at rest	Secret keys are never stored in plaintext
Per-request isolation	Each payment uses the correct merchant's keys (no global state)
Key validation	Keys are verified against Stripe API before saving
No logging	Secret keys are never written to logs
HTTPS only	All API calls are encrypted in transit

Need help? Contact support or visit the Stripe Dashboard