Commerce: Checkout and Order Processing – Reconciliation and Backfills
This section covers the SyncMissingStripePayments console command, designed for operations teams to reconcile and backfill missing orders and payments by replaying Stripe data through the SaveOrderService. It ensures data integrity when webhook delivery or initial processing fails.
Command Overview
Defines how to invoke reconciliation tasks for a given date range.
| Property | Value |
|---|---|
| Signature | stripe:sync-missing {date? : The date to sync payments for (YYYY-MM-DD)} |
| Description | Sync missing Stripe payments for a specific date and create corresponding database entries |
| Example | php artisan stripe:sync-missing 2025-10-01 |
# Sync today's payments
php artisan stripe:sync-missing
# Sync payments on a specific date
php artisan stripe:sync-missing 2025-10-01
The signature and description are defined in the command class itself .
Purpose and Use Cases
Helps maintain consistent order/payment records when external factors interrupt normal processing.
- Backfill missing orders when checkout sessions succeed but webhooks fail.
- Reconcile payment records for auditing and financial reporting.
- Ops recovery after partial outages or manual Stripe modifications.
Workflow
A step-by-step flow of how the command operates:
flowchart TD
A[Start: stripe:sync-missing] --> B{Load Configuration}
B -->|Secret found| C[Set Stripe API Key]
B -->|Missing key| Z[Exit with Error]
C --> D[Compute Start & End Timestamps]
D --> E[Fetch PaymentIntents via Stripe PHP SDK]
E --> F{Iterate Payments}
F -->|status ≠ succeeded| F
F -->|already exists| F
F -->|new & succeeded| G[Retrieve Checkout Session]
G -->|no session| F
G -->|session found| H[Invoke SaveOrderService->processSessionId]
H --> I{Orders Created?}
I -->|yes| J[Log Success]
I -->|no| K[Log No Orders]
H --> L[Catch Processing Errors]
L --> M[Log Error]
J --> F
K --> F
F --> N[Loop End]
N --> O[Exit 0]
Key Components
1. SyncMissingStripePayments Command
Responsible for orchestrating the backfill process.
protected $signature = 'stripe:sync-missing {date? : The date to sync payments for (YYYY-MM-DD)}';
protected $description = 'Sync missing Stripe payments for a specific date and create corresponding database entries';
public function handle()
{
$date = $this->argument('date') ? Carbon::parse($this->argument('date')) : Carbon::today();
Stripe::setApiKey(Config::get('services.stripe.secret'));
$payments = $this->getStripePayments($date->startOfDay()->timestamp, $date->endOfDay()->timestamp);
foreach ($payments as $payment) {
// skip logic…
$sessions = \Stripe\Checkout\Session::all(['payment_intent' => $payment->id,'limit'=>1]);
$orderRounds = (new SaveOrderService)->processSessionId($sessions->data[0]->id);
}
}
private function getStripePayments(int $from, int $to): array { /* … */ }
All code excerpts from SyncMissingStripePayments .
2. SaveOrderService → processSessionId
Encapsulates logic to convert a Stripe Checkout Session into application orders, rounds, and payments.
public function processSessionId($session, bool $deleteCart = true): Collection
{
$this->getStripeSession($session);
$cart = Cart::where('stripe_checkout_session_id', $session_id)->firstOrFail();
return $this->processCart($cart);
}
Handles:
- Restoring cart data
- Creating or updating
OrderandOrderRoundrecords - Dispatching
ProcessOrderjobs .
3. Dependencies
- Stripe PHP SDK (
Stripe\PaymentIntent,Stripe\Checkout\Session) - Laravel Console Command (
Illuminate\Console\Command) - Carbon for date parsing
- Config facade to read
services.stripe.secret - App\Models\Payment to detect existing records
Configuration
Ensure the Stripe secret key is set:
// config/services.php
'stripe' => [
'secret' => env('STRIPE_SECRET'),
'webhook' => env('STRIPE_WEBHOOK_SECRET'),
],
If missing, the command logs an error and exits with code 1 .
{
"title": "Ops Tip",
"content": "Verify STRIPE_SECRET is correctly loaded in your environment before running reconciliation."
}
Error Handling & Logging
- Configuration errors: missing API key → immediate exit.
- Stripe API errors: caught and logged; processing continues.
- Session retrieval issues: logged per payment to avoid halting the entire job.
- Processing exceptions: wrapped in try/catch; errors reported via
$this->error()for follow-up.
This reconciliation tooling empowers operational teams to ensure checkout data consistency by replaying Stripe events and regenerating any missing orders or payments.