@paykit-sdk/stripe 1.2.1 → 1.2.3

package/dist/index.js

@@ -289,19 +289,33 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         name: data.name,
         email: data.email
       });
+      const {
+        billing: _billing,
+        metadata,
+        provider_metadata,
+        name: _name,
+        ...stripeParams
+      } = data;
       const customer = await this.stripe.customers.create({
-        ...params,
-        phone: params.phone ?? void 0,
-        name: fullName
+        ...provider_metadata,
+        ...stripeParams,
+        phone: data.phone ?? void 0,
+        name: fullName,
+        metadata: core.stringifyMetadataValues(metadata ?? {})
       });
       return Customer$inboundSchema(customer);
     };
     this.updateCustomer = async (id, params) => {
-      const { provider_metadata, ...rest } = params;
+      const {
+        provider_metadata,
+        billing: _billing,
+        metadata,
+        ...rest
+      } = params;
       const customer = await this.stripe.customers.update(id, {
         ...provider_metadata,
         ...rest,
-        metadata: core.stringifyMetadataValues(rest.metadata ?? {}),
+        metadata: core.stringifyMetadataValues(metadata ?? {}),
         phone: rest.phone ?? void 0
       });
       return Customer$inboundSchema(customer);
@@ -547,7 +561,8 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         );
       }
       const { provider_metadata, customer, ...rest } = data;
-      const payment = await this.stripe.paymentIntents.retrieve(id);
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.retrieve(piId);
       const paymentOptions = {
         ...provider_metadata,
         metadata: core.stringifyMetadataValues({
@@ -569,10 +584,10 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         paymentOptions.receipt_email = customer.email;
       }
       const updatedPayment = await this.stripe.paymentIntents.update(
-        id,
+        piId,
         paymentOptions
       );
-      return Payment$inboundSchema(updatedPayment);
+      return { ...Payment$inboundSchema(updatedPayment), id };
     };
     this.retrievePayment = async (id) => {
       const { error, data } = core.retrievePaymentSchema.safeParse({ id });
@@ -583,6 +598,34 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
           "retrievePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        const [session, sessionError] = await core.tryCatchAsync(
+          this.stripe.checkout.sessions.retrieve(data.id, {
+            expand: ["payment_intent"]
+          })
+        );
+        if (!session || sessionError?.code === "resource_missing")
+          return null;
+        if (session.payment_intent && typeof session.payment_intent !== "string") {
+          return {
+            ...Payment$inboundSchema(
+              session.payment_intent
+            ),
+            id: data.id
+          };
+        }
+        return {
+          id: data.id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "pending",
+          metadata: core.omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: true,
+          payment_url: session.url
+        };
+      }
       const [payment, paymentError] = await core.tryCatchAsync(
         this.stripe.paymentIntents.retrieve(data.id)
       );
@@ -599,6 +642,10 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
           "deletePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        await this.stripe.checkout.sessions.expire(data.id);
+        return null;
+      }
       await this.stripe.paymentIntents.cancel(data.id);
       return null;
     };
@@ -611,12 +658,27 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
           "capturePayment"
         );
       }
-      const payment = await this.stripe.paymentIntents.capture(id, {
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.capture(piId, {
         amount_to_capture: data.amount
       });
-      return Payment$inboundSchema(payment);
+      return { ...Payment$inboundSchema(payment), id };
     };
     this.cancelPayment = async (id) => {
+      if (id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.expire(id);
+        return {
+          id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "canceled",
+          metadata: core.omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: false,
+          payment_url: null
+        };
+      }
       const canceledPayment = await this.stripe.paymentIntents.cancel(id);
       return Payment$inboundSchema(canceledPayment);
     };
@@ -646,7 +708,18 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         amount: rest.amount,
         metadata: core.stringifyMetadataValues(rest.metadata ?? {})
       };
-      if (data.payment_id.startsWith("pi_")) {
+      if (data.payment_id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.retrieve(
+          data.payment_id
+        );
+        if (!session.payment_intent) {
+          throw new core.ValidationError(
+            "Checkout Session has no associated PaymentIntent to refund",
+            { provider: this.providerName, method: "createRefund" }
+          );
+        }
+        stripeRefundOptions.payment_intent = typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+      } else if (data.payment_id.startsWith("pi_")) {
         stripeRefundOptions.payment_intent = data.payment_id;
       } else {
         stripeRefundOptions.charge = data.payment_id;
@@ -885,14 +958,29 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
       }
       return results;
     };
