Feat: Adding Payment Drivers, configuring stripe

src/Checkout/Contracts/PaymentDriver.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Modules\Core\Checkout\Contracts;
+
+use Lunar\Models\Cart;
+use Lunar\Models\Order;
+
+/**
+ * A boboko-owned payment driver — wraps a payment gateway's own confirmation
+ * mechanics (Stripe's synchronous authorize() call, a redirect-based
+ * provider's async callback/webhook, anything else) behind one uniform
+ * moment: "payment is confirmed, place the order."
+ *
+ * confirm() is the only thing a driver is required to do: once it has,
+ * by whatever mechanism is native to that gateway, independently decided
+ * the payment succeeded, it calls Modules\Core\Checkout\Services\
+ * CheckoutService::placeOrder($fingerprint) itself — no driver ever calls
+ * Lunar\Models\Cart::createOrder() directly. This is what lets the
+ * storefront checkout sequence stay uniform regardless of which provider is
+ * active: set addresses, select shipping, hand off to whichever driver is
+ * configured, and the driver decides when (or whether) the order actually
+ * gets created. See docs/checkout.md / docs/payments.md.
+ */
+interface PaymentDriver
+{
+    /**
+     * $data carries whatever the gateway needs to confirm this specific
+     * payment (Stripe: ['payment_intent' => $id], a redirect-based
+     * provider: its callback payload) — passed explicitly by the caller
+     * (a controller, a webhook job) rather than a driver reaching into the
+     * global request(), so confirm() works the same whether it's called
+     * from a synchronous HTTP request or an async webhook/job with no
+     * active request at all.
+     *
+     * @param  array<string, mixed>  $data
+     *
+     * @throws \Lunar\Exceptions\FingerprintMismatchException
+     * @throws \Lunar\Exceptions\Carts\CartException
+     */
+    public function confirm(Cart $cart, string $fingerprint, array $data): Order;
+}