payment-kit 1.13.72 → 1.13.74

package/api/src/{jobs → queues}/payment.ts

@@ -4,10 +4,12 @@ import dayjs from '../libs/dayjs';
 import CustomError from '../libs/error';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
-import { getGasPayerExtra, isDelegationSufficientForPayment } from '../libs/payment';
+import { getGasPayerExtra, isBalanceSufficientForPayment, isDelegationSufficientForPayment } from '../libs/payment';
 import createQueue from '../libs/queue';
+import { getDaysUntilDue, getDueUnit } from '../libs/subscription';
 import { MAX_RETRY_COUNT, MIN_RETRY_MAIL, getNextRetry } from '../libs/util';
 import { CheckoutSession } from '../store/models/checkout-session';
+import { Customer } from '../store/models/customer';
 import { Invoice } from '../store/models/invoice';
 import { PaymentCurrency } from '../store/models/payment-currency';
 import { PaymentIntent } from '../store/models/payment-intent';
@@ -21,7 +23,7 @@ type PaymentJob = {
   retryOnError?: boolean;
 };
 
-export const handlePaymentSucceed = async (paymentIntent: PaymentIntent) => {
+export const handlePaymentSucceed = async (paymentIntent: PaymentIntent, invoiceUpdates: any = {}) => {
   let invoice;
   if (paymentIntent.invoice_id) {
     invoice = await Invoice.findByPk(paymentIntent.invoice_id);
@@ -49,8 +51,9 @@ export const handlePaymentSucceed = async (paymentIntent: PaymentIntent) => {
       attempt_count: invoice.attempt_count + 1,
       attempted: true,
       status_transitions: { ...invoice.status_transitions, paid_at: dayjs().unix() },
+      ...invoiceUpdates,
     });
-    logger.info(`Invoice ${invoice.id} updated on payment done: ${paymentIntent.id}`);
+    logger.info(`Invoice ${invoice.id} updated on payment done: ${paymentIntent.id}`, invoiceUpdates);
   }
 
   if (invoice.subscription_id) {
@@ -59,10 +62,15 @@ export const handlePaymentSucceed = async (paymentIntent: PaymentIntent) => {
       if (subscription.status === 'incomplete') {
         await subscription.update({ status: subscription.trail_end ? 'trialing' : 'active' });
         logger.info(`Subscription ${subscription.id} updated on payment done ${invoice.id}`);
-      } else {
-        // FIXME: possible error here
-        await subscription.update({ status: 'active' });
-        logger.info(`Subscription ${subscription.id} moved to active after payment done ${paymentIntent.id}`);
+      } else if (subscription.status === 'past_due') {
+        if (subscription.cancel_at_period_end && subscription.cancelation_details?.reason === 'payment_failed') {
+          // @ts-ignore
+          await subscription.update({ status: 'active', cancel_at_period_end: false, cancelation_details: null });
+          logger.info(`Subscription ${subscription.id} moved to active after payment done ${paymentIntent.id}`);
+        } else {
+          await subscription.update({ status: 'active' });
+          logger.info(`Subscription ${subscription.id} moved to active after payment done ${paymentIntent.id}`);
+        }
       }
     }
 
@@ -84,6 +92,124 @@ export const handlePaymentSucceed = async (paymentIntent: PaymentIntent) => {
   }
 };
 
+type Updates = {
+  retry: {
+    payment: Partial<PaymentIntent>;
+    invoice: Partial<Invoice>;
+  };
+  terminate: {
+    payment: Partial<PaymentIntent>;
+    invoice: Partial<Invoice>;
+  };
+};
+
+export const handlePaymentFailed = async (paymentIntent: PaymentIntent, invoice: Invoice, error: PaymentError) => {
+  const now = dayjs().unix();
+  const attemptCount = invoice.attempt_count + 1;
+
+  const updates: Updates = {
+    retry: {
+      payment: { status: 'requires_capture', last_payment_error: error },
+      invoice: {
+        attempt_count: attemptCount,
+        attempted: true,
+        next_payment_attempt: getNextRetry(attemptCount),
+      },
+    },
+    terminate: {
+      payment: { status: 'requires_action', last_payment_error: error },
+      invoice: {
+        status: 'uncollectible',
+        attempt_count: attemptCount,
+        attempted: true,
+        status_transitions: { ...invoice.status_transitions, marked_uncollectible_at: now },
+      },
+    },
+  };
+
+  if (!invoice.subscription_id) {
+    return updates.retry;
+  }
+  const subscription = await Subscription.findByPk(invoice.subscription_id);
+  if (!subscription) {
+    return updates.retry;
+  }
+
+  if (subscription.status !== 'active') {
+    return updates.retry;
+  }
+
+  // check current period
+  if (subscription.current_period_end <= now) {
+    await subscription.update({
+      status: 'canceled',
+      canceled_at: now,
+      cancelation_details: {
+        comment: 'exceed_current_period',
+        feedback: 'other',
+        reason: 'payment_failed',
+      },
+    });
+    logger.warn('Subscription moved to canceled after retry exceeds current_period_end', {
+      subscription: subscription.id,
+      payment: paymentIntent.id,
+      current_period_end: subscription.current_period_end,
+      now,
+    });
+    return updates.terminate;
+  }
+
+  // check days until due
+  const daysUntilDue = getDaysUntilDue(subscription);
+  if (typeof daysUntilDue === 'number') {
+    const dueUnit = getDueUnit(subscription.pending_invoice_item_interval.interval);
+    const gracePeriodStart = subscription.current_period_start;
+    const graceDuration = daysUntilDue ? daysUntilDue * dueUnit : 0;
+    logger.debug('handlePaymentFailed.checkDue', { now, daysUntilDue, dueUnit, gracePeriodStart, graceDuration });
+    if (gracePeriodStart + graceDuration <= now) {
+      await subscription.update({
+        status: 'past_due',
+        cancel_at_period_end: true,
+        cancelation_details: {
+          comment: 'past_due',
+          feedback: 'other',
+          reason: 'payment_failed',
+        },
+      });
+      logger.warn('Subscription moved to past_due after payment failed', {
+        subscription: subscription.id,
+        payment: paymentIntent.id,
+        gracePeriodStart,
+        graceDuration,
+        dueUnit,
+      });
+      return updates.terminate;
+    }
+  }
+
+  // check max retry
+  if (invoice.attempt_count > MAX_RETRY_COUNT) {
+    await subscription.update({
+      status: 'past_due',
+      cancel_at_period_end: true,
+      cancelation_details: {
+        comment: 'exceed_max_retry',
+        feedback: 'other',
+        reason: 'payment_failed',
+      },
+    });
+    logger.warn('Subscription moved to past_due after max retry', {
+      subscription: subscription.id,
+      payment: paymentIntent.id,
+      attempt_count: invoice.attempt_count,
+    });
+
+    return updates.terminate;
+  }
+
+  return updates.retry;
+};
+
 export const handlePayment = async (job: PaymentJob) => {
   logger.info('handle payment', job);
 
@@ -116,9 +242,16 @@ export const handlePayment = async (job: PaymentJob) => {
     return;
   }
 
+  const customer = await Customer.findByPk(paymentIntent.customer_id);
+  if (!customer) {
+    logger.warn(`Customer not found: ${paymentIntent.customer_id}`);
+    return;
+  }
+
   const invoice = await Invoice.findByPk(paymentIntent.invoice_id);
   const paymentSettings = invoice?.payment_settings || job.paymentSettings;
   if (!paymentSettings) {
+    await paymentIntent.update({ status: 'requires_action' });
     logger.warn('Payment settings not found:', job);
     return;
   }
@@ -132,7 +265,38 @@ export const handlePayment = async (job: PaymentJob) => {
     const client = paymentMethod.getOcapClient();
     const payer = paymentSettings?.payment_method_options.arcblock?.payer;
 
-    // check balance before capture
+    // if we can complete purchase with customer balance
+    const balance = isBalanceSufficientForPayment({
+      paymentMethod,
+      paymentCurrency,
+      customer,
+      amount: paymentIntent.amount,
+    });
+    if (balance.sufficient) {
+      const tmp = await customer.decreaseTokenBalance(paymentCurrency.id, paymentIntent.amount);
+      logger.info(`PaymentIntent capture done: ${paymentIntent.id} with customer balance`, tmp);
+      await paymentIntent.update({
+        status: 'succeeded',
+        amount: '0', // update payment intent amount to 0
+        amount_received: '0',
+        payment_details: {
+          arcblock: {
+            tx_hash: '',
+            payer: payer as string,
+          },
+        },
+      });
+
+      await handlePaymentSucceed(paymentIntent, {
+        starting_token_balance: tmp.starting,
+        ending_token_balance: tmp.ending,
+      });
+      return;
+    }
+
+    // FIXME: support partial payment from balance
+
+    // check balance before capture with transaction
     result = await isDelegationSufficientForPayment({
       paymentMethod,
       paymentCurrency,
@@ -208,7 +372,10 @@ export const handlePayment = async (job: PaymentJob) => {
         });
       }
     } else if (invoice) {
+      // This means we have tried to capture this invoice before, since the retry is managed by invoice queue
       const attemptCount = invoice.attempt_count + 1;
+
+      // 只有在重试次数超过阈值的时候才发送邮件，不然邮件频率太高了，初次邮件时首次失败 6 小时后
       if (attemptCount >= MIN_RETRY_MAIL && invoice.billing_reason === 'subscription_cycle') {
         events.emit('customer.subscription.renew_failed', {
           invoice,
@@ -216,34 +383,19 @@ export const handlePayment = async (job: PaymentJob) => {
         });
       }
 
-      if (invoice.attempt_count > MAX_RETRY_COUNT) {
-        await paymentIntent.update({ status: 'requires_action', last_payment_error: error });
-        await invoice.update({
-          status: 'uncollectible',
-          attempt_count: attemptCount,
-          attempted: true,
-          status_transitions: { ...invoice.status_transitions, marked_uncollectible_at: dayjs().unix() },
-        });
+      const updates = await handlePaymentFailed(paymentIntent, invoice, error);
+      await paymentIntent.update(updates.payment);
+      await invoice.update(updates.invoice);
 
-        // FIXME: send email to customer, pause subscription
-        logger.error('PaymentIntent capture failed after max retry', { id: paymentIntent.id });
-      } else {
-        const retryAt = getNextRetry(attemptCount);
-
-        await paymentIntent.update({ status: 'requires_capture', last_payment_error: error });
-        await invoice.update({
-          attempt_count: attemptCount,
-          attempted: true,
-          next_payment_attempt: retryAt,
-        });
-        logger.error('PaymentIntent capture retry scheduled', { id: paymentIntent.id, retryAt });
-
-        // reschedule next attempt
+      // reschedule next attempt
+      const retryAt = updates.invoice.next_payment_attempt;
+      if (retryAt) {
         paymentQueue.push({
           id: paymentIntent.id,
           job: { paymentIntentId: paymentIntent.id, retryOnError: job.retryOnError },
           runAt: retryAt,
         });
+        logger.error('PaymentIntent capture retry scheduled', { id: paymentIntent.id, retryAt });
       }
     }
   }

package/api/src/{jobs → queues}/subscription.ts

@@ -1,14 +1,13 @@
-import { BN } from '@ocap/util';
 import type { LiteralUnion } from 'type-fest';
 
 import dayjs from '../libs/dayjs';
 import logger from '../libs/logger';
 import createQueue from '../libs/queue';
 import { getStatementDescriptor, getSubscriptionCycleAmount, getSubscriptionCycleSetup } from '../libs/session';
+import { ensureInvoiceAndItems } from '../routes/connect/shared';
 import { PaymentCurrency, PaymentMethod, UsageRecord } from '../store/models';
 import { Customer } from '../store/models/customer';
 import { Invoice } from '../store/models/invoice';
-import { InvoiceItem } from '../store/models/invoice-item';
 import { Price } from '../store/models/price';
 import { Subscription } from '../store/models/subscription';
 import { SubscriptionItem } from '../store/models/subscription-item';
@@ -19,6 +18,8 @@ type SubscriptionJob = {
   action?: LiteralUnion<'cycle' | 'cancel' | 'pause' | 'resume', string>;
 };
 
+const EXPECTED_SUBSCRIPTION_STATUS = ['trialing', 'active', 'paused', 'past_due'];
+
 // generate invoice for subscription periodically
 export const handleSubscription = async (job: SubscriptionJob) => {
   logger.info('handle subscription', job);
@@ -28,7 +29,7 @@ export const handleSubscription = async (job: SubscriptionJob) => {
     logger.warn(`Subscription not found: ${job.subscriptionId}`);
     return;
   }
-  if (['trialing', 'active', 'paused'].includes(subscription.status) === false) {
+  if (EXPECTED_SUBSCRIPTION_STATUS.includes(subscription.status) === false) {
     logger.warn(`Subscription status not expected: ${job.subscriptionId}`);
     return;
   }
@@ -41,7 +42,7 @@ export const handleSubscription = async (job: SubscriptionJob) => {
   const now = dayjs().unix();
 
   // Do we need to cancel the subscription
-  if (subscription.status === 'active') {
+  if (subscription.isImmutable() === false) {
     if (subscription.cancel_at_period_end) {
       await subscription.update({ status: 'canceled', canceled_at: now });
       logger.warn(`Subscription canceled on period end: ${job.subscriptionId}`);
@@ -55,11 +56,7 @@ export const handleSubscription = async (job: SubscriptionJob) => {
   }
 
   // Do we need to resume the subscription
-  if (
-    subscription.status === 'paused' &&
-    subscription.pause_collection?.resumes_at &&
-    subscription.pause_collection?.resumes_at <= now
-  ) {
+  if (subscription.pause_collection?.resumes_at && subscription.pause_collection?.resumes_at <= now) {
     await subscription.update({ status: 'active', pause_collection: undefined });
     logger.warn(`Subscription resumed as scheduled: ${job.subscriptionId}`);
   }
@@ -118,14 +115,14 @@ export const handleSubscription = async (job: SubscriptionJob) => {
 
   // set invoice status if subscription paused
   let status = 'open';
-  if (subscription.status === 'paused') {
-    if (subscription.pause_collection?.behavior === 'mark_uncollectible') {
+  if (subscription.pause_collection) {
+    if (subscription.pause_collection.behavior === 'mark_uncollectible') {
       status = 'uncollectible';
     }
-    if (subscription.pause_collection?.behavior === 'void') {
+    if (subscription.pause_collection.behavior === 'void') {
       status = 'void';
     }
-    if (subscription.pause_collection?.behavior === 'keep_as_draft') {
+    if (subscription.pause_collection.behavior === 'keep_as_draft') {
       status = 'draft';
     }
   }
@@ -166,95 +163,30 @@ export const handleSubscription = async (job: SubscriptionJob) => {
     })
   );
 
-  const amount = getSubscriptionCycleAmount(expandedItems, currency);
-
-  // create invoice
-  const invoice = await Invoice.create({
-    livemode: subscription.livemode,
-    number: await customer.getInvoiceNumber(),
-    description: 'Subscription cycle',
-    statement_descriptor: getStatementDescriptor(expandedItems),
-    period_start: setup.period.start,
-    period_end: setup.period.end,
-
-    auto_advance: true,
-    paid: false,
-    paid_out_of_band: false,
-
-    status,
-    collection_method: 'charge_automatically',
-    billing_reason: 'subscription_cycle',
-
-    currency_id: subscription.currency_id,
-    customer_id: customer.id,
-    payment_intent_id: '',
-    subscription_id: subscription?.id,
-    checkout_session_id: '',
-
-    subtotal: amount.total,
-    subtotal_excluding_tax: amount.total,
-    tax: '0',
-    total: amount.total,
-    amount_due: amount.total,
-    amount_paid: '0',
-    amount_remaining: amount.total,
-    amount_shipping: '0',
-
-    starting_balance: '0',
-    ending_balance: '0',
-
-    attempt_count: 0,
-    attempted: false,
-    // next_payment_attempt: undefined,
-
-    custom_fields: [],
-    customer_address: customer.address,
-    customer_email: customer.email,
-    customer_name: customer.name,
-    customer_phone: customer.phone,
-
-    discounts: [],
-    total_discount_amounts: [],
-
-    due_date: undefined, // The date on which payment for this invoice is due
-    effective_at: dayjs().unix(), // The date when this invoice is in effect
-    status_transitions: {
-      finalized_at: dayjs().unix(),
-    },
-
-    payment_settings: subscription.payment_settings,
-    default_payment_method_id: subscription.default_payment_method_id as string,
-
-    account_country: '',
-    account_name: '',
-    metadata: {},
+  const amount = getSubscriptionCycleAmount(expandedItems, currency.id);
+
+  const { invoice } = await ensureInvoiceAndItems({
+    customer,
+    subscription,
+    trailing: false,
+    metered: true,
+    lineItems: expandedItems,
+    props: {
+      livemode: subscription.livemode,
+      description: 'Subscription cycle',
+      statement_descriptor: getStatementDescriptor(expandedItems),
+      period_start: setup.period.start,
+      period_end: setup.period.end,
+      auto_advance: true,
+      status,
+      billing_reason: 'subscription_cycle',
+      currency_id: subscription.currency_id,
+      total: amount.total,
+      payment_settings: subscription.payment_settings,
+      default_payment_method_id: subscription.default_payment_method_id,
+      metadata: {},
+    } as Invoice,
   });
-  logger.info(`Invoice created for subscription ${subscription.id}: ${invoice.id}`);
-
-  // create invoice items
-  await Promise.all(
-    expandedItems.map((x: any) =>
-      InvoiceItem.create({
-        livemode: subscription.livemode,
-        amount: new BN(x.price.unit_amount).mul(new BN(x.quantity)).toString(),
-        quantity: x.quantity,
-        description: x.price.product.name,
-        period: { start: setup.period.start, end: setup.period.end },
-        currency_id: subscription.currency_id,
-        customer_id: customer.id,
-        price_id: x.price_id,
-        invoice_id: invoice.id,
-        subscription_id: subscription.id,
-        subscription_item_id: subscriptionItems.find((si) => si.price_id === x.price_id)?.id,
-        discountable: false,
-        discounts: [],
-        discount_amounts: [],
-        proration: false,
-        proration_details: {},
-        metadata: {},
-      })
-    )
-  );
 
   // schedule invoice job
   invoiceQueue.push({ id: invoice.id, job: { invoiceId: invoice.id, retryOnError: true } });
@@ -268,8 +200,8 @@ export const handleSubscription = async (job: SubscriptionJob) => {
   });
   logger.info(`Subscription updated for new billing cycle: ${subscription.id}`);
 
-  // schedule next billing cycle if we are not cancelling
-  if (!subscription.cancel_at_period_end) {
+  // schedule next billing cycle if we are not in terminal state
+  if (subscription.isActive()) {
     subscriptionQueue.push({
       id: subscription.id,
       job: { subscriptionId: subscription.id, action: 'cycle' },
@@ -292,7 +224,7 @@ export const subscriptionQueue = createQueue<SubscriptionJob>({
 export const startSubscriptionQueue = async () => {
   const subscriptions = await Subscription.findAll({
     where: {
-      status: ['trialing', 'active', 'paused'],
+      status: EXPECTED_SUBSCRIPTION_STATUS,
     },
   });
 

package/api/src/{jobs → queues}/webhook.ts

@@ -101,6 +101,8 @@ export const handleWebhook = async (job: WebhookJob) => {
           runAt: getNextRetry(retryCount),
         });
       });
+    } else {
+      await event.decrement('pending_webhooks');
     }
   }
 };