payment-kit 1.26.4 → 1.26.5

package/api/src/routes/checkout-sessions.ts

@@ -1539,6 +1539,83 @@ router.post('/:id/abort-stripe', user, ensureCheckoutSessionOpen, async (req, re
   }
 });
 
+// Skip payment method for $0 subscription — user chose "Skip, bind later"
+// Keeps the subscription but sets cancel_at_period_end so it won't renew without a payment method
+router.post('/:id/skip-payment-method', user, ensureCheckoutSessionOpen, async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(403).json({ code: 'REQUIRE_LOGIN', error: 'Please login to continue' });
+    }
+
+    const checkoutSession = req.doc as CheckoutSession;
+
+    if (!['subscription', 'setup'].includes(checkoutSession.mode)) {
+      return res.status(400).json({ error: 'Skip payment method is only supported for subscriptions' });
+    }
+
+    const subscriptionIds = getCheckoutSessionSubscriptionIds(checkoutSession);
+    const subscriptions = await Subscription.findAll({ where: { id: subscriptionIds } });
+
+    if (!subscriptions.length) {
+      return res.status(400).json({ error: 'No subscriptions found for this checkout session' });
+    }
+
+    // Cancel Stripe setup intents and activate subscriptions concurrently
+    await Promise.all(
+      subscriptions.map(async (sub) => {
+        const stripeSubId = sub.payment_details?.stripe?.subscription_id;
+        if (stripeSubId) {
+          const method = await PaymentMethod.findByPk(sub.default_payment_method_id);
+          if (method?.type === 'stripe') {
+            const client = method.getStripeClient();
+            try {
+              const stripeSub = await client.subscriptions.retrieve(stripeSubId, {
+                expand: ['pending_setup_intent'],
+              });
+              if (stripeSub.pending_setup_intent && typeof stripeSub.pending_setup_intent !== 'string') {
+                await client.setupIntents.cancel(stripeSub.pending_setup_intent.id);
+              }
+              await client.subscriptions.update(stripeSubId, { cancel_at_period_end: true });
+            } catch (err: any) {
+              logger.error('Failed to update Stripe subscription for skip-payment-method', {
+                checkoutSessionId: checkoutSession.id,
+                subscriptionId: sub.id,
+                stripeSubId,
+                error: err.message,
+              });
+            }
+          }
+        }
+
+        // Activate the local subscription with cancel_at_period_end
+        await sub.update({
+          status: sub.trial_end && sub.trial_end > Date.now() / 1000 ? 'trialing' : 'active',
+          cancel_at_period_end: true,
+        });
+        await addSubscriptionJob(sub, 'cycle', false, sub.trial_end);
+      })
+    );
+
+    // Complete the checkout session
+    await checkoutSession.update({
+      status: 'complete',
+      payment_status: 'no_payment_required',
+    });
+
+    return res.json({
+      checkoutSession: { id: checkoutSession.id, status: 'complete' },
+      skipped: true,
+    });
+  } catch (err: any) {
+    logger.error('Error in skip-payment-method', {
+      sessionId: req.params.id,
+      error: err.message,
+      stack: err.stack,
+    });
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // for checkout page
 router.get('/retrieve/:id', user, async (req, res) => {
   const doc = await CheckoutSession.findByPk(req.params.id);

package/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/payment-kit.git
 specVersion: 1.2.8
-version: 1.26.4
+version: 1.26.5
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.26.4",
+  "version": "1.26.5",
   "scripts": {
     "dev": "blocklet dev --open",
     "prelint": "npm run types",
@@ -59,9 +59,9 @@
     "@blocklet/error": "^0.3.5",
     "@blocklet/js-sdk": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@blocklet/logger": "^1.17.8-beta-20260104-120132-cb5b1914",
-    "@blocklet/payment-broker-client": "1.26.4",
-    "@blocklet/payment-react": "1.26.4",
-    "@blocklet/payment-vendor": "1.26.4",
+    "@blocklet/payment-broker-client": "1.26.5",
+    "@blocklet/payment-react": "1.26.5",
+    "@blocklet/payment-vendor": "1.26.5",
     "@blocklet/sdk": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@blocklet/ui-react": "^3.5.1",
     "@blocklet/uploader": "^0.3.19",
@@ -132,7 +132,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.26.4",
+    "@blocklet/payment-types": "1.26.5",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -179,5 +179,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "90fb554f2edfcd1c141e3887eef835b1a545f5ad"
+  "gitHead": "2d208818d218494407989dd8cd460ab51d075952"
 }

package/src/components/payment-link/actions.tsx

@@ -82,6 +82,26 @@ export default function PaymentLinkActions({ data, variant = 'compact', onChange
       setState({ loading: false, action: '' });
     }
   };
+  const onToggleSkipPaymentMethod = async () => {
+    const currentMetadata = (data.metadata || {}) as Record<string, any>;
+    const isEnabled = currentMetadata.allow_skip_payment_method === 'true';
+    try {
+      setState({ loading: true });
+      await api
+        .put(`/api/payment-links/${data.id}`, {
+          metadata: { ...currentMetadata, allow_skip_payment_method: isEnabled ? 'false' : 'true' },
+        })
+        .then((res: any) => res.data);
+      Toast.success(t('common.saved'));
+      onChange(state.action);
+    } catch (err) {
+      console.error(err);
+      Toast.error(formatError(err));
+    } finally {
+      setState({ loading: false, action: '' });
+    }
+  };
+
   const onCopyLink = () => {
     Copy(joinURL(window.blocklet.appUrl, window.blocklet.prefix, `/checkout/pay/${data.id}`));
     Toast.success(t('common.copied'));
@@ -127,6 +147,14 @@ export default function PaymentLinkActions({ data, variant = 'compact', onChange
             handler: () => setState({ action: 'togglePromotionCodes' }),
             color: 'primary',
           },
+          {
+            label:
+              (data.metadata as Record<string, any>)?.allow_skip_payment_method === 'true'
+                ? t('admin.paymentLink.disableSkipPaymentMethod')
+                : t('admin.paymentLink.enableSkipPaymentMethod'),
+            handler: () => setState({ action: 'toggleSkipPaymentMethod' }),
+            color: 'primary',
+          },
           {
             label: t('admin.passport.assign'),
             handler: () => setState({ action: 'assign' }),
@@ -162,6 +190,23 @@ export default function PaymentLinkActions({ data, variant = 'compact', onChange
           loading={state.loading}
         />
       )}
+      {state.action === 'toggleSkipPaymentMethod' && (
+        <ConfirmDialog
+          onConfirm={onToggleSkipPaymentMethod}
+          onCancel={() => setState({ action: '' })}
+          title={
+            (data.metadata as Record<string, any>)?.allow_skip_payment_method === 'true'
+              ? t('admin.paymentLink.disableSkipPaymentMethod')
+              : t('admin.paymentLink.enableSkipPaymentMethod')
+          }
+          message={
+            (data.metadata as Record<string, any>)?.allow_skip_payment_method === 'true'
+              ? t('admin.paymentLink.disableSkipPaymentMethodTip')
+              : t('admin.paymentLink.enableSkipPaymentMethodTip')
+          }
+          loading={state.loading}
+        />
+      )}
       {state.action === 'togglePromotionCodes' && (
         <ConfirmDialog
           onConfirm={onTogglePromotionCodes}

package/src/components/payment-link/before-pay.tsx

@@ -279,6 +279,30 @@ export default function BeforePay({
           );
         }}
       />
+      <Controller
+        name="metadata"
+        control={control}
+        render={({ field }) => {
+          const metadata = field.value || {};
+          const isChecked = metadata.allow_skip_payment_method === 'true';
+
+          return (
+            <FormControlLabel
+              control={
+                <Checkbox
+                  checked={isChecked}
+                  onChange={(_, checked) => {
+                    const newMetadata = { ...metadata };
+                    newMetadata.allow_skip_payment_method = checked ? 'true' : 'false';
+                    field.onChange(newMetadata);
+                  }}
+                />
+              }
+              label={t('admin.paymentLink.allowSkipPaymentMethod')}
+            />
+          );
+        }}
+      />
       {includeFreeTrial && (
         <Controller
           name="subscription_data.trial_period_days"

package/src/components/subscription/payment-method-info.tsx

@@ -133,12 +133,7 @@ export default function PaymentMethodInfo({
     setState({ editing: false, clientSecret: null, publishableKey: null, setupIntentId: null });
   };
 
-  if (!paymentMethodDetails) {
-    return null;
-  }
-
-  const { card, link, us_bank_account: usBankAccount, payer, type } = paymentMethodDetails;
-
+  // Stripe form for editing/binding — must be checked before early returns
   if (state.editing && state.clientSecret && state.publishableKey) {
     return (
       <Box>
@@ -156,6 +151,28 @@ export default function PaymentMethodInfo({
     );
   }
 
+  if (!paymentMethodDetails) {
+    if (!editable) {
+      return (
+        <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+          {t('admin.subscription.noPaymentMethod', { defaultValue: 'Not bound' })}
+        </Typography>
+      );
+    }
+    return (
+      <Stack direction="row" spacing={1} sx={{ alignItems: 'center' }}>
+        <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+          {t('admin.subscription.noPaymentMethod', { defaultValue: 'Not bound' })}
+        </Typography>
+        <Button variant="text" size="small" sx={{ color: 'text.link' }} loading={state.submitting} onClick={handleEdit}>
+          {t('admin.subscription.bindPaymentMethod', { defaultValue: 'Bind now' })}
+        </Button>
+      </Stack>
+    );
+  }
+
+  const { card, link, us_bank_account: usBankAccount, payer, type } = paymentMethodDetails;
+
   const renderPaymentMethodInfo = () => {
     if (type === 'card' && card) {
       return (

package/src/components/subscription/portal/actions.tsx

@@ -534,6 +534,8 @@ export function SubscriptionActionsInner({
           e?.stopPropagation();
           if (action?.action === 'pastDue') {
             navigate(`/customer/invoice/past-due?subscription=${subscription.id}`);
+          } else if (action?.action === 'recover' && !(subscription as any).paymentMethodDetails) {
+            Toast.error(t('admin.subscription.bindPaymentMethodFirst'));
           } else {
             // @ts-ignore
             setState({ action: action?.action, subscription: subscription.id });

package/src/locales/en.tsx

@@ -1080,6 +1080,12 @@ export default flat({
       includeFreeTrial: 'Include a free trial',
       noStakeRequired: 'No stake required',
       showProductFeatures: 'Show product features',
+      allowSkipPaymentMethod: 'Allow skipping payment method for $0 checkout',
+      enableSkipPaymentMethod: 'Allow skipping payment method',
+      disableSkipPaymentMethod: 'Require payment method',
+      enableSkipPaymentMethodTip:
+        'Allow customers to skip binding a payment method when the checkout amount is $0. The subscription will auto-cancel at the end of the current period if no payment method is added.',
+      disableSkipPaymentMethodTip: 'Require customers to provide a payment method even when the checkout amount is $0.',
       freeTrialDaysPositive: 'Free trial days must be positive',
       includeCustomFields: 'Add custom fields',
       confirmPage: 'Confirmation Page',
@@ -1568,6 +1574,11 @@ export default flat({
         button: 'Pay due invoices',
       },
       payerAddress: 'Payment Address',
+      noPaymentMethod: 'Not bound',
+      bindPaymentMethod: 'Bind now',
+      bindPaymentMethodFirst: 'Please bind a payment method first before resuming the subscription',
+      noPaymentMethodWarning:
+        'No payment method is bound to this subscription. Please bind one to avoid cancellation at the end of the current period.',
       changePayer: {
         btn: 'Change',
         stripe: {

package/src/locales/zh.tsx

@@ -1041,6 +1041,12 @@ export default flat({
       includeFreeTrial: '包含免费试用',
       noStakeRequired: '无需质押',
       showProductFeatures: '显示产品特性',
+      allowSkipPaymentMethod: '允许 $0 结账时跳过绑定支付方式',
+      enableSkipPaymentMethod: '允许跳过支付方式',
+      disableSkipPaymentMethod: '要求绑定支付方式',
+      enableSkipPaymentMethodTip:
+        '当结账金额为 $0 时，允许客户跳过绑定支付方式。若未绑定，订阅将在当前周期结束时自动取消。',
+      disableSkipPaymentMethodTip: '即使结账金额为 $0，也要求客户提供支付方式。',
       freeTrialDaysPositive: '免费试用天数必须是正数',
       includeCustomFields: '添加自定义字段',
       requireCrossSell: '用户必须选择交叉销售的商品（如果有的话）',
@@ -1533,6 +1539,10 @@ export default flat({
         button: '批量付款',
       },
       payerAddress: '扣费地址',
+      noPaymentMethod: '未绑定',
+      bindPaymentMethod: '立即绑定',
+      bindPaymentMethodFirst: '请先绑定支付方式后再恢复订阅',
+      noPaymentMethodWarning: '当前订阅未绑定支付方式，请尽快绑定，否则订阅将在当前周期结束时自动取消。',
       changePayer: {
         btn: '变更',
         stripe: {

package/src/pages/admin/products/links/detail.tsx

@@ -372,6 +372,14 @@ export default function PaymentLinkDetail(props: { id: string }) {
                     value={data.phone_number_collection?.enabled ? t('common.yes') : t('common.no')}
                   />
 
+                  <InfoRow
+                    label={t('admin.paymentLink.allowSkipPaymentMethod')}
+                    value={
+                      (data.metadata as Record<string, any>)?.allow_skip_payment_method === 'true'
+                        ? t('common.yes')
+                        : t('common.no')
+                    }
+                  />
                   <InfoRow
                     label={t('admin.paymentLink.showConfirmPage')}
                     value={renderConfirmPage(data.after_completion)}

package/src/pages/customer/subscription/detail.tsx

@@ -454,6 +454,11 @@ export default function CustomerSubscriptionDetail() {
     <>
       <Root>
         <Box>
+          {!(data as any).paymentMethodDetails && ['active', 'trialing'].includes(data.status) && (
+            <Alert severity="warning" sx={{ mb: 2 }}>
+              {t('admin.subscription.noPaymentMethodWarning')}
+            </Alert>
+          )}
           {hasUnpaid && (
             <Alert severity="error" sx={{ mb: 2 }}>
               {t('customer.unpaidInvoicesWarningTip')}
@@ -820,24 +825,22 @@ export default function CustomerSubscriptionDetail() {
                 }
               />
             )}
-            {(data as any).paymentMethodDetails && (
-              <InfoRow
-                label={t('admin.subscription.payerAddress')}
-                value={
-                  <PaymentMethodInfo
-                    subscriptionId={id}
-                    customer={data.customer}
-                    paymentMethodDetails={(data as any).paymentMethodDetails}
-                    editable={['active', 'trialing', 'past_due'].includes(data.status)}
-                    onUpdate={() => {
-                      refresh();
-                      checkUnpaidInvoices();
-                    }}
-                    paymentMethodType={data.paymentMethod?.type}
-                  />
-                }
-              />
-            )}
+            <InfoRow
+              label={t('admin.subscription.payerAddress')}
+              value={
+                <PaymentMethodInfo
+                  subscriptionId={id}
+                  customer={data.customer}
+                  paymentMethodDetails={(data as any).paymentMethodDetails}
+                  editable={['active', 'trialing', 'past_due'].includes(data.status)}
+                  onUpdate={() => {
+                    refresh();
+                    checkUnpaidInvoices();
+                  }}
+                  paymentMethodType={data.paymentMethod?.type}
+                />
+              }
+            />
 
             {data.payment_details && hasDelegateTxHash(data.payment_details, data.paymentMethod) && (
               <InfoRow