payment-kit 1.27.2 → 1.28.0

package/api/src/routes/connect/pay.ts

@@ -6,6 +6,7 @@ import { encodeTransferItx } from '../../integrations/ethereum/token';
 import { executeEvmTransaction, waitForEvmTxConfirm } from '../../integrations/ethereum/tx';
 import { CallbackArgs, ethWallet } from '../../libs/auth';
 import logger from '../../libs/logger';
+import { parseChainError } from '../../libs/chain-error';
 import { getGasPayerExtra } from '../../libs/payment';
 import { createPaymentOutput } from '../../libs/session';
 import { getTxMetadata } from '../../libs/util';
@@ -130,6 +131,9 @@ export default {
         const client = paymentMethod.getOcapClient();
         const claim = claims.find((x) => x.type === 'prepareTx');
 
+        // Warm up chain context cache to avoid setTimeout(resolve,0) hang in workerd
+        await client.getContext();
+
         const tx: Partial<Transaction> = client.decodeTx(claim.finalTx);
         if (claim.delegator && claim.from) {
           tx.delegator = claim.delegator;
@@ -227,10 +231,15 @@ export default {
 
         return { hash: txHash };
       } catch (err) {
-        console.error(err);
-        logger.error('Failed to finalize paymentIntent on arcblock', { paymentIntent: paymentIntent.id, error: err });
+        const parsed = parseChainError(err);
+        logger.error('Failed to finalize paymentIntent on arcblock', {
+          paymentIntentId: paymentIntent.id,
+          code: parsed.code,
+          details: parsed.details,
+          raw: err,
+        });
         await paymentIntent.update({ status: 'requires_capture' });
-        throw err;
+        throw parsed;
       }
     }
 

package/api/src/routes/connect/setup.ts

@@ -101,6 +101,8 @@ export default {
             billingThreshold: Math.max(minStakeAmount, billingThreshold),
             items,
             slippageConfig: subscription?.slippage_config || undefined,
+            // Reuse DelegateState fetched above — avoids a duplicate chain RPC on CF cold isolates
+            delegateState: delegation.state,
           }),
         });
       }