-    const { debug = true, apiKey, ...rest } = opts;
-    this.stripe = new Stripe__default.default(apiKey, rest);
-    this.opts = opts;
-    this.isSandbox = opts.isSandbox;
+    const { debug, apiKey, isSandbox, ...stripeConfig } = opts;
+    const resolvedSandbox = isSandbox ?? apiKey.includes("_test_");
+    this.stripe = new Stripe__default.default(apiKey, stripeConfig);
+    this.opts = { ...opts, debug: debug ?? resolvedSandbox };
+    this.isSandbox = resolvedSandbox;
   }
   get _native() {
     return this.stripe;
   }
+  async _resolvePaymentIntentId(id) {
+    if (!id.startsWith("cs_")) return id;
+    const session = await this.stripe.checkout.sessions.retrieve(id);
+    if (!session.payment_intent) {
+      throw new core.ValidationError(
+        "Checkout Session has no associated PaymentIntent yet",
+        {
+          provider: this.providerName,
+          method: "resolvePaymentIntentId"
+        }
+      );
+    }
+    return typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+  }
 };
 
 // src/index.ts
@@ -905,12 +993,10 @@ var stripe = () => {
     process.env ?? {},
     "Missing required environment variables: {keys}"
   );
-  const isSandbox = process.env.NODE_ENV === "development";
   return createStripe({
     apiKey: envVars.STRIPE_API_KEY,
-    isSandbox,
-    debug: isSandbox,
-    apiVersion: "2025-07-30.basil"
+    apiVersion: "2025-07-30.basil",
+    isSandbox: envVars.STRIPE_API_KEY.includes("_test_") || process.env.NODE_ENV !== "production"
   });
 };
 

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { schema, Schema, validateRequiredKeys, AbstractPayKitProvider, createCheckoutSchema, ValidationError, stringifyMetadataValues, isIdCustomer, isEmailCustomer, updateCheckoutSchema, ResourceNotFoundError, createCustomerSchema, parseCustomerName, createSubscriptionSchema, InvalidTypeError, updateSubscriptionSchema, retrieveSubscriptionSchema, createPaymentSchema, PAYKIT_METADATA_KEY, updatePaymentSchema, retrievePaymentSchema, tryCatchAsync, deletePaymentSchema, capturePaymentSchema, createRefundSchema, refundReasonMatcher, WebhookError, omitInternalMetadata, paykitEvent$InboundSchema, billingModeSchema, invoiceStatusSchema } from '@paykit-sdk/core';
+import { schema, Schema, validateRequiredKeys, AbstractPayKitProvider, createCheckoutSchema, ValidationError, stringifyMetadataValues, isIdCustomer, isEmailCustomer, updateCheckoutSchema, ResourceNotFoundError, createCustomerSchema, parseCustomerName, createSubscriptionSchema, InvalidTypeError, updateSubscriptionSchema, retrieveSubscriptionSchema, createPaymentSchema, PAYKIT_METADATA_KEY, updatePaymentSchema, retrievePaymentSchema, tryCatchAsync, omitInternalMetadata, deletePaymentSchema, capturePaymentSchema, createRefundSchema, refundReasonMatcher, WebhookError, paykitEvent$InboundSchema, billingModeSchema, invoiceStatusSchema } from '@paykit-sdk/core';
 import Stripe from 'stripe';
 
 // src/index.ts
@@ -283,19 +283,33 @@ var StripeProvider = class extends AbstractPayKitProvider {
         name: data.name,
         email: data.email
       });
+      const {
+        billing: _billing,
+        metadata,
+        provider_metadata,
+        name: _name,
+        ...stripeParams
+      } = data;
       const customer = await this.stripe.customers.create({
-        ...params,
-        phone: params.phone ?? void 0,
-        name: fullName
+        ...provider_metadata,
+        ...stripeParams,
+        phone: data.phone ?? void 0,
+        name: fullName,
+        metadata: stringifyMetadataValues(metadata ?? {})
       });
       return Customer$inboundSchema(customer);
     };
     this.updateCustomer = async (id, params) => {
-      const { provider_metadata, ...rest } = params;
+      const {
+        provider_metadata,
+        billing: _billing,
+        metadata,
+        ...rest
+      } = params;
       const customer = await this.stripe.customers.update(id, {
         ...provider_metadata,
         ...rest,
-        metadata: stringifyMetadataValues(rest.metadata ?? {}),
+        metadata: stringifyMetadataValues(metadata ?? {}),
         phone: rest.phone ?? void 0
       });
       return Customer$inboundSchema(customer);
@@ -541,7 +555,8 @@ var StripeProvider = class extends AbstractPayKitProvider {
         );
       }
       const { provider_metadata, customer, ...rest } = data;
