payment-kit 1.18.48 → 1.18.50

package/api/src/libs/invoice.ts

@@ -1119,3 +1119,234 @@ export async function retryUncollectibleInvoices(options: {
     logger.info('Released retry uncollectible lock', { lockKey });
   }
 }
+
+/**
+ * Migrate billing when a subscription's payment method changes.
+ * Steps:
+ * 1. Check if all subscription items are prepaid (licensed recurring).
+ * 2. If so, check if there is an unpaid invoice for the current period with the old payment method.
+ * 3. If such an invoice exists, void the old invoice and cancel its payment intent if present.
+ * 4. Create a new invoice for the current period with the new payment method.
+ * 5. If any step fails, throw an error and log details.
+ *
+ * @param subscription Subscription instance
+ * @param oldCurrencyId Old payment currency ID
+ * @param newCurrencyId New payment currency ID
+ * @returns Migration result: { migrated, oldInvoice, newInvoice }
+ */
+export const migrateSubscriptionPaymentMethodInvoice = async (
+  subscription: Subscription,
+  oldCurrencyId: string,
+  newCurrencyId: string
+) => {
+  // 1. Check if all subscription items are prepaid (licensed recurring)
+  const subscriptionItems = await SubscriptionItem.findAll({
+    where: { subscription_id: subscription.id },
+    include: [{ model: Price, as: 'price' }],
+  });
+
+  const subscriptionItemsExpanded = await Price.expand(subscriptionItems.map((x) => x.toJSON()));
+  const isPrepaid = subscriptionItemsExpanded.every((item: TLineItemExpanded) => {
+    const price = getSubscriptionItemPrice(item);
+    return price.type === 'recurring' && price.recurring?.usage_type === 'licensed';
+  });
+
+  if (!isPrepaid) {
+    logger.info('Skip billing migration for non-prepaid items', {
+      subscriptionId: subscription.id,
+    });
+    return { migrated: false, reason: 'has_non_prepaid_items' };
+  }
+
+  // 2. Find unpaid invoice for the current period with the old payment method
+  const currentPeriodInvoice = await Invoice.findOne({
+    where: {
+      subscription_id: subscription.id,
+      billing_reason: 'subscription_cycle',
+      status: ['open', 'uncollectible'],
+      currency_id: oldCurrencyId,
+      period_start: {
+        [Op.gte]: subscription.current_period_start,
+        [Op.lt]: subscription.current_period_end,
+      },
+    },
+    order: [['created_at', 'DESC']],
+  });
+
+  let voidedInvoice: Invoice | null = null;
+
+  if (!currentPeriodInvoice) {
+    voidedInvoice = await Invoice.findOne({
+      where: {
+        subscription_id: subscription.id,
+        billing_reason: 'subscription_cycle',
+        status: 'void',
+        currency_id: oldCurrencyId,
+        period_start: {
+          [Op.gte]: subscription.current_period_start,
+          [Op.lt]: subscription.current_period_end,
+        },
+      },
+      order: [['created_at', 'DESC']],
+    });
+    if (!voidedInvoice) {
+      logger.info('Skip billing migration for no unpaid invoice', {
+        subscriptionId: subscription.id,
+        periodStart: subscription.current_period_start,
+        periodEnd: subscription.current_period_end,
+        oldCurrencyId,
+      });
+      return { migrated: false, reason: 'no_unpaid_invoice' };
+    }
+  }
+
+  // 3. Get old and new payment method/currency
+  const oldPaymentCurrency = await PaymentCurrency.findByPk(oldCurrencyId);
+  if (!oldPaymentCurrency) {
+    throw new Error(`Payment currency ${oldCurrencyId} not found`);
+  }
+  const oldPaymentMethod = await PaymentMethod.findByPk(oldPaymentCurrency.payment_method_id);
+  if (!oldPaymentMethod) {
+    throw new Error(`Payment method for currency ${oldCurrencyId} not found`);
+  }
+
+  const newPaymentCurrency = await PaymentCurrency.findByPk(newCurrencyId);
+  if (!newPaymentCurrency) {
+    throw new Error(`Payment currency ${newCurrencyId} not found`);
+  }
+  const newPaymentMethod = await PaymentMethod.findByPk(newPaymentCurrency.payment_method_id);
+  if (!newPaymentMethod) {
+    throw new Error(`Payment method for currency ${newCurrencyId} not found`);
+  }
+
+  // 4. Stripe payment method is not supported for migration
+  if (newPaymentMethod.type === 'stripe') {
+    logger.info('Skip billing migration for stripe payment method', {
+      subscriptionId: subscription.id,
+    });
+    return { migrated: false, reason: 'stripe_payment_method' };
+  }
+
+  try {
+    const customer = await Customer.findByPk(subscription.customer_id);
+    if (!customer) {
+      throw new Error(`Customer ${subscription.customer_id} not found`);
+    }
+
+    const cancelOldInvoice = async (invoice: Invoice) => {
+      try {
+        if (invoice.payment_intent_id) {
+          const paymentIntent = await PaymentIntent.findByPk(invoice.payment_intent_id);
+          if (paymentIntent && paymentIntent.status !== 'canceled') {
+            await paymentIntent.update({
+              status: 'canceled',
+              canceled_at: dayjs().unix(),
+              cancellation_reason: 'void_invoice',
+            });
+          }
+        }
+
+        if (oldPaymentMethod.type === 'stripe' && invoice.metadata?.stripe_id) {
+          const client = oldPaymentMethod.getStripeClient();
+          await client.invoices.voidInvoice(invoice.metadata.stripe_id);
+        }
+
+        await invoice.update({
+          status: 'void',
+          status_transitions: {
+            ...(invoice.status_transitions || {}),
+            voided_at: dayjs().unix(),
+          },
+        });
+
+        logger.info('Successfully voided old invoice for payment method change', {
+          subscriptionId: subscription.id,
+          oldInvoice: invoice.id,
+          oldCurrency: oldCurrencyId,
+          newCurrency: newCurrencyId,
+        });
+      } catch (error) {
+        logger.error('Failed to void old invoice', {
+          subscription: subscription.id,
+          invoiceId: invoice.id,
+          error: error.message,
+        });
+        throw error;
+      }
+    };
+
+    const createNewInvoice = async () => {
+      const preInvoice = currentPeriodInvoice || voidedInvoice;
+      if (!preInvoice) {
+        throw new Error('No unpaid invoice found');
+      }
+      const metadata: Record<string, any> = {
+        prev_invoice_id: preInvoice.id,
+      };
+      const amount = getSubscriptionCycleAmount(subscriptionItemsExpanded, newCurrencyId);
+
+      const { invoice } = await ensureInvoiceAndItems({
+        customer,
+        currency: newPaymentCurrency,
+        subscription,
+        trialing: subscription.status === 'trialing',
+        metered: false,
+        lineItems: subscriptionItemsExpanded,
+        applyCredit: false,
+        props: {
+          status: 'open',
+          total: amount.total,
+          livemode: subscription.livemode,
+          description: 'Subscription cycle',
+          statement_descriptor: preInvoice.statement_descriptor,
+          period_start: preInvoice.period_start,
+          period_end: preInvoice.period_end,
+          auto_advance: true,
+          billing_reason: 'subscription_cycle',
+          currency_id: newCurrencyId,
+          default_payment_method_id: newPaymentMethod.id,
+          custom_fields: preInvoice.custom_fields || [],
+          footer: preInvoice.footer || '',
+          payment_settings: subscription.payment_settings,
+          metadata,
+        } as Invoice,
+      });
+      return invoice;
+    };
+
+    // 5. Cancel old invoice, then create new invoice
+    if (currentPeriodInvoice) {
+      await cancelOldInvoice(currentPeriodInvoice);
+    }
+
+    const invoice = await createNewInvoice();
+    if (invoice) {
+      await emitAsync('invoice.queued', invoice.id, { invoiceId: invoice.id, retryOnError: true }, { sync: false });
+      logger.info('Successfully queued new invoice for payment method change', {
+        subscriptionId: subscription.id,
+        invoiceId: invoice.id,
+      });
+    }
+
+    logger.info('Successfully migrated invoice for payment method change', {
+      subscriptionId: subscription.id,
+      oldInvoiceId: currentPeriodInvoice?.id || voidedInvoice?.id,
+      oldCurrency: oldCurrencyId,
+      newCurrency: newCurrencyId,
+      newInvoiceId: invoice.id,
+    });
+    return {
+      migrated: true,
+      oldInvoice: currentPeriodInvoice,
+      newInvoice: invoice,
+    };
+  } catch (error) {
+    logger.error('Failed to migrate invoice for payment method change', {
+      subscriptionId: subscription.id,
+      oldCurrencyId,
+      newCurrencyId,
+      error: error.message,
+    });
+    throw error;
+  }
+};