@@ -217,7 +219,7 @@ export default {
 
       await checkoutSession.update({ status: 'complete', payment_status: 'paid' });
       if (invoice) {
-        invoiceQueue.pushAndWait({ id: invoice.id, job: { invoiceId: invoice.id, retryOnError: false } });
+        await invoiceQueue.pushAndWait({ id: invoice.id, job: { invoiceId: invoice.id, retryOnError: false } });
       }
       await addSubscriptionJob(subscription, 'cycle', false, subscription.trial_end);
       logger.info('CheckoutSession updated on setup done', {

package/api/src/routes/connect/shared.ts

@@ -1,12 +1,12 @@
 /* eslint-disable @typescript-eslint/indent */
 /* eslint-disable prettier/prettier */
 import { toTypeInfo } from '@arcblock/did';
-import { toDelegateAddress } from '@arcblock/did-util';
-import type { Transaction } from '@ocap/client';
+import { toDelegateAddress } from '@arcblock/did-util/cbor';
+import type { DelegateState as DelegateStateType, Transaction } from '@ocap/client';
 import { BN, fromTokenToUnit, toBase58 } from '@ocap/util';
 import { fromPublicKey } from '@ocap/wallet';
 import type { Request } from 'express';
-import { isEmpty } from 'lodash';
+import isEmpty from 'lodash/isEmpty';
 import dayjs from '../../libs/dayjs';
 import { estimateMaxGasForTx, hasStakedForGas } from '../../integrations/arcblock/stake';
 import { encodeApproveItx } from '../../integrations/ethereum/token';
@@ -31,6 +31,7 @@ import {
 } from '../../libs/subscription';
 import { getCustomerStakeAddress, OCAP_PAYMENT_TX_TYPE } from '../../libs/util';
 
+// eslint-disable-next-line import/no-cycle
 import { invoiceQueue } from '../../queues/invoice';
 import { AutoRechargeConfig, type TLineItemExpanded } from '../../store/models';
 import { CheckoutSession } from '../../store/models/checkout-session';
@@ -453,8 +454,6 @@ export async function ensureInvoiceForCheckout({
     }
   }
 
-  const currency = await PaymentCurrency.findByPk(checkoutSession.currency_id);
-
   const metadata = {
     ...(checkoutSession.invoice_creation?.invoice_data?.metadata || {}),
   };
@@ -467,7 +466,13 @@ export async function ensureInvoiceForCheckout({
   const trialInDays = Number(checkoutSession.subscription_data?.trial_period_days || 0);
   const trialEnd = Number(checkoutSession.subscription_data?.trial_end || 0);
   const now = dayjs().unix();
-  let invoiceItems = lineItems || (await Price.expand(checkoutSession.line_items, { product: true, upsell: true }));
+
+  // Parallel: fetch currency + expand line items (independent queries)
+  const [currency, expandedItems] = await Promise.all([
+    PaymentCurrency.findByPk(checkoutSession.currency_id),
+    lineItems ? Promise.resolve(lineItems) : Price.expand(checkoutSession.line_items, { product: true, upsell: true }),
+  ]);
+  let invoiceItems = expandedItems;
 
   // For items with quote_id, fetch full quote info and attach to line item metadata
   // This ensures invoice line items have complete quote info for display
@@ -610,33 +615,21 @@ export async function ensureInvoiceForCheckout({
     discountCount: discountInfo.appliedDiscounts.length,
   });
 
-  // only update invoice_id for single invoice
-  if (!isGroupInvoice) {
-    await checkoutSession.update({ invoice_id: invoice.id });
-  }
-  if (paymentIntent) {
-    await paymentIntent.update({ invoice_id: invoice.id });
-  }
-  if (subscription) {
-    await subscription.update({ latest_invoice_id: invoice.id });
-  }
-
-  // Update quotes with invoice_id for audit trail
-  // Find quote_ids from invoice items and update the quotes
+  // Update invoice_id references in parallel — these are independent writes
   const quoteIdsFromItems = items
     .map((item) => item.metadata?.quote_id)
     .filter((id): id is string => typeof id === 'string' && id.length > 0);
 
-  if (quoteIdsFromItems.length > 0) {
-    await PriceQuote.update(
-      { invoice_id: invoice.id },
-      { where: { id: quoteIdsFromItems } }
-    );
-    logger.info('Updated quotes with invoice_id', {
-      invoiceId: invoice.id,
-      quoteIds: quoteIdsFromItems,
-    });
-  }
+  await Promise.all([
+    !isGroupInvoice ? checkoutSession.update({ invoice_id: invoice.id }) : Promise.resolve(),
+    paymentIntent ? paymentIntent.update({ invoice_id: invoice.id }) : Promise.resolve(),
+    subscription ? subscription.update({ latest_invoice_id: invoice.id }) : Promise.resolve(),
+    quoteIdsFromItems.length > 0
+      ? PriceQuote.update({ invoice_id: invoice.id }, { where: { id: quoteIdsFromItems } }).then(() => {
+          logger.info('Updated quotes with invoice_id', { invoiceId: invoice.id, quoteIds: quoteIdsFromItems });
+        })
+      : Promise.resolve(),
+  ]);
 
   return { invoice, items };
 }
@@ -861,6 +854,7 @@ export async function getDelegationTxClaim({
   billingThreshold = 0,
   requiredStake = true,
   slippageConfig,
+  delegateState,
 }: {
   userDid: string;
   userPk: string;
@@ -880,6 +874,10 @@ export async function getDelegationTxClaim({
     min_acceptable_rate?: string;
     base_currency?: string;
   };
+  // Optional DelegateState passthrough — avoids a duplicate chain RPC in getTokenLimitsForDelegation
+  // when the caller already fetched it (e.g. via isDelegationSufficientForPayment). Same-request
+  // usage only — do not cache across requests (see delegationCache note in libs/payment.ts).
+  delegateState?: DelegateStateType | null;
 }) {
   // Calculate authorization amount
   // When slippage_config with min_acceptable_rate is provided, use it for precise calculation
@@ -902,16 +900,23 @@ export async function getDelegationTxClaim({
   }
 
   const address = toDelegateAddress(userDid, wallet.address);
-  const tokenLimits = await getTokenLimitsForDelegation(items, paymentMethod, paymentCurrency, address, amount);
-  let tokenRequirements = await getTokenRequirements({
-    items,
-    mode,
-    trialing,
-    billingThreshold,
-    paymentMethod,
-    paymentCurrency,
-    requiredStake,
-  });
+  // These two helpers each issue 1–2 chain RPCs and don't depend on each other,
+  // so fan them out — on CF Workers cold isolates the serial path easily pushed the
+  // request over the runtime CPU/real-time budget and tripped a "hung promise" 500
+  // (see #1351). Parallelising halves the wall-clock for the delegation tx claim.
+  const [tokenLimits, tokenRequirementsResult] = await Promise.all([
+    getTokenLimitsForDelegation(items, paymentMethod, paymentCurrency, address, amount, delegateState),
+    getTokenRequirements({
+      items,
+      mode,
+      trialing,
+      billingThreshold,
+      paymentMethod,
+      paymentCurrency,
+      requiredStake,
+    }),
+  ]);
+  let tokenRequirements = tokenRequirementsResult;
 
   if (mode === 'delegation') {
     tokenRequirements = [];
@@ -1049,6 +1054,9 @@ export async function getStakeTxClaim({
   if (paymentMethod.type === 'arcblock') {
     // create staking data
     const client = paymentMethod.getOcapClient();
+    // CF Workers: warm up chain context to avoid setTimeout(resolve,0) hang on cold client.
+    // Same pattern as pay.ts; needed because did-connect-js tryWithTimeout bounds this callback at 10s.
+    await client.getContext();
 
     const stakeId = hasGrouping ? `stake-group-${subscription.id}` : subscription.id;
 
@@ -1155,6 +1163,8 @@ export async function getOverdraftProtectionStakeTxClaim({
   if (paymentMethod.type === 'arcblock') {
     // create staking data
     const client = paymentMethod.getOcapClient();
+    // CF Workers: warm up chain context to avoid setTimeout(resolve,0) hang on cold client.
+    await client.getContext();
     const nonce = `overdraft-protection-${subscription.id}`;
     const address = await getCustomerStakeAddress(userDid, nonce);
     const { state } = await client.getStakeState({ address });
@@ -1579,6 +1589,9 @@ export async function executeOcapTransactions(
   nonce?: string
 ) {
   const client = paymentMethod.getOcapClient();
+  // CF Workers: warm up chain context to avoid setTimeout(resolve,0) hang on cold client.
+  // Each subsequent executeSingleTransaction (Delegate + Stake broadcast) needs ready context.
+  await client.getContext();
   logger.info('start executeOcapTransactions', { userDid, claims });
 
   const delegation = claims.find((x) => x.type === 'signature' && x.meta?.purpose === 'delegation');

package/api/src/routes/connect/subscribe.ts

@@ -133,6 +133,8 @@ export default {
             items,
             requiredStake,
             slippageConfig: primarySubscription?.slippage_config || undefined,
+            // Reuse DelegateState fetched above — avoids a duplicate chain RPC on CF cold isolates
+            delegateState: delegation.state,
           }),
         });
       }
@@ -243,7 +245,8 @@ export default {
 
       for (const invoice of invoices) {
         if (invoice) {
-          invoiceQueue.pushAndWait({ id: invoice.id, job: { invoiceId: invoice.id, retryOnError: false } });
+          // eslint-disable-next-line no-await-in-loop
+          await invoiceQueue.pushAndWait({ id: invoice.id, job: { invoiceId: invoice.id, retryOnError: false } });
         }
       }
 

package/api/src/routes/credit-grants.ts

@@ -27,6 +27,7 @@ import { blocklet } from '../libs/auth';
 import { formatMetadata } from '../libs/util';
 import { getPriceUintAmountByCurrency } from '../libs/price';
 import { checkTokenBalance } from '../libs/payment';
+import { measurePhase } from '../libs/timing';
 import { getExchangeRateService } from '../libs/exchange-rate/service';
 import { getExchangeRateSymbol, hasTokenAddress } from '../libs/exchange-rate/token-address-mapping';
 import { isRateBelowMinAcceptableRate } from '../libs/slippage';
@@ -290,16 +291,19 @@ router.get('/verify-availability', authMine, async (req, res) => {
     const { customer_id: customerId, currency_id: currencyId } = value;
     let pendingAmount = value.pending_amount;
 
-    const customer = await Customer.findByPkOrDid(customerId);
+    // Parallelize Customer + PaymentCurrency lookups (independent, saves ~85ms RTT)
+    const [customer, currency] = await Promise.all([
+      Customer.findByPkOrDid(customerId),
+      PaymentCurrency.findByPk(currencyId),
+    ]);
     if (!customer) {
       return res.status(404).json({ error: `Customer ${customerId} not found` });
     }
-
-    const currency = await PaymentCurrency.findByPk(currencyId);
     if (!currency) {
       return res.status(404).json({ error: `PaymentCurrency ${currencyId} not found` });
     }
 
+    // AutoRechargeConfig needs customer.id which we now have
     const config = (await AutoRechargeConfig.findOne({
       where: {
         customer_id: customer.id,
@@ -511,13 +515,15 @@ router.get('/verify-availability', authMine, async (req, res) => {
       // This ensures user can pay off pending amount and still have balance for continued usage
       // minimumRequiredBalance = requiredPaymentAmount (to pay off pending) + totalAmount (for one more recharge)
       const minimumRequiredBalance = requiredPaymentAmount.add(totalAmount);
-      balanceResult = await checkTokenBalance({
-        paymentMethod: config.paymentMethod,
-        paymentCurrency: config.rechargeCurrency,
-        userDid: payer,
-        amount: minimumRequiredBalance.toString(),
-        skipUserCheck: true,
-      });
+      balanceResult = await measurePhase('chain', () =>
+        checkTokenBalance({
+          paymentMethod: config.paymentMethod!,
+          paymentCurrency: config.rechargeCurrency!,
+          userDid: payer,
+          amount: minimumRequiredBalance.toString(),
+          skipUserCheck: true,
+        })
+      );
 
       if (!balanceResult.sufficient) {
         return res.json({
@@ -531,13 +537,15 @@ router.get('/verify-availability', authMine, async (req, res) => {
       }
     } else {
       // No pending amount: check if balance can cover at least one recharge
-      balanceResult = await checkTokenBalance({
-        paymentMethod: config.paymentMethod,
-        paymentCurrency: config.rechargeCurrency,
-        userDid: payer,
-        amount: totalAmount.toString(),
-        skipUserCheck: true,
-      });
+      balanceResult = await measurePhase('chain', () =>
+        checkTokenBalance({
+          paymentMethod: config.paymentMethod!,
+          paymentCurrency: config.rechargeCurrency!,
+          userDid: payer,
+          amount: totalAmount.toString(),
+          skipUserCheck: true,
+        })
+      );
 
       if (!balanceResult.sufficient) {
         return res.json({

package/api/src/routes/donations.ts

@@ -1,4 +1,4 @@
-import { Joi } from '@arcblock/validator';
+import Joi from 'joi';
 import { Router } from 'express';
 
 import { BN } from '@ocap/util';
@@ -24,7 +24,7 @@ const donationSchema = Joi.object<DonationSettings>({
   beneficiaries: Joi.array()
     .items(
       Joi.object({
-        address: Joi.DID().required(),
+        address: Joi.string().required(),
         share: Joi.number().positive().required(),
         memo: Joi.string().max(64).optional(),
       })

package/api/src/routes/meter-events.ts

@@ -414,12 +414,22 @@ router.get('/overdue-summary', auth, async (req, res) => {
       currencyIds.length > 0 ? await PaymentCurrency.findAll({ where: { id: { [Op.in]: currencyIds } } }) : [];
     const currencyMap = new Map(currencies.map((c) => [c.id, c]));
 
-    const list = results.map((r) => ({
-      currency: currencyMap.get(r.currency_id),
-      total_pending: r.total_pending,
-      customer_count: r.customer_count,
-      event_count: r.event_count,
-    }));
+    // Filter out results whose currency no longer exists (e.g. deleted currency)
+    const list = results
+      .map((r) => {
+        const currency = currencyMap.get(r.currency_id);
+        if (!currency) {
+          logger.warn('overdue-summary: currency not found, skipping row', { currency_id: r.currency_id });
+          return null;
+        }
+        return {
+          currency,
+          total_pending: r.total_pending,
+          customer_count: r.customer_count,
+          event_count: r.event_count,
+        };
+      })
+      .filter((item): item is NonNullable<typeof item> => item !== null);
 
     return res.json({ list });
   } catch (err) {

package/api/src/routes/payment-links.ts

@@ -1,4 +1,4 @@
-import { Joi } from '@arcblock/validator';
+import Joi from 'joi';
 import { Router } from 'express';
 import pick from 'lodash/pick';
 import { Op } from 'sequelize';

package/api/src/routes/payment-methods.ts

@@ -6,7 +6,7 @@ import pick from 'lodash/pick';
 import { InferAttributes, Op, WhereOptions } from 'sequelize';
 import cloneDeep from 'lodash/cloneDeep';
 import merge from 'lodash/merge';
-import { Joi } from '@arcblock/validator';
+import Joi from 'joi';
 import { ensureWebhookRegistered, cleanupStripeWebhook, validateStripeKeys } from '../integrations/stripe/setup';
 import logger from '../libs/logger';
 import { authenticate } from '../libs/security';

package/api/src/routes/settings.ts

@@ -3,7 +3,7 @@ import pick from 'lodash/pick';
 import { Op, type WhereOptions } from 'sequelize';
 
 import Joi from 'joi';
-import { merge } from 'lodash';
+import merge from 'lodash/merge';
 import { PaymentCurrency } from '../store/models/payment-currency';
 import { PaymentMethod } from '../store/models/payment-method';
 import { authenticate } from '../libs/security';

package/api/src/routes/tax-rates.ts

@@ -77,7 +77,7 @@ router.get('/', auth, async (req, res) => {
             literal(`(
               SELECT COUNT(DISTINCT ii.invoice_id)
               FROM invoice_items AS ii
-              WHERE ii.tax_rate_id = TaxRate.id
+              WHERE ii.tax_rate_id = tax_rates.id
             )`),
             'invoice_count',
           ],

package/api/src/store/models/customer.ts

@@ -13,9 +13,9 @@ import {
 } from 'sequelize';
 
 import merge from 'lodash/merge';
+import { getLock } from '../../libs/lock';
 import { createEvent } from '../../libs/audit';
 import CustomError from '../../libs/error';
-import { getLock } from '../../libs/lock';
 import { createCodeGenerator, createIdGenerator } from '../../libs/util';
 import type { CustomerAddress, CustomerPreferences, CustomerShipping } from './types';
 
@@ -156,6 +156,28 @@ export class Customer extends Model<InferAttributes<Customer>, InferCreationAttr
   };
 
   public async getInvoiceNumber() {
+    // Optimized path for CF Workers: atomic UPDATE...RETURNING in 1 D1 round trip.
+    // Original lock-based approach: lock.acquire → reload → increment(UPDATE + reload) → release
+    //   = 2 D1 round trips for lock + 3 D1 round trips for data = ~1000ms at ~350ms/RT
+    // Optimized: single UPDATE...RETURNING = 1 D1 round trip = ~350ms
+    //
+    // SQLite serializes writes at the DB level, so the application-level lock is
+    // redundant for both D1 and Blocklet Server's SQLite.
+    const d1 = (globalThis as any).__CF_ENV__?.DB;
+    if (d1) {
+      try {
+        const sql =
+          // eslint-disable-next-line @typescript-eslint/quotes
+          'UPDATE "customers" SET "next_invoice_sequence" = COALESCE("next_invoice_sequence", 1) + 1 WHERE "id" = ? RETURNING "next_invoice_sequence" - 1 as "prev_sequence"';
+        const result = await d1.prepare(sql).bind(this.id).first();
+        const sequence = (result as any)?.prev_sequence ?? 1;
+        return `${this.invoice_prefix}-${padStart(sequence.toString(), 4, '0')}`;
+      } catch (err) {
+        console.warn('[getInvoiceNumber] D1 RETURNING failed, falling back:', (err as any)?.message);
+      }
+    }
+
+    // Blocklet Server path (or D1 fallback): use lock-based approach
     const lock = getLock(`${this.id}-invoice-number`);
     await lock.acquire();
     await this.reload();

package/api/src/store/models/payment-method.ts

@@ -207,6 +207,10 @@ export class PaymentMethod extends Model<InferAttributes<PaymentMethod>, InferCr
     const host = this.settings.arcblock?.api_host;
     const cached = ocapClients.has(host);
     if (!cached) {
+      // 1.30.9: the default `@ocap/client` entry went CBOR-only, but current ABT
+      // wallets only decode protobuf-encoded tx bytes. Use `@ocap/client/legacy`
+      // (protobuf client) so encode / decode / broadcast all stay protobuf,
+      // matching the wallet signatures and what the chain node expects to hash.
       const created = new OcapClient(host);
       ocapClients.set(host, created);
       return created;

package/api/src/store/models/price.ts

@@ -438,23 +438,32 @@ export class Price extends Model<InferAttributes<Price>, InferCreationAttributes
       }
     });
 
-    // expand upsell
+    // expand upsell — batch load to avoid N+1 queries
     if (upsell) {
-      await Promise.all(
-        prices.map(async (x) => {
-          if (x.upsell?.upsells_to_id) {
-            const to = await Price.findByPk(x.upsell?.upsells_to_id);
-            if (to) {
-              // @ts-ignore
-              x.upsell.upsells_to = to;
-            }
-          }
-          if (x.recurring?.meter_id) {
+      const upsellToIds = [...new Set(prices.map((x) => x.upsell?.upsells_to_id).filter(Boolean))] as string[];
+      const meterIds = [...new Set(prices.map((x) => x.recurring?.meter_id).filter(Boolean))] as string[];
+
+      const [upsellPrices, meters] = await Promise.all([
+        upsellToIds.length > 0 ? Price.findAll({ where: { id: upsellToIds } }) : [],
+        meterIds.length > 0 ? Meter.findAll({ where: { id: meterIds } }) : [],
+      ]);
+
+      const upsellPriceMap = new Map(upsellPrices.map((p) => [p.id, p]));
+      const meterMap = new Map(meters.map((m) => [m.id, m]));
+
+      prices.forEach((x) => {
+        if (x.upsell?.upsells_to_id) {
+          const to = upsellPriceMap.get(x.upsell.upsells_to_id);
+          if (to) {
             // @ts-ignore
-            x.meter = await Meter.findByPk(x.recurring?.meter_id);
+            x.upsell.upsells_to = to;
           }
-        })
-      );
+        }
+        if (x.recurring?.meter_id) {
+          // @ts-ignore
+          x.meter = meterMap.get(x.recurring.meter_id) ?? null;
+        }
+      });
     }
 
     // @ts-ignore

package/api/tests/libs/wallet-migration.spec.ts

@@ -79,7 +79,7 @@ describe('wallet-migration', () => {
 
     it('should return stored address if available and valid', async () => {
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           if (address === 'stored_delegation_address') {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
           }
@@ -105,7 +105,7 @@ describe('wallet-migration', () => {
     it('should fallback if stored address has no valid state', async () => {
       const oldAddress = toDelegateAddress(delegator, oldAppDid);
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           // stored address has no state, but migratedFrom address has
           if (address === oldAddress) {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
@@ -131,7 +131,7 @@ describe('wallet-migration', () => {
     it('should return current address if delegation exists on current wallet', async () => {
       const currentAddress = toDelegateAddress(delegator, currentWalletAddress);
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           if (address === currentAddress) {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
           }
@@ -154,7 +154,7 @@ describe('wallet-migration', () => {
     it('should fallback to migratedFrom addresses', async () => {
       const oldAddress = toDelegateAddress(delegator, oldAppDid);
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           if (address === oldAddress) {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
           }

package/api/tests/queues/credit-consume-batch.spec.ts

@@ -248,13 +248,16 @@ describe('credit-consume: handleBatchCreditConsumption', () => {
     expect(event1.update).toHaveBeenCalledWith(expect.objectContaining({ status: 'completed' }));
 
     // Event 2 should fail — only 20 remaining but needs 80
-    // It should have partial consumption saved and be marked for retry
+    // Partial consumption is saved and event leaves the retry chain immediately
+    // (Insufficient balance is non-retryable per Plan 3, 2026-04-25 — retry
+    // would only re-trip the same shortage until external credit top-up).
     expect(event2.update).toHaveBeenCalledWith(
       expect.objectContaining({
         credit_pending: expect.any(String),
       })
     );
-    expect(event2.markAsRequiresCapture).toHaveBeenCalled();
+    expect(event2.markAsRequiresAction).toHaveBeenCalled();
+    expect(event2.markAsRequiresCapture).not.toHaveBeenCalled();
 
     expect(getLock().release).toHaveBeenCalled();
   });

package/api/tests/queues/credit-consume.spec.ts

@@ -386,7 +386,11 @@ describe('credit-consume: handleCreditConsumption', () => {
   // ==========================================
   // Scenario 22/23: Retry scheduling + max retries
   // ==========================================
-  it('scenario 22: schedules retry on partial failure', async () => {
+  it('scenario 22: insufficient balance is non-retryable (goes straight to requires_action)', async () => {
+    // Insufficient credit balance only resolves via external top-up; retrying
+    // before that is guaranteed to fail again. Per Plan 3 (2026-04-25), this
+    // is classified as non-retryable so the event leaves the retry chain
+    // immediately rather than spawning N more delayed queue messages.
     const event = makeMeterEvent({
       getValue: jest.fn().mockReturnValue('500'),
       attempt_count: 0,
@@ -397,10 +401,10 @@ describe('credit-consume: handleCreditConsumption', () => {
 
     setupBasicMocks(event, meter, customer, [grant]);
 
-    await expect(handleCreditConsumption({ meterEventId: 'me_1' })).rejects.toThrow();
+    await expect(handleCreditConsumption({ meterEventId: 'me_1' })).rejects.toThrow(/Insufficient credit balance/);
 
-    // Should schedule retry (attempt_count=0 < MAX_RETRY_COUNT=3)
-    expect(event.markAsRequiresCapture).toHaveBeenCalled();
+    expect(event.markAsRequiresAction).toHaveBeenCalled();
+    expect(event.markAsRequiresCapture).not.toHaveBeenCalled();
   });
 
   it('scenario 23: marks as requires_action after max retries', async () => {

package/api/tests/routes/credit-grants.spec.ts

@@ -92,6 +92,7 @@ describe('GET /api/credit-grants/verify-availability', () => {
     it('should return 404 if customer not found', async () => {
       if (!routeHandler) return;
       jest.spyOn(Customer, 'findByPkOrDid').mockResolvedValue(null as any);
+      jest.spyOn(PaymentCurrency, 'findByPk').mockResolvedValue({ id: 'currency_123' } as any);
 
       await routeHandler(mockReq as Request, mockRes as Response);
 

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