-      const payment = await this.stripe.paymentIntents.retrieve(id);
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.retrieve(piId);
       const paymentOptions = {
         ...provider_metadata,
         metadata: stringifyMetadataValues({
@@ -563,10 +578,10 @@ var StripeProvider = class extends AbstractPayKitProvider {
         paymentOptions.receipt_email = customer.email;
       }
       const updatedPayment = await this.stripe.paymentIntents.update(
-        id,
+        piId,
         paymentOptions
       );
-      return Payment$inboundSchema(updatedPayment);
+      return { ...Payment$inboundSchema(updatedPayment), id };
     };
     this.retrievePayment = async (id) => {
       const { error, data } = retrievePaymentSchema.safeParse({ id });
@@ -577,6 +592,34 @@ var StripeProvider = class extends AbstractPayKitProvider {
           "retrievePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        const [session, sessionError] = await tryCatchAsync(
+          this.stripe.checkout.sessions.retrieve(data.id, {
+            expand: ["payment_intent"]
+          })
+        );
+        if (!session || sessionError?.code === "resource_missing")
+          return null;
+        if (session.payment_intent && typeof session.payment_intent !== "string") {
+          return {
+            ...Payment$inboundSchema(
+              session.payment_intent
+            ),
+            id: data.id
+          };
+        }
+        return {
+          id: data.id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "pending",
+          metadata: omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: true,
+          payment_url: session.url
+        };
+      }
       const [payment, paymentError] = await tryCatchAsync(
         this.stripe.paymentIntents.retrieve(data.id)
       );
@@ -593,6 +636,10 @@ var StripeProvider = class extends AbstractPayKitProvider {
           "deletePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        await this.stripe.checkout.sessions.expire(data.id);
+        return null;
+      }
       await this.stripe.paymentIntents.cancel(data.id);
       return null;
     };
@@ -605,12 +652,27 @@ var StripeProvider = class extends AbstractPayKitProvider {
           "capturePayment"
         );
       }
-      const payment = await this.stripe.paymentIntents.capture(id, {
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.capture(piId, {
         amount_to_capture: data.amount
       });
-      return Payment$inboundSchema(payment);
+      return { ...Payment$inboundSchema(payment), id };
     };
     this.cancelPayment = async (id) => {
+      if (id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.expire(id);
+        return {
+          id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "canceled",
+          metadata: omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: false,
+          payment_url: null
+        };
+      }
       const canceledPayment = await this.stripe.paymentIntents.cancel(id);
       return Payment$inboundSchema(canceledPayment);
     };
@@ -640,7 +702,18 @@ var StripeProvider = class extends AbstractPayKitProvider {
         amount: rest.amount,
         metadata: stringifyMetadataValues(rest.metadata ?? {})
       };
-      if (data.payment_id.startsWith("pi_")) {
+      if (data.payment_id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.retrieve(
+          data.payment_id
+        );
+        if (!session.payment_intent) {
+          throw new ValidationError(
+            "Checkout Session has no associated PaymentIntent to refund",
+            { provider: this.providerName, method: "createRefund" }
+          );
+        }
+        stripeRefundOptions.payment_intent = typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+      } else if (data.payment_id.startsWith("pi_")) {
         stripeRefundOptions.payment_intent = data.payment_id;
       } else {
         stripeRefundOptions.charge = data.payment_id;
@@ -879,14 +952,29 @@ var StripeProvider = class extends AbstractPayKitProvider {
       }
       return results;
     };
-    const { debug = true, apiKey, ...rest } = opts;
-    this.stripe = new Stripe(apiKey, rest);
-    this.opts = opts;
-    this.isSandbox = opts.isSandbox;
+    const { debug, apiKey, isSandbox, ...stripeConfig } = opts;
+    const resolvedSandbox = isSandbox ?? apiKey.includes("_test_");
+    this.stripe = new Stripe(apiKey, stripeConfig);
+    this.opts = { ...opts, debug: debug ?? resolvedSandbox };
+    this.isSandbox = resolvedSandbox;
   }
   get _native() {
     return this.stripe;
   }
+  async _resolvePaymentIntentId(id) {
+    if (!id.startsWith("cs_")) return id;
+    const session = await this.stripe.checkout.sessions.retrieve(id);
+    if (!session.payment_intent) {
+      throw new ValidationError(
+        "Checkout Session has no associated PaymentIntent yet",
+        {
+          provider: this.providerName,
+          method: "resolvePaymentIntentId"
+        }
+      );
+    }
+    return typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+  }
 };
 
 // src/index.ts
