Skip to main content

​
Overview

Stripe is TelemanAI’s recommended payment gateway for global subscription billing. It supports:
  • Credit and debit card payments
  • 135+ currencies
  • Strong authentication (3D Secure)
  • Automatic invoice generation
  • Subscription management
  • Webhook notifications

​
Prerequisites

  • A Stripe account (Sign up here)
  • Business verification completed (for production)
  • Bank account connected for payouts

​
Setup Instructions

1

Create Stripe Account

  1. Visit Stripe Dashboard
  2. Sign up with your business email
  3. Complete business verification
  4. Add bank account for payouts
2

Get API Keys

  1. Log in to Stripe Dashboard
  2. Click Developers → API keys
  3. You’ll see two types of keys:
Test Mode Keys:
  • Publishable key: pk_test_...
  • Secret key: sk_test_...
Live Mode Keys:
  • Publishable key: pk_live_...
  • Secret key: sk_live_...
Never share your secret key publicly or commit it to version control.
3

Configure Environment Variables

Add Stripe credentials to your .env file:For Testing (Sandbox Mode):
STRIPE="YES"
STRIPE_ENVIRONMENT="sandbox"
STRIPE_KEY="pk_test_Nr6hlHbDo44RWI4N6QhdYZNP00KS5i1lKX"
STRIPE_SECRET="sk_test_S5nEvoXdlANiZ82rWO99JEO800KB1boacQ"
For Production (Live Mode):
STRIPE="YES"
STRIPE_ENVIRONMENT="production"
STRIPE_KEY="pk_live_your_actual_key"
STRIPE_SECRET="sk_live_your_actual_secret"
Start with sandbox mode during development and testing.
4

Configure in Dashboard

  1. Log in to TelemanAI admin panel
  2. Navigate to Settings → Payment Gateways → Stripe
  3. Enter your Stripe credentials:
    • Environment: sandbox or production
    • Publishable Key (STRIPE_KEY)
    • Secret Key (STRIPE_SECRET)
  4. Click Save Configuration
This updates your .env file automatically.

​
Testing the Integration

1

Use Test Cards

Stripe provides test card numbers for different scenarios:Successful Payment:
Card Number: 4242 4242 4242 4242
CVV: Any 3 digits (e.g., 123)
Expiry: Any future date (e.g., 12/25)
ZIP: Any 5 digits (e.g., 12345)
Payment Declined:
Card Number: 4000 0000 0000 0002
Insufficient Funds:
Card Number: 4000 0000 0000 9995
Full list of test cards
2

Make a Test Purchase

  1. Go to TelemanAI pricing page
  2. Select a subscription plan
  3. Click Subscribe Now
  4. Fill in billing information
  5. Enter test card number: 4242 4242 4242 4242
  6. Complete the purchase
  7. Verify subscription is activated
3

Verify in Stripe Dashboard

  1. Go to Stripe Dashboard → Payments
  2. You should see the test payment
  3. Check payment status and amount
  4. View customer details

​
Webhook Configuration

Webhooks notify TelemanAI about payment events:
1

Create Webhook Endpoint

  1. In Stripe Dashboard, go to Developers → Webhooks
  2. Click Add endpoint
  3. Enter your endpoint URL: 
    https://your-domain.com/api/stripe/webhook
  4. Select events to listen for:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • charge.refunded
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
2

Get Webhook Secret

After creating the webhook:
  1. Click on the webhook endpoint
  2. Click Reveal under “Signing secret”
  3. Copy the secret (starts with whsec_...)
  4. Add to your .env file: 
    STRIPE_WEBHOOK_SECRET="whsec_..."
3

Test Webhook

  1. In Stripe Dashboard, go to webhook settings
  2. Click Send test webhook
  3. Select payment_intent.succeeded
  4. Click Send test webhook
  5. Verify TelemanAI receives the event

​
Payment Flow

Understand how payments are processed:

​
Implementation Details

​
Stripe Controller

See StripeController.php for implementation: Key Methods:
MethodDescriptionLine Reference
index()Display Stripe setup page20-23
update()Save Stripe configuration26-46
stripe()Display payment form51-60
stripePost()Process payment63-164

​
Payment Processing Logic

// Create Stripe charge
Stripe\Stripe::setApiKey(env('STRIPE_SECRET'));

$charge = Stripe\Charge::create([
    'amount' => $payment->amount * 100, // Convert to cents
    'currency' => 'usd',
    'source' => $request->stripeToken,
    'description' => 'Subscription payment for ' . $user->name,
]);

if ($charge->paid == true) {
    // Update subscription
    $subscription->payment_status = 'paid';
    $subscription->payment_gateway = 'Stripe';
    $subscription->save();
    
    // Activate credits
    $credits->credit += $subscription->credit;
    $credits->save();
    
    // Send invoice
    Mail::to($user->email)->queue(new InvoiceMail($subscription));
}
See StripeController.php (lines 75-114)

​
Stripe Gateway Service

// Service implementation
namespace App\Services\Payment;

use Stripe\Stripe;
use Stripe\Charge;

class StripeGateway implements PaymentGatewayInterface
{
    public function pay(array $paymentData)
    {
        Stripe::setApiKey(env('STRIPE_SECRET'));
        
        $charge = Charge::create([
            'amount'      => $paymentData['amount'] * 100,
            'currency'    => $paymentData['currency'] ?? 'USD',
            'source'      => $paymentData['token'],
            'description' => $paymentData['description'] ?? 'Payment',
        ]);
        
        return [
            'message'        => 'Payment successful.',
            'transaction_id' => $charge->id,
            'amount'         => $paymentData['amount'],
        ];
    }
}
See StripeGateway.php (lines 11-31)

