payment-kit 1.21.16 → 1.21.17

package/api/src/index.ts

@@ -53,6 +53,7 @@ import rechargeHandlers from './routes/connect/recharge';
 import rechargeAccountHandlers from './routes/connect/recharge-account';
 import setupHandlers from './routes/connect/setup';
 import subscribeHandlers from './routes/connect/subscribe';
+import changePayerHandlers from './routes/connect/change-payer';
 import { initialize } from './store/models';
 import { sequelize } from './store/sequelize';
 
@@ -92,6 +93,7 @@ handlers.attach(Object.assign({ app: router }, delegationHandlers));
 handlers.attach(Object.assign({ app: router }, overdraftProtectionHandlers));
 handlers.attach(Object.assign({ app: router }, reStakeHandlers));
 handlers.attach(Object.assign({ app: router }, autoRechargeAuthorizationHandlers));
+handlers.attach(Object.assign({ app: router }, changePayerHandlers));
 router.use('/api', routes);
 
 const isProduction = process.env.BLOCKLET_MODE === 'production';

package/api/src/integrations/stripe/handlers/invoice.ts

@@ -91,7 +91,7 @@ export function getStripeInvoicePeriod(invoice: any) {
   };
 }
 
-export async function syncStripeInvoice(invoice: Invoice) {
+export async function syncStripeInvoice(invoice: Invoice, sync = true) {
   if (!invoice.metadata?.stripe_id) {
     return;
   }
@@ -103,6 +103,28 @@ export async function syncStripeInvoice(invoice: Invoice) {
 
   const client = await method.getStripeClient();
   const stripeInvoice = await client.invoices.retrieve(invoice.metadata.stripe_id);
+  const updates = [
+    'amount_due',
+    'amount_paid',
+    'amount_remaining',
+    'last_finalization_error',
+    'paid_out_of_band',
+    'paid',
+    'status',
+    'status_transitions',
+    'subtotal_excluding_tax',
+    'subtotal',
+    'tax',
+    'total_discount_amounts',
+    'total',
+  ];
+  if (!sync && stripeInvoice.status !== 'paid' && invoice.status === 'uncollectible') {
+    // remove status from updates
+    const statusIndex = updates.indexOf('status');
+    if (statusIndex !== -1) {
+      updates.splice(statusIndex, 1);
+    }
+  }
   if (stripeInvoice) {
     const processDiscounts = await processInvoiceDiscounts(
       stripeInvoice,
@@ -111,27 +133,9 @@ export async function syncStripeInvoice(invoice: Invoice) {
     );
     await invoice.update(
       // @ts-ignore
-      merge(
-        pick(stripeInvoice, [
-          'amount_due',
-          'amount_paid',
-          'amount_remaining',
-          'last_finalization_error',
-          'paid_out_of_band',
-          'paid',
-          'status_transitions',
-          'status',
-          'subtotal_excluding_tax',
-          'subtotal',
-          'tax',
-          'total_discount_amounts',
-          'total',
-        ]),
-        getStripeInvoicePeriod(stripeInvoice),
-        {
-          total_discount_amounts: processDiscounts,
-        }
-      )
+      merge(pick(stripeInvoice, updates), getStripeInvoicePeriod(stripeInvoice), {
+        total_discount_amounts: processDiscounts,
+      })
     );
     logger.info('stripe invoice synced', { locale: invoice.id, remote: stripeInvoice.id });
     const failedStatuses = ['uncollectible', 'finalization_failed', 'payment_failed'];
@@ -416,7 +420,8 @@ export async function handleInvoiceEvent(event: TEventExpanded, client: Stripe)
   }
 
   if (event.type === 'invoice.finalized') {
-    await invoice.update({ status: 'finalized', status_transitions: event.data.object.status_transitions });
+    // invoice from draft to open
+    await invoice.update({ status: 'open', status_transitions: event.data.object.status_transitions });
     logger.info('invoice finalized on stripe event', { locale: invoice.id });
     return;
   }
@@ -442,14 +447,14 @@ export async function handleInvoiceEvent(event: TEventExpanded, client: Stripe)
 
   if (event.type === 'invoice.finalization_failed') {
     await invoice.update({
-      status: 'finalization_failed',
+      status: 'uncollectible',
       last_finalization_error: event.data.object.last_finalization_error,
     });
     logger.info('invoice finalization failed on stripe event', { locale: invoice.id });
   }
 
   if (event.type === 'invoice.payment_failed') {
-    await invoice.update({ status: 'payment_failed' });
+    await invoice.update({ status: 'uncollectible' });
     logger.info('invoice payment failed on stripe event', { locale: invoice.id });
   }
 

package/api/src/integrations/stripe/handlers/setup-intent.ts

@@ -1,10 +1,15 @@
 import type Stripe from 'stripe';
+import { Op } from 'sequelize';
 
 import logger from '../../../libs/logger';
 import {
   AutoRechargeConfig,
   CheckoutSession,
+  Customer,
+  Invoice,
   Lock,
+  PaymentCurrency,
+  PaymentMethod,
   SetupIntent,
   Subscription,
   TEventExpanded,
@@ -150,6 +155,230 @@ async function handleAutoRechargeOnSetupSucceeded(event: TEventExpanded, stripeI
   }
 }
 
+async function handleUpdateStripePaymentMethodOnSetupSucceeded(event: TEventExpanded, stripeIntentId: string) {
+  const { metadata } = event.data.object;
+
+  if (metadata?.action !== 'update_payment_method' || !metadata?.subscription_id) {
+    return;
+  }
+
+  if (event.type !== 'setup_intent.succeeded') {
+    return;
+  }
+
+  const subscription = await Subscription.findByPk(metadata.subscription_id);
+  if (!subscription) {
+    logger.warn('subscription not found for update payment method', {
+      id: event.id,
+      stripeIntentId,
+      subscriptionId: metadata.subscription_id,
+    });
+    return;
+  }
+
+  const paymentMethod = await PaymentMethod.findByPk(subscription.default_payment_method_id);
+  if (!paymentMethod || paymentMethod.type !== 'stripe') {
+    logger.warn('stripe payment method not found for subscription', {
+      id: event.id,
+      stripeIntentId,
+      subscriptionId: subscription.id,
+    });
+    return;
+  }
+
+  const stripeSubscriptionId = subscription.payment_details?.stripe?.subscription_id;
+  if (!stripeSubscriptionId) {
+    logger.warn('stripe subscription id not found', {
+      id: event.id,
+      stripeIntentId,
+      subscriptionId: subscription.id,
+    });
+    return;
+  }
+
+  const client = paymentMethod.getStripeClient();
+  const stripePaymentMethodId = event.data.object.payment_method as string;
+
+  await client.subscriptions.update(stripeSubscriptionId, {
+    default_payment_method: stripePaymentMethodId,
+  });
+
+  logger.info('stripe payment method updated via webhook', {
+    subscriptionId: subscription.id,
+    stripeIntentId,
+    paymentMethod: stripePaymentMethodId,
+  });
+}
+
+async function handleBatchOverduePaymentOnSetupSucceeded(event: TEventExpanded, stripeIntentId: string) {
+  const { metadata } = event.data.object;
+
+  if (metadata?.action !== 'pay_overdue_batch' || !metadata?.currency_id) {
+    return;
+  }
+
+  if (event.type !== 'setup_intent.succeeded') {
+    return;
+  }
+
+  const paymentCurrency = await PaymentCurrency.findByPk(metadata.currency_id);
+  if (!paymentCurrency) {
+    logger.warn('payment currency not found for batch overdue payment', {
+      id: event.id,
+      stripeIntentId,
+      currencyId: metadata.currency_id,
+    });
+    return;
+  }
+
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+  if (!paymentMethod || paymentMethod.type !== 'stripe') {
+    logger.warn('stripe payment method not found or invalid type', {
+      id: event.id,
+      stripeIntentId,
+      currencyId: metadata.currency_id,
+      paymentMethodType: paymentMethod?.type,
+    });
+    return;
+  }
+
+  let invoices: Invoice[];
+
+  if (metadata.invoices) {
+    let invoiceIds: string[];
+    try {
+      invoiceIds = JSON.parse(metadata.invoices);
+    } catch (err) {
+      logger.error('failed to parse invoices from setup intent metadata', {
+        id: event.id,
+        stripeIntentId,
+        metadata,
+      });
+      return;
+    }
+
+    invoices = await Invoice.findAll({
+      where: {
+        id: { [Op.in]: invoiceIds },
+        currency_id: metadata.currency_id,
+      },
+    });
+
+    const subscriptionIds = [...new Set(invoices.map((inv) => inv.subscription_id).filter(Boolean) as string[])];
+
+    if (subscriptionIds.length > 0) {
+      const additionalInvoices = await Invoice.findAll({
+        where: {
+          subscription_id: { [Op.in]: subscriptionIds },
+          currency_id: metadata.currency_id,
+          status: { [Op.in]: ['open', 'uncollectible'] },
+          id: { [Op.notIn]: invoiceIds },
+        },
+      });
+
+      invoices = [...invoices, ...additionalInvoices];
+
+      logger.info('found additional overdue invoices for subscriptions', {
+        stripeIntentId,
+        subscriptionIds,
+        originalCount: invoiceIds.length,
+        additionalCount: additionalInvoices.length,
+        totalCount: invoices.length,
+      });
+    }
+  } else if (metadata.subscription_id) {
+    invoices = await Invoice.findAll({
+      where: {
+        subscription_id: metadata.subscription_id,
+        currency_id: metadata.currency_id,
+        status: { [Op.in]: ['open', 'uncollectible'] },
+      },
+    });
+  } else if (metadata.customer_id) {
+    const customer = await Customer.findByPkOrDid(metadata.customer_id);
+    if (!customer) {
+      logger.warn('customer not found for batch overdue payment', {
+        id: event.id,
+        stripeIntentId,
+        customerId: metadata.customer_id,
+      });
+      return;
+    }
+
+    invoices = await Invoice.findAll({
+      where: {
+        customer_id: customer.id,
+        currency_id: metadata.currency_id,
+        status: { [Op.in]: ['open', 'uncollectible'] },
+      },
+    });
+  } else {
+    logger.error('invalid metadata for batch overdue payment, must provide invoices, subscription_id or customer_id', {
+      id: event.id,
+      stripeIntentId,
+      metadata,
+    });
+    return;
+  }
+
+  if (invoices.length === 0) {
+    logger.warn('no invoices found for batch overdue payment', {
+      id: event.id,
+      stripeIntentId,
+      metadata,
+    });
+    return;
+  }
+
+  const validInvoices = invoices.filter((inv) => inv.metadata?.stripe_id);
+  if (validInvoices.length === 0) {
+    logger.warn('no valid stripe invoices found for batch overdue payment', {
+      id: event.id,
+      stripeIntentId,
+      totalInvoices: invoices.length,
+    });
+    return;
+  }
+
+  const client = paymentMethod.getStripeClient();
+  const stripePaymentMethodId = event.data.object.payment_method as string;
+
+  const payResults = await Promise.all(
+    validInvoices.map(async (invoice) => {
+      try {
+        await client.invoices.pay(invoice.metadata!.stripe_id, {
+          payment_method: stripePaymentMethodId,
+        });
+
+        logger.info('stripe invoice payment initiated via webhook', {
+          invoiceId: invoice.id,
+          stripeInvoiceId: invoice.metadata!.stripe_id,
+          stripeIntentId,
+        });
+
+        return { invoiceId: invoice.id, success: true };
+      } catch (err) {
+        logger.error('failed to pay stripe invoice via webhook', {
+          invoiceId: invoice.id,
+          stripeInvoiceId: invoice.metadata!.stripe_id,
+          stripeIntentId,
+          error: err,
+        });
+        return { invoiceId: invoice.id, success: false, error: err.message };
+      }
+    })
+  );
+
+  logger.info('batch overdue payment completed via webhook', {
+    stripeIntentId,
+    currencyId: metadata.currency_id,
+    totalInvoices: invoices.length,
+    validInvoices: validInvoices.length,
+    succeeded: payResults.filter((r) => r.success).length,
+    failed: payResults.filter((r) => !r.success).length,
+  });
+}
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export async function handleSetupIntentEvent(event: TEventExpanded, _: Stripe) {
   const stripeIntentId = event.data.object.id;
@@ -159,4 +388,6 @@ export async function handleSetupIntentEvent(event: TEventExpanded, _: Stripe) {
   await handleSetupIntentOnSetupSucceeded(event, stripeIntentId);
   await handleCheckoutSessionOnSetupSucceeded(event, stripeIntentId);
   await handleAutoRechargeOnSetupSucceeded(event, stripeIntentId);
+  await handleUpdateStripePaymentMethodOnSetupSucceeded(event, stripeIntentId);
+  await handleBatchOverduePaymentOnSetupSucceeded(event, stripeIntentId);
 }

package/api/src/integrations/stripe/handlers/subscription.ts

@@ -197,11 +197,25 @@ export async function handleSubscriptionOnPaymentFailure(
   eventType: string,
   client: Stripe
 ) {
-  if (!subscription || !subscription.isActive()) {
-    logger.warn('Subscription is not active or not found', { subscription: subscription.id });
+  if (!subscription || subscription.isImmutable()) {
+    logger.warn('Subscription is immutable or not found', { subscription: subscription.id });
     return;
   }
 
+  const paymentMethod = await PaymentMethod.findByPk(subscription.default_payment_method_id);
+  if (paymentMethod && paymentMethod.type !== 'stripe') {
+    logger.info('Subscription payment method is not stripe', {
+      subscription: subscription.id,
+      paymentMethod: paymentMethod?.type,
+    });
+    return;
+  }
+
+  logger.info('start handle stripe subscription on payment failure', {
+    subscription: subscription.id,
+    eventType,
+  });
+
   const now = dayjs().unix();
   const { interval } = subscription.pending_invoice_item_interval;
   const dueUnit = getDueUnit(interval);
@@ -256,13 +270,25 @@ export async function handleSubscriptionOnPaymentFailure(
   // sync to stripe
   if (subscription.payment_details?.stripe?.subscription_id && client) {
     try {
-      const method = await PaymentMethod.findByPk(subscription.default_payment_method_id);
-      if (method && method.type === 'stripe') {
+      if (paymentMethod && paymentMethod.type === 'stripe') {
+        if (cancelSubscription) {
+          await client.subscriptions.cancel(subscription.payment_details.stripe.subscription_id, {
+            cancellation_details: {
+              comment: 'exceed_current_period',
+              feedback: 'other',
+            },
+          });
+          logger.info('subscription in Stripe has canceled after payment failed', {
+            subscription: subscription.id,
+            stripeSubscription: subscription.payment_details.stripe.subscription_id,
+            eventType,
+          });
+          return;
+        }
         const stripeUpdates: any = {
           cancellation_details: {
             comment: 'past_due',
             feedback: 'other',
-            reason: 'payment_failed',
           },
         };
 
@@ -271,10 +297,6 @@ export async function handleSubscriptionOnPaymentFailure(
         } else if (cancelUpdates.cancel_at_period_end) {
           stripeUpdates.cancel_at_period_end = true;
         }
-        if (cancelSubscription) {
-          stripeUpdates.cancel_at = now;
-          stripeUpdates.cancel_at_period_end = false;
-        }
 
         await client.subscriptions.update(subscription.payment_details.stripe.subscription_id, stripeUpdates);
         logger.info(`[${eventType}] Updated subscription in Stripe after payment failed`, {

package/api/src/integrations/stripe/resource.ts

@@ -855,6 +855,35 @@ export async function ensureStripeSetupIntentForAutoRecharge(
   return setupIntent;
 }
 
+export async function ensureStripeSetupIntentForInvoicePayment(
+  customer: Customer,
+  method: PaymentMethod,
+  metadata: Record<string, string>
+) {
+  const client = method.getStripeClient();
+  const stripeCustomer = await ensureStripeCustomer(customer, method);
+
+  const setupIntent = await client.setupIntents.create({
+    customer: stripeCustomer.id,
+    payment_method_types: ['card'],
+    usage: 'off_session',
+    metadata: {
+      appPid: env.appPid,
+      customer_id: customer.id,
+      action: 'pay_overdue_batch',
+      ...metadata,
+    },
+  });
+
+  logger.info('stripe setup intent created for invoice payment', {
+    customerId: customer.id,
+    setupIntentId: setupIntent.id,
+    metadata,
+  });
+
+  return setupIntent;
+}
+
 export async function updateAutoRechargeConfigPaymentMethod(params: {
   stripePaymentMethodId: string;
   autoRechargeConfig: AutoRechargeConfig;

package/api/src/libs/payment.ts

@@ -25,7 +25,13 @@ import {
 import type { TPaymentCurrency } from '../store/models/payment-currency';
 import { blocklet, ethWallet, wallet, getVaultAddress } from './auth';
 import logger from './logger';
-import { getBlockletJson, getUserOrAppInfo, OCAP_PAYMENT_TX_TYPE, resolveAddressChainTypes } from './util';
+import {
+  formatLinkWithLocale,
+  getBlockletJson,
+  getUserOrAppInfo,
+  OCAP_PAYMENT_TX_TYPE,
+  resolveAddressChainTypes,
+} from './util';
 import { CHARGE_SUPPORTED_CHAIN_TYPES, EVM_CHAIN_TYPES } from './constants';
 import { getTokenByAddress } from '../integrations/arcblock/stake';
 import { isCreditMetered } from './session';
@@ -564,7 +570,7 @@ export async function isBalanceSufficientForRefund(args: {
   throw new Error(`isBalanceSufficientForRefund: Payment method ${paymentMethod.type} not supported`);
 }
 
-export async function getDonationBenefits(paymentLink: PaymentLink, url?: string) {
+export async function getDonationBenefits(paymentLink: PaymentLink, url?: string, locale?: string) {
   const { donation_settings: donationSettings } = paymentLink;
   if (!donationSettings) {
     return [];
@@ -585,7 +591,7 @@ export async function getDonationBenefits(paymentLink: PaymentLink, url?: string
           percent: (Number(share) * 100) / total,
           name: name || info?.name || '',
           avatar: avatar || info?.avatar || '',
-          url: info?.url || '',
+          url: formatLinkWithLocale(info?.url || '', locale),
           type: info?.type || 'user',
         };
       } catch (error) {

package/api/src/libs/util.ts

@@ -603,3 +603,20 @@ export function formatNumber(
   const [left, right] = result.split('.');
   return right ? [left, trimEnd(right, '0')].filter(Boolean).join('.') : left;
 }
+
+export function formatLinkWithLocale(url: string, locale?: string) {
+  if (!locale || !url) {
+    return url;
+  }
+  try {
+    const urlObj = new URL(url);
+    urlObj.searchParams.set('locale', locale);
+    return urlObj.toString();
+  } catch (error) {
+    if (/[?&]locale=[^&]*/.test(url)) {
+      return url.replace(/([?&])locale=[^&]*/, `$1locale=${locale}`);
+    }
+    const separator = url.includes('?') ? '&' : '?';
+    return `${url}${separator}locale=${locale}`;
+  }
+}

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

@@ -0,0 +1,148 @@
+import { executeEvmTransaction, waitForEvmTxConfirm } from '../../integrations/ethereum/tx';
+import type { CallbackArgs } from '../../libs/auth';
+import { getTxMetadata } from '../../libs/util';
+import { type TLineItemExpanded } from '../../store/models';
+import {
+  ensurePayerChangeContext,
+  executeOcapTransactions,
+  getAuthPrincipalClaim,
+  getDelegationTxClaim,
+} from './shared';
+import { EVM_CHAIN_TYPES } from '../../libs/constants';
+
+export default {
+  action: 'change-payer',
+  authPrincipal: false,
+  persistentDynamicClaims: true,
+  claims: {
+    authPrincipal: async ({ extraParams }: CallbackArgs) => {
+      const { paymentMethod } = await ensurePayerChangeContext(extraParams.subscriptionId);
+      return getAuthPrincipalClaim(paymentMethod, 'continue');
+    },
+  },
+  onConnect: async ({ userDid, userPk, extraParams }: CallbackArgs) => {
+    const { subscriptionId } = extraParams;
+    const { subscription, paymentMethod, paymentCurrency, payerAddress } =
+      await ensurePayerChangeContext(subscriptionId);
+
+    if (userDid === payerAddress) {
+      throw new Error('The current payer is the same as the new payer, please use another account to change payer');
+    }
+    const claimsList: any[] = [];
+    // @ts-ignore
+    const items = subscription!.items as TLineItemExpanded[];
+    const trialing = true;
+    const billingThreshold = Number(subscription.billing_thresholds?.amount_gte || 0);
+
+    if (paymentMethod.type === 'arcblock') {
+      claimsList.push({
+        signature: await getDelegationTxClaim({
+          mode: 'delegation',
+          userDid,
+          userPk,
+          nonce: subscription.id,
+          data: getTxMetadata({ subscriptionId: subscription.id }),
+          paymentCurrency,
+          paymentMethod,
+          trialing,
+          billingThreshold,
+          items,
+          requiredStake: false,
+        }),
+      });
+      return claimsList;
+    }
+
+    if (EVM_CHAIN_TYPES.includes(paymentMethod.type)) {
+      if (!paymentCurrency.contract) {
+        throw new Error(`Payment currency ${paymentMethod.type}:${paymentCurrency.id} does not support subscription`);
+      }
+
+      claimsList.push({
+        signature: await getDelegationTxClaim({
+          mode: 'subscription',
+          userDid,
+          userPk,
+          nonce: `change-payer-${subscription!.id}`,
+          data: getTxMetadata({ subscriptionId: subscription!.id }),
+          paymentCurrency,
+          paymentMethod,
+          trialing,
+          billingThreshold,
+          items,
+        }),
+      });
+
+      return claimsList;
+    }
+
+    throw new Error(`ChangePayer: Payment method ${paymentMethod.type} not supported`);
+  },
+
+  onAuth: async ({ request, userDid, userPk, claims, extraParams, step }: CallbackArgs) => {
+    const { subscriptionId } = extraParams;
+    const { subscription, paymentMethod, paymentCurrency } = await ensurePayerChangeContext(subscriptionId);
+
+    const result = request?.context?.store?.result || [];
+    result.push({
+      step,
+      claim: claims?.[0],
+      stepRequest: {
+        headers: request?.headers,
+      },
+    });
+    const claimsList = result.map((x: any) => x.claim);
+
+    const afterTxExecution = async (paymentDetails: any) => {
+      await subscription?.update({
+        payment_settings: {
+          payment_method_types: [paymentMethod.type],
+          payment_method_options: {
+            [paymentMethod.type]: { payer: userDid },
+          },
+        },
+        payment_details: {
+          ...subscription.payment_details,
+          [paymentMethod.type]: {
+            ...(subscription.payment_details?.[paymentMethod.type as keyof typeof subscription.payment_details] || {}),
+            type: 'delegate',
+            payer: userDid,
+            tx_hash: paymentDetails.tx_hash,
+          },
+        },
+      });
+    };
+
+    if (paymentMethod.type === 'arcblock') {
+      const requestArray = result
+        .map((item: { stepRequest?: Request }) => item.stepRequest)
+        .filter(Boolean) as Request[];
+      const requestSource = requestArray.length > 0 ? requestArray : request;
+
+      const paymentDetails = await executeOcapTransactions(
+        userDid,
+        userPk,
+        claimsList,
+        paymentMethod,
+        requestSource,
+        subscription?.id,
+        paymentCurrency.contract
+      );
+
+      await afterTxExecution(paymentDetails);
+      return { hash: paymentDetails.tx_hash };
+    }
+
+    if (EVM_CHAIN_TYPES.includes(paymentMethod.type)) {
+      const paymentDetails = await executeEvmTransaction('approve', userDid, claimsList, paymentMethod);
+      waitForEvmTxConfirm(paymentMethod.getEvmClient(), +paymentDetails.block_height, paymentMethod.confirmation.block)
+        .then(async () => {
+          await afterTxExecution(paymentDetails);
+        })
+        .catch(console.error);
+      return { hash: paymentDetails.tx_hash };
+    }
+
+    throw new Error(`ChangePayer: Payment method ${paymentMethod.type} not supported`);
+  },
+};