package/api/src/libs/security.ts

@@ -77,9 +77,10 @@ export function authenticate<T extends Model>({ component, roles, record, mine,
     }
 
     if (req.headers['x-user-did']) {
+      const role = (<string>req.headers['x-user-role'] || '').replace('blocklet-', '');
       req.user = {
         did: <string>req.headers['x-user-did'],
-        role: <string>req.headers['x-user-role'],
+        role,
         provider: <string>req.headers['x-user-provider'],
         fullName: decodeURIComponent(<string>req.headers['x-user-fullname']),
         walletOS: <string>req.headers['x-user-wallet-os'],

package/api/src/queues/payment.ts

@@ -846,10 +846,8 @@ export const handlePayment = async (job: PaymentJob) => {
         wallet,
         delegator: result.delegator,
       });
-      logger.info('PaymentIntent signed', { signed });
       // @ts-ignore
       const { buffer } = await client.encodeTransferV2Tx({ tx: signed });
-      logger.info('PaymentIntent buffer', { buffer, gas: getGasPayerExtra(buffer) });
       const txHash = await client.sendTransferV2Tx(
         // @ts-ignore
         { tx: signed, wallet, delegator: result.delegator },

package/api/src/queues/subscription.ts

@@ -26,7 +26,7 @@ import {
   shouldCancelSubscription,
   slashOverdraftProtectionStake,
 } from '../libs/subscription';
-import { ensureInvoiceAndItems } from '../libs/invoice';
+import { ensureInvoiceAndItems, migrateSubscriptionPaymentMethodInvoice } from '../libs/invoice';
 import { PaymentCurrency, PaymentIntent, PaymentMethod, Refund, SetupIntent, UsageRecord } from '../store/models';
 import { Customer } from '../store/models/customer';
 import { Invoice } from '../store/models/invoice';
@@ -1280,5 +1280,28 @@ events.on('setup_intent.succeeded', async (setupIntent: SetupIntent) => {
         logger.error('create return overdraft protection stake job failed', { error, subscription: subscription.id });
       }
     }
+
+    try {
+      const migrationResult = await migrateSubscriptionPaymentMethodInvoice(
+        subscription,
+        setupIntent.metadata?.from_currency,
+        setupIntent.metadata?.to_currency
+      );
+      if (migrationResult.migrated) {
+        logger.info('Subscription payment method billing migration completed', {
+          subscription: subscription.id,
+          migrated: migrationResult.migrated,
+          oldInvoice: migrationResult.oldInvoice?.id,
+          newInvoice: migrationResult.newInvoice?.id,
+        });
+      }
+    } catch (error) {
+      logger.error('Failed to migrate billing for payment method change', {
+        subscription: subscription.id,
+        fromCurrency: setupIntent.metadata?.from_currency,
+        toCurrency: setupIntent.metadata?.to_currency,
+        error,
+      });
+    }
   }
 });

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