​
Supported Currencies

Stripe supports 135+ currencies. Common ones:
  • USD - US Dollar
  • EUR - Euro
  • GBP - British Pound
  • CAD - Canadian Dollar
  • AUD - Australian Dollar
  • INR - Indian Rupee
  • JPY - Japanese Yen
  • SGD - Singapore Dollar
Full currency list
To change the currency, update the currency parameter in the charge creation.

​
Invoice Generation

TelemanAI automatically generates PDF invoices: 
// Generate invoice PDF
$pdf = PDF::loadView('frontend.success.attachment_invoice', [
    'details' => $subscription_details,
])->save(invoice_path($subscription_details->invoice));

// Send invoice email
Mail::to($user->email)->queue(new InvoiceMail([
    'paymentHistory' => $subscription_details
]));
See StripeController.php (lines 128-138)

​
Test vs Production Mode

​
Sandbox Mode (Testing)

STRIPE_ENVIRONMENT="sandbox"
STRIPE_KEY="pk_test_..."
STRIPE_SECRET="sk_test_..."
Characteristics:
  • Uses test API keys
  • No real money charged
  • Test cards accepted
  • Separate dashboard data
  • Webhooks can use localhost with Stripe CLI

​
Production Mode (Live)

STRIPE_ENVIRONMENT="production"
STRIPE_KEY="pk_live_..."
STRIPE_SECRET="sk_live_..."
Requirements:
  • Business verification complete
  • Bank account connected
  • HTTPS enabled (required)
  • Public webhook endpoint
  • Terms of service acceptance
Never use live keys in sandbox mode or vice versa. Always keep test and production environments separate.

​
Security Best Practices

Critical Security Measures:
  1. Never expose secret keys:
    • Use environment variables
    • Don’t commit to version control
    • Rotate keys if exposed
  2. Use HTTPS in production:
    • Required by Stripe
    • Protects customer data
    • Enables secure webhooks
  3. Verify webhook signatures:
    • Prevents webhook spoofing
    • Use STRIPE_WEBHOOK_SECRET
    • Validate all webhook events
  4. Implement rate limiting:
    • Prevent abuse
    • Limit payment attempts
    • Monitor for suspicious activity
  5. Log all transactions:
    • Audit trail
    • Debug payment issues
    • Compliance requirements

​
Troubleshooting

Problem: Invalid API Key provided: sk_test_...Solution:
  • Verify the secret key is correct (no extra spaces)
  • Ensure you’re using the right key for the environment
  • Check that .env file is properly loaded
  • Clear config cache: php artisan config:clear
Problem: Charge successful in Stripe but user subscription inactiveSolution:
  • Check webhook is configured and receiving events
  • Verify webhook secret is correct
  • Review TelemanAI logs for errors
  • Check database payment_histories and subscriptions tables
  • Manually trigger webhook from Stripe Dashboard
Problem: Test card 4242 4242 4242 4242 is declinedSolution:
  • Ensure you’re in test mode: STRIPE_ENVIRONMENT="sandbox"
  • Use test keys (starting with pk_test_ and sk_test_)
  • Check you entered a future expiry date
  • Verify CVV is 3 digits
Problem: “Currency not supported” errorSolution:
  • Check Stripe supports your currency
  • Verify currency code is correct (ISO 4217)
  • Update the currency parameter in charge creation
  • Some currencies require specific account setup
Problem: Stripe can’t reach webhook endpointSolution:
  • Ensure URL is publicly accessible (not localhost)
  • Verify SSL certificate is valid
  • Check server firewall allows Stripe IPs
  • Test URL accessibility with curl: 
    curl -X POST https://your-domain.com/api/stripe/webhook
  • For local testing, use Stripe CLI

​
Stripe Dashboard

Key sections of the Stripe Dashboard:
  • Payments: View all transactions
  • Customers: Manage customer records
  • Subscriptions: Track recurring payments
  • Disputes: Handle chargebacks
  • Logs: Debug API requests
  • Webhooks: Monitor webhook delivery
  • Reports: Financial reporting

​
Advanced Features

​
3D Secure Authentication

Stripe automatically handles Strong Customer Authentication (SCA): 
// 3D Secure is handled automatically
$charge = Charge::create([
    'amount' => $amount,
    'currency' => 'eur',
    'source' => $token,
    // Stripe handles 3DS if required
]);

​
Payment Intents API

For advanced use cases, consider using Payment Intents: 
use Stripe\PaymentIntent;

$intent = PaymentIntent::create([
    'amount' => 1000,
    'currency' => 'usd',
    'payment_method_types' => ['card'],
]);

​
Customer Portal

Allow customers to manage their subscriptions: 
$session = \Stripe\BillingPortal\Session::create([
    'customer' => $customer_id,
    'return_url' => route('dashboard'),
]);

return redirect($session->url);

​
Going Live Checklist

1

Complete Business Verification

  • Submit business documents
  • Verify bank account
  • Accept Stripe terms
2

Update to Live Keys

  • Replace test keys with live keys
  • Set STRIPE_ENVIRONMENT="production"
  • Clear config cache
3

Configure Live Webhooks

  • Create webhook for production URL
  • Update STRIPE_WEBHOOK_SECRET
  • Test webhook delivery
4

Enable HTTPS

  • Install SSL certificate
  • Force HTTPS in application
  • Update all URLs to HTTPS
5

Test End-to-End

  • Make a real small payment
  • Verify subscription activation
  • Check invoice generation
  • Test webhook notifications

​
Next Steps

PayPal Integration

Add PayPal as an alternative payment method

Subscription Plans

Configure your subscription plans

Invoice Customization

Customize invoice templates

Payment Analytics

Track payment metrics

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us