@@ -899,12 +987,10 @@ var stripe = () => {
     process.env ?? {},
     "Missing required environment variables: {keys}"
   );
-  const isSandbox = process.env.NODE_ENV === "development";
   return createStripe({
     apiKey: envVars.STRIPE_API_KEY,
-    isSandbox,
-    debug: isSandbox,
-    apiVersion: "2025-07-30.basil"
+    apiVersion: "2025-07-30.basil",
+    isSandbox: envVars.STRIPE_API_KEY.includes("_test_") || process.env.NODE_ENV !== "production"
   });
 };
 

package/dist/stripe-provider.d.mts

@@ -9,6 +9,7 @@ interface StripeMetadata extends ProviderMetadataRegistry {
     refund: Stripe.RefundCreateParams;
 }
 interface StripeOptions extends PaykitProviderOptions, Stripe.StripeConfig {
+    /** Stripe secret key (sk_test_... or sk_live_...) */
     apiKey: string;
 }
 type StripeRawEvents = {
@@ -23,6 +24,7 @@ declare class StripeProvider extends AbstractPayKitProvider implements PayKitPro
     constructor(opts: StripeOptions);
     readonly providerName = "stripe";
     get _native(): Stripe;
+    private _resolvePaymentIntentId;
     createCheckout: (params: CreateCheckoutSchema<StripeMetadata["checkout"]>) => Promise<Checkout>;
     retrieveCheckout: (id: string) => Promise<Checkout>;
     updateCheckout: (id: string, params: UpdateCheckoutSchema) => Promise<Checkout>;

package/dist/stripe-provider.d.ts

@@ -9,6 +9,7 @@ interface StripeMetadata extends ProviderMetadataRegistry {
     refund: Stripe.RefundCreateParams;
 }
 interface StripeOptions extends PaykitProviderOptions, Stripe.StripeConfig {
+    /** Stripe secret key (sk_test_... or sk_live_...) */
     apiKey: string;
 }
 type StripeRawEvents = {
@@ -23,6 +24,7 @@ declare class StripeProvider extends AbstractPayKitProvider implements PayKitPro
     constructor(opts: StripeOptions);
     readonly providerName = "stripe";
     get _native(): Stripe;
+    private _resolvePaymentIntentId;
     createCheckout: (params: CreateCheckoutSchema<StripeMetadata["checkout"]>) => Promise<Checkout>;
     retrieveCheckout: (id: string) => Promise<Checkout>;
     updateCheckout: (id: string, params: UpdateCheckoutSchema) => Promise<Checkout>;

package/dist/stripe-provider.js

@@ -289,19 +289,33 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         name: data.name,
         email: data.email
       });
+      const {
+        billing: _billing,
+        metadata,
+        provider_metadata,
+        name: _name,
+        ...stripeParams
+      } = data;
       const customer = await this.stripe.customers.create({
-        ...params,
-        phone: params.phone ?? void 0,
-        name: fullName
+        ...provider_metadata,
+        ...stripeParams,
+        phone: data.phone ?? void 0,
+        name: fullName,
+        metadata: core.stringifyMetadataValues(metadata ?? {})
       });
       return Customer$inboundSchema(customer);
     };
     this.updateCustomer = async (id, params) => {
-      const { provider_metadata, ...rest } = params;
+      const {
+        provider_metadata,
+        billing: _billing,
+        metadata,
+        ...rest
+      } = params;
       const customer = await this.stripe.customers.update(id, {
         ...provider_metadata,
         ...rest,
-        metadata: core.stringifyMetadataValues(rest.metadata ?? {}),
+        metadata: core.stringifyMetadataValues(metadata ?? {}),
         phone: rest.phone ?? void 0
       });
       return Customer$inboundSchema(customer);
@@ -547,7 +561,8 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         );
       }
       const { provider_metadata, customer, ...rest } = data;
