Stripe Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stripe/stripe-php:^20.2.0-alpha.5
   

   Update config/services.php (Laravel convention) to include new optional fields:

   'stripe' => [
       'key' => env('STRIPE_KEY'),
       'secret' => env('STRIPE_SECRET'),
       'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
       'api_version' => env('STRIPE_API_VERSION', '2023-10-16'), // Explicitly set for stability
   ],
   

2. First Use Case (New Features): Initialize Stripe with the new API version in AppServiceProvider:

   use Stripe\Stripe;
   
   Stripe::setApiKey(config('services.stripe.secret'));
   Stripe::setApiVersion(config('services.stripe.api_version'));
   

   New: Fee Batch Example (Private Preview):

   use Stripe\V2\Core\FeeBatch;
   
   $feeBatch = FeeBatch::create([
       'amount' => 1000,
       'currency' => 'usd',
       'description' => 'Fee batch for service charges',
   ]);
   

3. Key Files:

   • config/services.php (credentials + API version)
   • app/Services/StripeService.php (updated wrapper for new resources)
   • routes/web.php (new webhook routes for FinancialAccountStatement events)
   • app/Events/StripeWebhookHandler.php (handler for new event types)

Implementation Patterns

Core Workflows

1. Service Layer Pattern (Updated): Extend StripeService to support new resources:

   namespace App\Services;
   
   use Stripe\Stripe;
   use Stripe\V2\MoneyManagement\DebitDispute;
   use Stripe\V2\MoneyManagement\FinancialAccountStatement;
   
   class StripeService {
       public function __construct() {
           Stripe::setApiKey(config('services.stripe.secret'));
           Stripe::setApiVersion(config('services.stripe.api_version'));
       }
   
       // New: Debit Dispute Management
       public function createDebitDispute($paymentIntentId, array $data) {
           return DebitDispute::create([
               'payment_intent' => $paymentIntentId,
               ...$data,
           ]);
       }
   
       // New: Financial Account Statements
       public function getFinancialAccountStatement($statementId) {
           return FinancialAccountStatement::retrieve($statementId);
       }
   
       public function listFinancialAccountStatements($accountId) {
           return FinancialAccountStatement::all(['financial_account' => $accountId]);
       }
   }
   

2. Webhook Handling (Updated): Add handlers for new event types in StripeWebhookController:

   public function handle(Request $request) {
       $payload = $request->getContent();
       $sigHeader = $request->header('Stripe-Signature');
       $event = \Stripe\Webhook::constructEvent($payload, $sigHeader, config('services.stripe.webhook_secret'));
   
       // Handle new event types
       switch ($event->type) {
           case 'V2MoneyManagement.FinancialAccountStatement.created':
               $statement = $event->data->object;
               // Process new statement
               break;
           case 'V2MoneyManagement.FinancialAccountStatement.restated':
               $statement = $event->data->object;
               // Handle restated statement
               break;
           // ... existing cases
       }
   }
   

3. Delegated Checkout (New): Use the updated DelegatedCheckout resource for discounts and line items:

   use Stripe\DelegatedCheckout\RequestedSession;
   
   $session = RequestedSession::create([
       'line_item_details' => [
           [
               'amount_sale' => 1000, // New field
               'amount_discount' => 100, // New field
           ],
       ],
       'total_details' => [
           'amount_sale' => 1000,
           'amount_discount' => 100,
           'breakdown' => ['tax' => 100], // New field
       ],
       'discounts' => [['coupon' => 'SUMMER20']], // New field
   ]);
   

4. Payment Location (Updated): Manage payment locations with the new all() method:

   use Stripe\PaymentLocation;
   
   $locations = PaymentLocation::all(['business' => 'ba_123']);
   foreach ($locations->autoPagingIterator() as $location) {
       // Process each location
   }
   

5. Radar Customer Evaluations (New): Update customer evaluations with optional fields:

   use Stripe\Radar\CustomerEvaluation;
   
   $evaluation = CustomerEvaluation::update(
       'radarceval_123',
       ['status' => 'approved', 'customer' => 'cus_456'] // New fields
   );
   

Integration Tips

• Private Preview Features: Enable private preview features via API version:

  Stripe::setApiVersion('2023-10-16'); // Ensure this version supports private preview
  

  Check Stripe's private preview docs for feature availability.

• Testing New Features: Use Stripe CLI to test new resources locally:

  stripe listen --forward-to localhost:3000/stripe/webhook --api-version=2023-10-16
  

  Mock new resources in PHPUnit:

  $this->partialMock(\Stripe\V2\MoneyManagement\DebitDispute::class, 'create');
  

• Deprecation Handling: Remove check_deposit_address from payment method options:

  // Old (deprecated)
  Invoice::create([
      'payment_settings' => [
          'payment_method_options' => [
              'check_scan' => ['check_deposit_address' => '123 Main St'],
          ],
      ],
  ]);
  
  // New
  Invoice::create([
      'payment_settings' => [
          'payment_method_options' => [
              'check_scan' => [], // No check_deposit_address
          ],
      ],
  ]);
  

• Payment Evaluations (New): Report payment evaluations for guaranteed payments:

  use Stripe\PaymentRecord;
  
  $paymentRecord = PaymentRecord::reportPayment([
      'payment' => 'pm_123',
      'guaranteed' => [
          'payment_evaluations' => [
              ['status' => 'approved', 'reason' => 'high_risk'],
          ],
      ],
  ]);
  

Gotchas and Tips

Common Pitfalls

1. API Versioning (Critical):

   • Breaking Change: The new release introduces private preview features tied to specific API versions. Always explicitly set Stripe::setApiVersion() to avoid unexpected behavior.
   • Example: If you don’t set the version, you may unintentionally use the latest stable version, which might not include private preview features.
   • Fix: Add this to your StripeService constructor:

     Stripe::setApiVersion(config('services.stripe.api_version'));
     

2. Deprecated Fields:

   • Removed: check_deposit_address from check_scan payment method options. This will cause errors if not updated.
   • Fix: Remove the field from all Invoice, Subscription, and QuotePreviewInvoice creation/update calls.

3. Private Preview Limitations:

   • Features like FeeBatch, DebitDispute, and FinancialAccountStatement are in private preview. They may change or be removed without notice.
   • Workaround: Use feature flags or environment checks to toggle these features:

     if (config('services.stripe.enable_private_preview')) {
         $feeBatch = FeeBatch::create([...]);
     }
     

4. Webhook Event Types (New):

   • New Events: V2MoneyManagement.FinancialAccountStatement.created and V2MoneyManagement.FinancialAccountStatement.restated require handling.
   • Pitfall: Forgetting to add handlers for these events may lead to unprocessed statements.
   • Fix: Update your webhook controller to include:

     case 'V2MoneyManagement.FinancialAccountStatement.created':
     case 'V2MoneyManagement.FinancialAccountStatement.restated':
         $this->handleFinancialAccountStatement($event);
         break;
     

5. Optional Fields (New):

   • New Optional Fields: Fields like customer on Radar\CustomerEvaluation or status on PaymentLocation are now optional but may be required in the future.
   • Tip: Document these changes in your codebase to avoid future breaking changes:

     // Example: Updated Radar Customer Evaluation
     $params = [
         '