Stripe Php Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require stripe/stripe-php:^20.1.0-alpha.3

Add to composer.json autoload if not using Composer's default autoloading.

2. Initialize Client:

   use Stripe\StripeClient;
   
   $stripe = new StripeClient(config('services.stripe.key'));
   

   Note: Prefer StripeClient over legacy \Stripe\Stripe::setApiKey() for new projects.

3. First Use Case: Create a customer with the new StripeClient:

   use Stripe\Customer;
   
   public function createCustomer(Request $request, StripeClient $stripe) {
       $customer = $stripe->customers->create([
           'email' => $request->email,
           'name' => $request->name,
           'payment_method' => $request->payment_method_id,
       ]);
       return response()->json($customer);
   }
   

Key Starting Points

• Laravel Service Provider: Register the Stripe client in AppServiceProvider:

  public function boot() {
      $this->app->singleton(StripeClient::class, function ($app) {
          return new StripeClient(config('services.stripe.key'));
      });
  }
  

• Config File: Add to config/services.php:

  'stripe' => [
      'key' => env('STRIPE_KEY'),
      'secret' => env('STRIPE_SECRET'),
      'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
  ],
  

• API Docs: Reference Stripe PHP API Docs (v20) for resource methods.
• Private Preview Features: Enable with \Stripe\Stripe::addBetaVersion('feature_name', 'v1').

Implementation Patterns

Core Workflows

1. Customer Management (Updated for StripeClient):

   // Create
   $customer = $stripe->customers->create(['email' => 'user@example.com']);
   
   // Update
   $customer->update(['name' => 'Updated Name']);
   
   // Retrieve
   $customer = $stripe->customers->retrieve('cus_123');
   
   // List
   $customers = $stripe->customers->all(['limit' => 10]);
   

2. Payment Processing with New Features:

   // Charge with money service details (new in v20)
   $charge = $stripe->charges->create([
       'amount' => 1000,
       'currency' => 'usd',
       'customer' => $customer->id,
       'payment_detail' => [
           'money_service' => [
               'account_funding' => [
                   'beneficiary_account' => 'ba_123',
                   'transaction_type' => 'account_funding',
               ],
           ],
       ],
   ]);
   
   // Handle webhooks (unchanged)
   Route::post('/stripe/webhook', function (Request $request, StripeClient $stripe) {
       $payload = $request->getContent();
       $sigHeader = $request->header('Stripe-Signature');
       $event = $stripe->webhookEndpoints->constructEvent($payload, $sigHeader, config('services.stripe.webhook_secret'));
       // Handle event
   });
   

3. Subscriptions with Bizum Support:

   $subscription = $stripe->subscriptions->create([
       'customer' => $customer->id,
       'items' => [['price' => 'price_123']],
       'payment_settings' => [
           'payment_method_options' => [
               'bizum' => ['reference' => '123456789'],
           ],
       ],
   ]);
   

4. PaymentIntents with Fleet Data (Private Preview):

   $stripe->addBetaVersion('payment_intent_fleet_data', 'v1');
   $intent = $stripe->paymentIntents->create([
       'amount' => 1000,
       'currency' => 'usd',
       'payment_method' => 'pm_123',
       'payment_detail' => [
           'fleet_data' => [
               'vehicle_identification_number' => '1HGCM82633A123456',
           ],
       ],
   ]);
   

Integration Tips

• Laravel Middleware: Protect Stripe routes (unchanged):

  Route::middleware(['stripe.webhook'])->post('/stripe/webhook', ...);
  

• Testing with New Features: Use updated test helpers:

  use Stripe\TestHelper;
  
  TestHelper::init();
  $charge = $stripe->charges->create([
      'amount' => 1000,
      'currency' => 'usd',
      'payment_method' => TestHelper::createPaymentMethod(),
      'payment_detail' => ['money_service' => ['account_funding' => ['transaction_type' => 'account_funding']]],
  ]);
  

• Idempotency (Critical for new endpoints):

  $charge = $stripe->charges->create([
      'amount' => 1000,
      'currency' => 'usd',
      'idempotency_key' => 'unique_key_for_new_endpoint',
  ]);
  

• Webhooks with New Events: Listen for payment_intent.payment_failed and handle CannotProceedException:

  if ($event->type === 'payment_intent.payment_failed') {
      $paymentIntent = $event->data->object;
      if (isset($paymentIntent->last_payment_error->error->type) &&
          $paymentIntent->last_payment_error->error->type === 'cannot_proceed') {
          // Handle new exception type
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. API Key Exposure (Unchanged):

   • Never hardcode keys. Use Laravel's .env and dependency injection.

2. Legacy Patterns (Updated):

   • Deprecated: \Stripe\Stripe::createToken() and \Stripe\Stripe::setApiKey().
   • Preferred: Use StripeClient with explicit resource methods (e.g., $stripe->customers->create()).
   • Breaking: Removed support for legacy ID number types (e.g., bm_crn, ph_tin). Update your account creation logic if using these.

3. Idempotency for New Endpoints:

   • Always use idempotency keys for all non-idempotent operations, especially with private preview features.
   • Example: PaymentIntent operations with fleet_data or money_service details.

4. Webhook Delays (Unchanged):

   • Webhooks may still take up to 10 minutes. Implement retries with exponential backoff.

5. TLS Issues (Unchanged):

   • Ensure TLS 1.2+. Configure cURL if needed:

     $stripe->setHttpClient(new \Stripe\HttpClient\CurlClient([
         CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2,
     ]));
     

6. Private Preview Features:

   • Enable explicitly with \Stripe\Stripe::addBetaVersion().
   • These may change or be removed without notice. Use in non-production first.

7. Enum Changes:

   • Radar.CustomerEvaluation.event_type now strictly enum('login'|'registration') (was string).
   • Radar.CustomerEvaluation.signals.risk_level now uses strict enums (was string).

Debugging Tips

• Enable Logging (Updated for StripeClient):

  $stripe->setLogger(\Log::getMonolog());
  

• Inspect Responses:

  $charge = $stripe->charges->create([...]);
  \Log::debug($charge->lastResponse->headers);
  

• Test Mode Quirks (Unchanged):

  • Use TestHelper::init() to reset test data.
  • Test cards may fail if not whitelisted in test mode.

• New Exception Handling:

  try {
      $intent = $stripe->paymentIntents->create([...]);
  } catch (\Stripe\Exception\CannotProceedException $e) {
      \Log::error('Cannot proceed: ' . $e->getMessage());
      // Handle new exception type
  }
  

Extension Points

1. Custom HTTP Client (Updated):

   $client = new \Stripe\HttpClient\CurlClient([
       CURLOPT_PROXY => 'http://proxy:8080',
       CURLOPT_TIMEOUT => 30,
   ]);
   $stripe->setHttpClient($client