-      const payment = await this.stripe.paymentIntents.retrieve(id);
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.retrieve(piId);
       const paymentOptions = {
         ...provider_metadata,
         metadata: core.stringifyMetadataValues({
@@ -569,10 +584,10 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         paymentOptions.receipt_email = customer.email;
       }
       const updatedPayment = await this.stripe.paymentIntents.update(
-        id,
+        piId,
         paymentOptions
       );
-      return Payment$inboundSchema(updatedPayment);
+      return { ...Payment$inboundSchema(updatedPayment), id };
     };
     this.retrievePayment = async (id) => {
       const { error, data } = core.retrievePaymentSchema.safeParse({ id });
@@ -583,6 +598,34 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
           "retrievePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        const [session, sessionError] = await core.tryCatchAsync(
+          this.stripe.checkout.sessions.retrieve(data.id, {
+            expand: ["payment_intent"]
+          })
+        );
+        if (!session || sessionError?.code === "resource_missing")
+          return null;
+        if (session.payment_intent && typeof session.payment_intent !== "string") {
+          return {
+            ...Payment$inboundSchema(
+              session.payment_intent
+            ),
+            id: data.id
+          };
+        }
+        return {
+          id: data.id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "pending",
+          metadata: core.omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: true,
+          payment_url: session.url
+        };
+      }
       const [payment, paymentError] = await core.tryCatchAsync(
         this.stripe.paymentIntents.retrieve(data.id)
       );
@@ -599,6 +642,10 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
           "deletePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        await this.stripe.checkout.sessions.expire(data.id);
+        return null;
+      }
       await this.stripe.paymentIntents.cancel(data.id);
       return null;
     };
@@ -611,12 +658,27 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
           "capturePayment"
         );
       }
-      const payment = await this.stripe.paymentIntents.capture(id, {
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.capture(piId, {
         amount_to_capture: data.amount
       });
-      return Payment$inboundSchema(payment);
+      return { ...Payment$inboundSchema(payment), id };
     };
     this.cancelPayment = async (id) => {
+      if (id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.expire(id);
+        return {
+          id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "canceled",
+          metadata: core.omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: false,
+          payment_url: null
+        };
+      }
       const canceledPayment = await this.stripe.paymentIntents.cancel(id);
       return Payment$inboundSchema(canceledPayment);
     };
@@ -646,7 +708,18 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
         amount: rest.amount,
         metadata: core.stringifyMetadataValues(rest.metadata ?? {})
       };
-      if (data.payment_id.startsWith("pi_")) {
+      if (data.payment_id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.retrieve(
+          data.payment_id
+        );
+        if (!session.payment_intent) {
+          throw new core.ValidationError(
+            "Checkout Session has no associated PaymentIntent to refund",
+            { provider: this.providerName, method: "createRefund" }
+          );
+        }
+        stripeRefundOptions.payment_intent = typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+      } else if (data.payment_id.startsWith("pi_")) {
         stripeRefundOptions.payment_intent = data.payment_id;
       } else {
         stripeRefundOptions.charge = data.payment_id;
@@ -885,14 +958,29 @@ var StripeProvider = class extends core.AbstractPayKitProvider {
       }
       return results;
     };
-    const { debug = true, apiKey, ...rest } = opts;
-    this.stripe = new Stripe__default.default(apiKey, rest);
-    this.opts = opts;
-    this.isSandbox = opts.isSandbox;
+    const { debug, apiKey, isSandbox, ...stripeConfig } = opts;
+    const resolvedSandbox = isSandbox ?? apiKey.includes("_test_");
+    this.stripe = new Stripe__default.default(apiKey, stripeConfig);
+    this.opts = { ...opts, debug: debug ?? resolvedSandbox };
+    this.isSandbox = resolvedSandbox;
   }
   get _native() {
     return this.stripe;
   }
+  async _resolvePaymentIntentId(id) {
+    if (!id.startsWith("cs_")) return id;
+    const session = await this.stripe.checkout.sessions.retrieve(id);
+    if (!session.payment_intent) {
+      throw new core.ValidationError(
+        "Checkout Session has no associated PaymentIntent yet",
+        {
+          provider: this.providerName,
+          method: "resolvePaymentIntentId"
+        }
+      );
+    }
+    return typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+  }
 };
 
 exports.StripeProvider = StripeProvider;