@@ -89,7 +89,7 @@ import { addSubscriptionJob } from '../queues/subscription';
 
 const router = Router();
 
-const user = sessionMiddleware();
+const user = sessionMiddleware({ accessKey: true });
 const auth = authenticate<CheckoutSession>({ component: true, roles: ['owner', 'admin'] });
 
 const getPaymentMethods = async (doc: CheckoutSession) => {

package/api/src/routes/connect/change-payment.ts

@@ -13,6 +13,8 @@ import {
 import { ensureStakeInvoice } from '../../libs/invoice';
 import { EVM_CHAIN_TYPES } from '../../libs/constants';
 import logger from '../../libs/logger';
+import { getFastCheckoutAmount } from '../../libs/session';
+import { isDelegationSufficientForPayment } from '../../libs/payment';
 
 export default {
   action: 'change-payment',
@@ -26,41 +28,53 @@ export default {
   },
   onConnect: async ({ userDid, userPk, extraParams }: CallbackArgs) => {
     const { subscriptionId } = extraParams;
-    const { subscription, paymentMethod, paymentCurrency } = await ensureChangePaymentContext(subscriptionId);
+    const { subscription, paymentMethod, paymentCurrency, customer } = await ensureChangePaymentContext(subscriptionId);
 
     const claimsList: any[] = [];
     // @ts-ignore
     const items = subscription!.items as TLineItemExpanded[];
     const trialing = true;
     const billingThreshold = Number(subscription.billing_thresholds?.amount_gte || 0);
+    const fastCheckoutAmount = getFastCheckoutAmount(items, 'subscription', paymentCurrency.id, false);
 
     if (paymentMethod.type === 'arcblock') {
-      claimsList.push({
-        signature: await getDelegationTxClaim({
-          mode: 'setup',
-          userDid,
-          userPk,
-          nonce: `change-method-${subscription.id}`,
-          data: getTxMetadata({ subscriptionId: subscription.id }),
-          paymentCurrency,
-          paymentMethod,
-          trialing,
-          billingThreshold,
-          items,
-        }),
-      });
-
-      claimsList.push({
-        prepareTx: await getStakeTxClaim({
-          userDid,
-          userPk,
-          paymentCurrency,
-          paymentMethod,
-          items,
-          subscription,
-        }),
+      const delegation = await isDelegationSufficientForPayment({
+        paymentMethod,
+        paymentCurrency,
+        userDid: customer!.did,
+        amount: fastCheckoutAmount,
       });
+      const needDelegation = delegation.sufficient === false;
+      const noStake = subscription.billing_thresholds?.no_stake;
+      if (needDelegation || noStake) {
+        claimsList.push({
+          signature: await getDelegationTxClaim({
+            mode: 'setup',
+            userDid,
+            userPk,
+            nonce: `change-method-${subscription.id}`,
+            data: getTxMetadata({ subscriptionId: subscription.id }),
+            paymentCurrency,
+            paymentMethod,
+            trialing,
+            billingThreshold,
+            items,
+          }),
+        });
+      }
 
+      if (!noStake) {
+        claimsList.push({
+          prepareTx: await getStakeTxClaim({
+            userDid,
+            userPk,
+            paymentCurrency,
+            paymentMethod,
+            items,
+            subscription,
+          }),
+        });
+      }
       return claimsList;
     }
 
@@ -95,6 +109,8 @@ export default {
     const { setupIntent, subscription, paymentMethod, paymentCurrency, customer } =
       await ensureChangePaymentContext(subscriptionId);
 
+    const noStake = subscription.billing_thresholds?.no_stake;
+
     const result = request?.context?.store?.result || [];
     result.push({
       step,
@@ -106,7 +122,8 @@ export default {
 
     // 判断是否为最后一步
     const staking = result.find((x: any) => x.claim?.type === 'prepareTx' && x.claim?.meta?.purpose === 'staking');
-    const isFinalStep = (paymentMethod.type === 'arcblock' && staking) || paymentMethod.type !== 'arcblock';
+    const isFinalStep =
+      (paymentMethod.type === 'arcblock' && (staking || noStake)) || paymentMethod.type !== 'arcblock';
 
     if (!isFinalStep) {
       await updateSession({
@@ -181,25 +198,28 @@ export default {
         subscription?.id,
         paymentCurrency.contract
       );
-      await ensureStakeInvoice(
-        {
-          total: stakingAmount,
-          description: 'Stake for subscription payment change',
-          currency_id: paymentCurrency.id,
-          metadata: {
-            payment_details: {
-              arcblock: {
-                tx_hash: paymentDetails?.staking?.tx_hash,
-                payer: paymentDetails?.payer,
-                address: paymentDetails?.staking?.address,
+      if (stakingAmount && stakingAmount !== '0') {
+        await ensureStakeInvoice(
+          {
+            total: stakingAmount,
+            description: 'Stake for subscription payment change',
+            currency_id: paymentCurrency.id,
+            metadata: {
+              payment_details: {
+                arcblock: {
+                  tx_hash: paymentDetails?.staking?.tx_hash,
+                  payer: paymentDetails?.payer,
+                  address: paymentDetails?.staking?.address,
+                },
               },
             },
           },
-        },
-        subscription!,
-        paymentMethod,
-        customer!
-      );
+          subscription!,
+          paymentMethod,
+          customer!
+        );
+      }
+
       await afterTxExecution(paymentDetails);
       return { hash: paymentDetails.tx_hash };
     }

package/api/src/routes/customers.ts

@@ -96,7 +96,7 @@ router.get('/search', auth, async (req, res) => {
 });
 
 // eslint-disable-next-line consistent-return
-router.get('/me', sessionMiddleware(), async (req, res) => {
+router.get('/me', sessionMiddleware({ accessKey: true }), async (req, res) => {
   if (!req.user) {
     return res.status(403).json({ error: 'Unauthorized' });
   }
@@ -282,7 +282,7 @@ router.get('/:id/overdue/invoices', sessionMiddleware(), async (req, res) => {
   }
 });
 
-router.get('/recharge', sessionMiddleware(), async (req, res) => {
+router.get('/recharge', sessionMiddleware({ accessKey: true }), async (req, res) => {
   if (!req.user) {
     return res.status(403).json({ error: 'Unauthorized' });
   }
@@ -345,7 +345,7 @@ router.get('/recharge', sessionMiddleware(), async (req, res) => {
 });
 
 // get address token
-router.get('/payer-token', sessionMiddleware(), async (req, res) => {
+router.get('/payer-token', sessionMiddleware({ accessKey: true }), async (req, res) => {
   if (!req.user) {
     return res.status(403).json({ error: 'Unauthorized' });
   }
@@ -439,7 +439,7 @@ const updatePreferenceSchema = Joi.object({
   }).optional(),
 }).unknown(false);
 
-router.put('/preference', sessionMiddleware(), async (req, res) => {
+router.put('/preference', sessionMiddleware({ accessKey: true }), async (req, res) => {
   try {
     if (!req.user) {
       return res.status(403).json({ error: 'Unauthorized' });

package/api/src/routes/invoices.ts

@@ -25,6 +25,8 @@ import { getReturnStakeInvoices, getStakingInvoices, retryUncollectibleInvoices
 import { CheckoutSession, PaymentLink, TInvoiceExpanded } from '../store/models';
 import { mergePaginate, defaultTimeOrderBy, getCachedOrFetch, DataSource } from '../libs/pagination';
 import logger from '../libs/logger';
+import { returnOverdraftProtectionQueue, returnStakeQueue } from '../queues/subscription';
+import { checkRemainingStake } from '../libs/subscription';
 
 const router = Router();
 const authAdmin = authenticate<Subscription>({ component: true, roles: ['owner', 'admin'] });
@@ -495,6 +497,77 @@ router.get('/retry-uncollectible', authAdmin, async (req, res) => {
   }
 });
 
+router.get('/:id/return-stake', authAdmin, async (req, res) => {
+  const doc = await Invoice.findByPk(req.params.id as string);
+  if (!doc) {
+    return res.status(404).json({ error: 'Invoice not found' });
+  }
+  if (!['stake', 'stake_overdraft_protection'].includes(doc.billing_reason)) {
+    return res.status(400).json({ error: 'Invoice is not a stake invoice' });
+  }
+  const paymentCurrency = await PaymentCurrency.findByPk(doc.currency_id);
+  if (!paymentCurrency) {
+    return res.status(400).json({ error: 'Payment currency not found' });
+  }
+  const paymentMethod = await PaymentMethod.findByPk(doc.default_payment_method_id);
+  if (!paymentMethod) {
+    return res.status(400).json({ error: 'Payment method not found' });
+  }
+  const stakingAddress = doc.metadata?.payment_details?.arcblock?.address;
+  if (!stakingAddress) {
+    return res.status(400).json({ error: 'Staking address not found' });
+  }
+  const { staked } = await checkRemainingStake(paymentMethod, paymentCurrency, stakingAddress, '0');
+  return res.json(staked);
+});
+router.post('/:id/return-stake', authAdmin, async (req, res) => {
+  const doc = await Invoice.findByPk(req.params.id as string);
+  if (!doc) {
+    return res.status(404).json({ error: 'Invoice not found' });
+  }
+  if (!['stake', 'stake_overdraft_protection'].includes(doc.billing_reason)) {
+    return res.status(400).json({ error: 'Invoice is not a stake invoice' });
+  }
+  if (doc.status !== 'paid') {
+    return res.status(400).json({ error: 'Invoice is not paid' });
+  }
+  const paymentMethod = await PaymentMethod.findByPk(doc.default_payment_method_id);
+  if (!paymentMethod) {
+    return res.status(400).json({ error: 'Payment method not found' });
+  }
+  if (paymentMethod.type !== 'arcblock') {
+    return res.status(400).json({ error: 'Can only return stake for arcblock payment method' });
+  }
+  const subscription = await Subscription.findByPk(doc.subscription_id);
+  if (!subscription) {
+    return res.status(400).json({ error: 'Subscription not found' });
+  }
+  try {
+    if (doc.billing_reason === 'stake') {
+      await returnStakeQueue.pushAndWait({
+        id: `return-stake-${subscription.id}-${doc.id}`,
+        job: {
+          subscriptionId: subscription.id,
+          stakingAddress: doc.metadata?.payment_details?.arcblock?.address,
+          paymentCurrencyId: doc.currency_id,
+        },
+      });
+      return res.json({ success: true, subscriptionId: subscription.id });
+    }
+    if (doc.billing_reason === 'stake_overdraft_protection' && subscription.status === 'canceled') {
+      await returnOverdraftProtectionQueue.pushAndWait({
+        id: `return-overdraft-protection-${subscription.id}`,
+        job: { subscriptionId: subscription.id },
+      });
+      return res.json({ success: true, subscriptionId: subscription.id });
+    }
+    return res.json({ success: false, error: 'Subscription is not canceled' });
+  } catch (error) {
+    logger.error('Failed to return stake', { error, subscriptionId: subscription.id, invoiceId: doc.id });
+    return res.status(400).json({ error: 'Failed to return stake' });
+  }
+});
+
 router.get('/:id', authPortal, async (req, res) => {
   try {
     const doc = (await Invoice.findOne({
@@ -554,8 +627,8 @@ router.get('/:id', authPortal, async (req, res) => {
       const prices = (await Price.findAll()).map((x) => x.toJSON());
       // @ts-ignore
       expandLineItems(json.lines, products, prices);
-      if (doc.metadata?.invoice_id) {
-        const relatedInvoice = await Invoice.findByPk(doc.metadata.invoice_id, {
+      if (doc.metadata?.invoice_id || doc.metadata?.prev_invoice_id) {
+        const relatedInvoice = await Invoice.findByPk(doc.metadata.invoice_id || doc.metadata.prev_invoice_id, {
           attributes: ['id', 'number', 'status', 'billing_reason'],
         });
         return res.json({ ...json, relatedInvoice, paymentLink, checkoutSession });

package/api/src/routes/payouts.ts

@@ -117,7 +117,7 @@ const mineRecordPaginationSchema = createListParamSchema<{
   currency_id: Joi.string().empty(''),
   status: Joi.string().empty(''),
 });
-router.get('/mine', sessionMiddleware(), async (req, res) => {
+router.get('/mine', sessionMiddleware({ accessKey: true }), async (req, res) => {
   try {
     const {
       page,

package/api/src/routes/subscriptions.ts

@@ -55,7 +55,11 @@ import { Subscription, TSubscription } from '../store/models/subscription';
 import { SubscriptionItem } from '../store/models/subscription-item';
 import type { LineItem, ServiceAction, SubscriptionUpdateItem } from '../store/models/types';
 import { UsageRecord } from '../store/models/usage-record';
-import { cleanupInvoiceAndItems, ensureInvoiceAndItems } from '../libs/invoice';
+import {
+  cleanupInvoiceAndItems,
+  ensureInvoiceAndItems,
+  migrateSubscriptionPaymentMethodInvoice,
+} from '../libs/invoice';
 import { createUsageRecordQueryFn } from './usage-records';
 import { SubscriptionWillCanceledSchedule } from '../crons/subscription-will-canceled';
 import { getTokenByAddress } from '../integrations/arcblock/stake';
@@ -447,7 +451,7 @@ router.get('/:id/recover-info', authPortal, async (req, res) => {
       try {
         const { revoked } = await checkRemainingStake(paymentMethod, paymentCurrency, address, '0');
         const cancelReason = doc.cancelation_details?.reason;
-        if (revoked && revoked !== '0' && cancelReason === 'stake_revoked') {
+        if (revoked && revoked.value !== '0' && cancelReason === 'stake_revoked') {
           needStake = true;
           revokedStake = revoked;
         }
@@ -496,7 +500,7 @@ router.put('/:id/recover', authPortal, async (req, res) => {
       try {
         const { revoked } = await checkRemainingStake(paymentMethod, paymentCurrency, address, '0');
         const cancelReason = doc.cancelation_details?.reason;
-        if (revoked && revoked !== '0' && cancelReason === 'stake_revoked') {
+        if (revoked && revoked.value !== '0' && cancelReason === 'stake_revoked') {
           return res.json({
             needStake: true,
             subscription: doc,
@@ -1449,7 +1453,7 @@ router.post('/:id/change-payment', authPortal, async (req, res) => {
     if (!subscription) {
       return res.status(404).json({ error: `Subscription ${req.params.id} not found when change payment` });
     }
-    if (subscription.isActive() === false) {
+    if (['active', 'trialing', 'past_due'].includes(subscription.status) === false) {
       return res.status(400).json({ error: `Subscription ${req.params.id} not active when change payment` });
     }
     const paymentCurrency = await PaymentCurrency.findByPk(req.body.payment_currency);
@@ -1655,9 +1659,10 @@ router.post('/:id/change-payment', authPortal, async (req, res) => {
         userDid: customer!.did,
         amount: getFastCheckoutAmount(lineItems, 'subscription', paymentCurrency.id, false),
       });
-      if (paymentMethod.type === 'arcblock' && delegation.sufficient) {
+      const noStake = subscription.billing_thresholds?.no_stake;
+      if (paymentMethod.type === 'arcblock' && delegation.sufficient && !noStake) {
         delegation.sufficient = false;
-        delegation.reason = 'NO_ENOUGH_TOKEN';
+        delegation.reason = 'WAIT_STAKE';
       }
       if (delegation.sufficient) {
         await setupIntent.update({
@@ -2216,4 +2221,30 @@ router.get('/:id/unpaid-invoices', authPortal, async (req, res) => {
   const count = await getSubscriptionUnpaidInvoicesCount(subscription);
   return res.json({ count });
 });
+
+router.get('/:id/change-payment/migrate-invoice', auth, async (req, res) => {
+  const subscription = await Subscription.findByPk(req.params.id);
+  if (!subscription) {
+    return res.status(404).json({ error: 'Subscription not found' });
+  }
+  const context = subscription.metadata.changePayment || {};
+  if (!context.setup_intent_id) {
+    return res.status(404).json({ error: 'Subscription change payment context not found' });
+  }
+  const setupIntent = await SetupIntent.findByPk(context.setup_intent_id);
+  if (!setupIntent) {
+    return res.status(404).json({ error: 'Setup intent not found' });
+  }
+  try {
+    const migrationResult = await migrateSubscriptionPaymentMethodInvoice(
+      subscription,
+      setupIntent.metadata?.from_currency,
+      setupIntent.metadata?.to_currency
+    );
+    return res.json(migrationResult);
+  } catch (error) {
+    logger.error(error);
+    return res.status(400).json({ error: error.message });
+  }
+});
 export default router;

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.18.48
+version: 1.18.50
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.18.48",
+  "version": "1.18.50",
   "scripts": {
     "dev": "blocklet dev --open",
     "eject": "vite eject",
@@ -55,7 +55,7 @@
     "@blocklet/did-space-js": "^1.0.56",
     "@blocklet/js-sdk": "^1.16.43",
     "@blocklet/logger": "^1.16.43",
-    "@blocklet/payment-react": "1.18.48",
+    "@blocklet/payment-react": "1.18.50",
     "@blocklet/sdk": "^1.16.43",
     "@blocklet/ui-react": "^2.13.54",
     "@blocklet/uploader": "^0.1.93",
@@ -123,7 +123,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.43",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.18.48",
+    "@blocklet/payment-types": "1.18.50",
     "@types/cookie-parser": "^1.4.7",
     "@types/cors": "^2.8.17",
     "@types/debug": "^4.1.12",
@@ -169,5 +169,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "4042dc2996b11ab6ccf6a973af53042cff913474"
+  "gitHead": "1b7529c51c5ef7d65a288e852e971fbfb281a9bb"
 }

package/src/components/invoice/action.tsx

@@ -2,7 +2,7 @@ import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
 import Toast from '@arcblock/ux/lib/Toast';
 import { ConfirmDialog, api, formatError } from '@blocklet/payment-react';
 import type { TInvoiceExpanded } from '@blocklet/payment-types';
-import { useSetState } from 'ahooks';
+import { useRequest, useSetState } from 'ahooks';
 import { useNavigate } from 'react-router-dom';
 import type { LiteralUnion } from 'type-fest';
 
@@ -23,6 +23,10 @@ InvoiceActions.defaultProps = {
   mode: 'admin',
 };
 
+const fetchStakingData = (id: string): Promise<{ value: string }> => {
+  return api.get(`/api/invoices/${id}/return-stake`).then((res: any) => res.data);
+};
+
 export default function InvoiceActions({ data, variant, onChange, mode }: Props) {
   const { t } = useLocaleContext();
   const navigate = useNavigate();
@@ -31,11 +35,39 @@ export default function InvoiceActions({ data, variant, onChange, mode }: Props)
     loading: false,
   });
 
+  const isStakeInvoice = ['stake', 'stake_overdraft_protection'].includes(data.billing_reason);
+  const hasPaid = data.status === 'paid';
+  const isAdmin = mode === 'admin';
+  const showReturnStake = isAdmin && isStakeInvoice && hasPaid && data.paymentMethod?.type === 'arcblock';
+
+  const {
+    data: stakeResult = {
+      value: '0',
+    },
+    runAsync: fetchStakeResultAsync,
+  } = useRequest(
+    () => {
+      if (showReturnStake) {
+        return fetchStakingData(data.id);
+      }
+      return Promise.resolve({ value: '0' });
+    },
+    {
+      manual: true,
+    }
+  );
+
   const handleAction = async () => {
     try {
       setState({ loading: true });
-      await api.put(`/api/invoices/${data.id}/xxx`).then((res) => res.data);
-      Toast.success(t('common.saved'));
+      if (state.action === 'return-stake') {
+        const result = await api.post(`/api/invoices/${data.id}/return-stake`).then((res) => res.data);
+        if (result.success) {
+          Toast.success(t('admin.invoice.returnStake.success'));
+        } else {
+          Toast.error(result.error);
+        }
+      }
       onChange(state.action);
     } catch (err) {
       console.error(err);
@@ -45,8 +77,6 @@ export default function InvoiceActions({ data, variant, onChange, mode }: Props)
     }
   };
 
-  const isAdmin = mode === 'admin';
-
   const actions = [
     isAdmin && {
       label: t('admin.invoice.edit'),
@@ -61,6 +91,14 @@ export default function InvoiceActions({ data, variant, onChange, mode }: Props)
       disabled: data.status !== 'draft',
       divider: true,
     },
+    showReturnStake &&
+      stakeResult &&
+      stakeResult.value !== '0' && {
+        label: t('admin.invoice.returnStake.title'),
+        handler: () => setState({ action: 'return-stake' }),
+        color: 'primary',
+        divider: true,
+      },
     {
       label: t('admin.customer.view'),
       handler: () => {
@@ -90,13 +128,13 @@ export default function InvoiceActions({ data, variant, onChange, mode }: Props)
 
   return (
     <ClickBoundary>
-      <Actions variant={variant} actions={actions as any} />
-      {state.action === 'xxx' && (
+      <Actions variant={variant} actions={actions as any} onOpenCallback={fetchStakeResultAsync} />
+      {state.action === 'return-stake' && (
         <ConfirmDialog
           onConfirm={handleAction}
           onCancel={() => setState({ action: '' })}
-          title={t('admin.invoice.edit')}
-          message={t('admin.invoice.edit')}
+          title={t('admin.invoice.returnStake.title')}
+          message={t('admin.invoice.returnStake.tip')}
           loading={state.loading}
         />
       )}

package/src/libs/util.ts

@@ -227,7 +227,7 @@ export const debounce = (fun: Function, wait: number) => {
 
 export function canChangePaymentMethod(subscription: TSubscriptionExpanded) {
   return (
-    ['active', 'trialing'].includes(subscription.status) &&
+    ['active', 'trialing', 'past_due'].includes(subscription.status) &&
     subscription.items.every((x) => getPriceCurrencyOptions(x.price).length > 1)
   );
 }

package/src/locales/en.tsx

@@ -518,6 +518,11 @@ export default flat({
       download: 'Download PDF',
       edit: 'Edit Invoice',
       duplicate: 'Duplicate Invoice',
+      returnStake: {
+        title: 'Return Stake',
+        tip: 'Are you sure you want to return the stake? This action will return the stake to the customer.',
+        success: 'Stake return application has been successfully created',
+      },
     },
     subscription: {
       view: 'View subscription',

package/src/locales/zh.tsx

@@ -507,6 +507,11 @@ export default flat({
       edit: '编辑账单',
       duplicate: '复制账单',
       attention: '未完成的账单',
+      returnStake: {
+        title: '退还质押',
+        tip: '您确定要退还质押吗？此操作将退还质押给客户。',
+        success: '质押退还申请已提交',
+      },
     },
     subscription: {
       view: '查看订阅',

package/src/pages/customer/subscription/change-payment.tsx

@@ -203,9 +203,12 @@ function CustomerSubscriptionChangePayment({ subscription, customer, onComplete
   };
 
   const onConfirm = async () => {
-    const result = await checkUnpaidInvoices();
-    if (result) {
-      return;
+    // only check unpaid invoices when overdraft protection is enabled
+    if (subscription.overdraft_protection?.enabled) {
+      const result = await checkUnpaidInvoices();
+      if (result) {
+        return;
+      }
     }
     handleSubmit(onSubmit)();
   };
@@ -239,7 +242,7 @@ function CustomerSubscriptionChangePayment({ subscription, customer, onComplete
           currency={findCurrency(settings.paymentMethods, selectedCurrencyId) as TPaymentCurrency}
           trialInDays={0}
           billingThreshold={0}
-          showStaking={method.type === 'arcblock'}
+          showStaking={method.type === 'arcblock' && !subscription.billing_thresholds?.no_stake}
         />
       </Stack>
       <Stack direction="column" spacing={2}>

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

@@ -516,9 +516,12 @@ export default function CustomerSubscriptionDetail() {
                     sx={{ color: 'text.link' }}
                     size="small"
                     onClick={async () => {
-                      const result = await checkUnpaidInvoices();
-                      if (result) {
-                        return;
+                      // only check unpaid invoices when overdraft protection is enabled
+                      if (data?.overdraft_protection?.enabled) {
+                        const result = await checkUnpaidInvoices();
+                        if (result) {
+                          return;
+                        }
                       }
                       navigate(`/customer/subscription/${data.id}/change-payment`);
                     }}>