package/dist/stripe-provider.mjs

@@ -1,4 +1,4 @@
-import { schema, Schema, AbstractPayKitProvider, createCheckoutSchema, ValidationError, stringifyMetadataValues, isIdCustomer, isEmailCustomer, updateCheckoutSchema, ResourceNotFoundError, createCustomerSchema, parseCustomerName, createSubscriptionSchema, InvalidTypeError, updateSubscriptionSchema, retrieveSubscriptionSchema, createPaymentSchema, PAYKIT_METADATA_KEY, updatePaymentSchema, retrievePaymentSchema, tryCatchAsync, deletePaymentSchema, capturePaymentSchema, createRefundSchema, refundReasonMatcher, WebhookError, validateRequiredKeys, omitInternalMetadata, paykitEvent$InboundSchema, billingModeSchema, invoiceStatusSchema } from '@paykit-sdk/core';
+import { schema, Schema, AbstractPayKitProvider, createCheckoutSchema, ValidationError, stringifyMetadataValues, isIdCustomer, isEmailCustomer, updateCheckoutSchema, ResourceNotFoundError, createCustomerSchema, parseCustomerName, createSubscriptionSchema, InvalidTypeError, updateSubscriptionSchema, retrieveSubscriptionSchema, createPaymentSchema, PAYKIT_METADATA_KEY, updatePaymentSchema, retrievePaymentSchema, tryCatchAsync, omitInternalMetadata, deletePaymentSchema, capturePaymentSchema, createRefundSchema, refundReasonMatcher, WebhookError, validateRequiredKeys, paykitEvent$InboundSchema, billingModeSchema, invoiceStatusSchema } from '@paykit-sdk/core';
 import Stripe from 'stripe';
 
 // src/stripe-provider.ts
@@ -283,19 +283,33 @@ var StripeProvider = class extends AbstractPayKitProvider {
         name: data.name,
         email: data.email
       });
+      const {
+        billing: _billing,
+        metadata,
+        provider_metadata,
+        name: _name,
+        ...stripeParams
+      } = data;
       const customer = await this.stripe.customers.create({
-        ...params,
-        phone: params.phone ?? void 0,
-        name: fullName
+        ...provider_metadata,
+        ...stripeParams,
+        phone: data.phone ?? void 0,
+        name: fullName,
+        metadata: stringifyMetadataValues(metadata ?? {})
       });
       return Customer$inboundSchema(customer);
     };
     this.updateCustomer = async (id, params) => {
-      const { provider_metadata, ...rest } = params;
+      const {
+        provider_metadata,
+        billing: _billing,
+        metadata,
+        ...rest
+      } = params;
       const customer = await this.stripe.customers.update(id, {
         ...provider_metadata,
         ...rest,
-        metadata: stringifyMetadataValues(rest.metadata ?? {}),
+        metadata: stringifyMetadataValues(metadata ?? {}),
         phone: rest.phone ?? void 0
       });
       return Customer$inboundSchema(customer);
@@ -541,7 +555,8 @@ var StripeProvider = class extends AbstractPayKitProvider {
         );
       }
       const { provider_metadata, customer, ...rest } = data;
-      const payment = await this.stripe.paymentIntents.retrieve(id);
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.retrieve(piId);
       const paymentOptions = {
         ...provider_metadata,
         metadata: stringifyMetadataValues({
@@ -563,10 +578,10 @@ var StripeProvider = class extends AbstractPayKitProvider {
         paymentOptions.receipt_email = customer.email;
       }
       const updatedPayment = await this.stripe.paymentIntents.update(
-        id,
+        piId,
         paymentOptions
       );
-      return Payment$inboundSchema(updatedPayment);
+      return { ...Payment$inboundSchema(updatedPayment), id };
     };
     this.retrievePayment = async (id) => {
       const { error, data } = retrievePaymentSchema.safeParse({ id });
@@ -577,6 +592,34 @@ var StripeProvider = class extends AbstractPayKitProvider {
           "retrievePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        const [session, sessionError] = await tryCatchAsync(
+          this.stripe.checkout.sessions.retrieve(data.id, {
+            expand: ["payment_intent"]
+          })
+        );
+        if (!session || sessionError?.code === "resource_missing")
+          return null;
+        if (session.payment_intent && typeof session.payment_intent !== "string") {
+          return {
+            ...Payment$inboundSchema(
+              session.payment_intent
+            ),
+            id: data.id
+          };
+        }
+        return {
+          id: data.id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "pending",
+          metadata: omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: true,
+          payment_url: session.url
+        };
+      }
       const [payment, paymentError] = await tryCatchAsync(
         this.stripe.paymentIntents.retrieve(data.id)
       );
@@ -593,6 +636,10 @@ var StripeProvider = class extends AbstractPayKitProvider {
           "deletePayment"
         );
       }
+      if (data.id.startsWith("cs_")) {
+        await this.stripe.checkout.sessions.expire(data.id);
+        return null;
+      }
       await this.stripe.paymentIntents.cancel(data.id);
       return null;
     };
@@ -605,12 +652,27 @@ var StripeProvider = class extends AbstractPayKitProvider {
           "capturePayment"
         );
       }
-      const payment = await this.stripe.paymentIntents.capture(id, {
+      const piId = await this._resolvePaymentIntentId(id);
+      const payment = await this.stripe.paymentIntents.capture(piId, {
         amount_to_capture: data.amount
       });
-      return Payment$inboundSchema(payment);
+      return { ...Payment$inboundSchema(payment), id };
     };
     this.cancelPayment = async (id) => {
+      if (id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.expire(id);
+        return {
+          id,
+          amount: session.amount_total ?? 0,
+          currency: session.currency ?? "",
+          customer: typeof session.customer === "string" ? { id: session.customer } : session.customer?.id ? { id: session.customer.id } : session.customer_email ? { email: session.customer_email } : null,
+          status: "canceled",
+          metadata: omitInternalMetadata(session.metadata ?? {}),
+          item_id: null,
+          requires_action: false,
+          payment_url: null
+        };
+      }
       const canceledPayment = await this.stripe.paymentIntents.cancel(id);
       return Payment$inboundSchema(canceledPayment);
     };
@@ -640,7 +702,18 @@ var StripeProvider = class extends AbstractPayKitProvider {
         amount: rest.amount,
         metadata: stringifyMetadataValues(rest.metadata ?? {})
       };
-      if (data.payment_id.startsWith("pi_")) {
+      if (data.payment_id.startsWith("cs_")) {
+        const session = await this.stripe.checkout.sessions.retrieve(
+          data.payment_id
+        );
+        if (!session.payment_intent) {
+          throw new ValidationError(
+            "Checkout Session has no associated PaymentIntent to refund",
+            { provider: this.providerName, method: "createRefund" }
+          );
+        }
+        stripeRefundOptions.payment_intent = typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+      } else if (data.payment_id.startsWith("pi_")) {
         stripeRefundOptions.payment_intent = data.payment_id;
       } else {
         stripeRefundOptions.charge = data.payment_id;
@@ -879,14 +952,29 @@ var StripeProvider = class extends AbstractPayKitProvider {
       }
       return results;
     };
-    const { debug = true, apiKey, ...rest } = opts;
-    this.stripe = new Stripe(apiKey, rest);
-    this.opts = opts;
-    this.isSandbox = opts.isSandbox;
+    const { debug, apiKey, isSandbox, ...stripeConfig } = opts;
+    const resolvedSandbox = isSandbox ?? apiKey.includes("_test_");
+    this.stripe = new Stripe(apiKey, stripeConfig);
+    this.opts = { ...opts, debug: debug ?? resolvedSandbox };
+    this.isSandbox = resolvedSandbox;
   }
   get _native() {
     return this.stripe;
   }
+  async _resolvePaymentIntentId(id) {
+    if (!id.startsWith("cs_")) return id;
+    const session = await this.stripe.checkout.sessions.retrieve(id);
+    if (!session.payment_intent) {
+      throw new ValidationError(
+        "Checkout Session has no associated PaymentIntent yet",
+        {
+          provider: this.providerName,
+          method: "resolvePaymentIntentId"
+        }
+      );
+    }
+    return typeof session.payment_intent === "string" ? session.payment_intent : session.payment_intent.id;
+  }
 };
 
 export { StripeProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paykit-sdk/stripe",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Stripe provider for PayKit",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -26,7 +26,7 @@
     "stripe": "^18.2.1"
   },
   "peerDependencies": {
-    "@paykit-sdk/core": ">=1.2.0"
+    "@paykit-sdk/core": ">=1.2.2"
   },
   "devDependencies": {
     "@paykit-sdk/core": "workspace:*",