payment-kit 1.20.9 → 1.20.11

package/README.md

@@ -1,46 +1,47 @@
 # Payment Kit
 
-The decentralized stripe for blocklet platform.
+The decentralized Stripe for the Blocklet platform.
 
 ## Contribution
 
 ### Development
 
-1. clone the repo
-2. run `make build`
-3. run `cd blocklets/core && blocklet dev`
+1. Clone the repository
+2. Run `make build`
+3. Run `cd blocklets/core && blocklet dev`
 
-##### when error
+#### Troubleshooting
 
-1. pre-start error component xxx is not running or unreachable
+**Error: "pre-start error component xxx is not running or unreachable"**
 
-- create .env.local file in this root
-  - add BLOCKLET_DEV_APP_DID="did:abt:your payment kit server did"
-  - add BLOCKLET_DEV_MOUNT_POINT="/example"
-- copy .env.local to be under the /core
-  - edit BLOCKLET_DEV_MOUNT_POINT="/"
+- Create a `.env.local` file in the project root
+  - Add `BLOCKLET_DEV_APP_DID="did:abt:your payment kit server did"`
+  - Add `BLOCKLET_DEV_MOUNT_POINT="/example"`
+- Copy `.env.local` to the `/core` directory
+  - Edit `BLOCKLET_DEV_MOUNT_POINT="/"`
 
-2. Insufficient fund to pay for tx cost from xxx, expected 1.0020909, got 0
-   - copy BLOCKLET_DEV_APP_DID
-   - transfer 2 TBA in your DID Wallet to your copied address
+**Error: "Insufficient funds to pay for transaction cost from xxx, expected 1.0020909, got 0"**
+
+- Copy the `BLOCKLET_DEV_APP_DID`
+- Transfer 2 TBA from your DID Wallet to the copied address
 
 ### Debug Stripe
 
-1. Install and login with instructions from: https://stripe.com/docs/stripe-cli
-2. Start your local payment-kit server, get it's port
+1. Install and log in following the instructions at: https://stripe.com/docs/stripe-cli
+2. Start your local Payment Kit server and note its port
 3. Run `stripe listen --forward-to http://127.0.0.1:8188/api/integrations/stripe/webhook --log-level=debug --latest`
 
 ### Test Stripe
 
-Invoices for subscriptions are not finalized automatically. You can use stripe postman collection to finalize it and then confirm the payment.
+Invoices for subscriptions are not finalized automatically. You can use the Stripe Postman collection to finalize them and then confirm the payment.
 
 ### Easter Eggs
 
-None public environment variables used in the code, can change the behavior of the payment-kit.
+Non-public environment variables used in the code that can change the behavior of Payment Kit:
 
-- PAYMENT_CHANGE_LOCKED_PRICE: allow change locked price, must be set to "1" to work
-- PAYMENT_RELOAD_SUBSCRIPTION_JOBS: reload subscription jobs on start, must be set to "1" to work
-- PAYMENT_BILLING_THRESHOLD: global default billing threshold, must be a number
-- PAYMENT_MIN_STAKE_AMOUNT: global min stake amount limit, must be a number
-- PAYMENT_DAYS_UNTIL_DUE: global default days until due, must be a number
-- PAYMENT_DAYS_UNTIL_CANCEL: global default days until cancel, must be a number
+- `PAYMENT_CHANGE_LOCKED_PRICE`: Allows changing locked price (must be set to "1" to enable)
+- `PAYMENT_RELOAD_SUBSCRIPTION_JOBS`: Reloads subscription jobs on start (must be set to "1" to enable)
+- `PAYMENT_BILLING_THRESHOLD`: Global default billing threshold (must be a number)
+- `PAYMENT_MIN_STAKE_AMOUNT`: Global minimum stake amount limit (must be a number)
+- `PAYMENT_DAYS_UNTIL_DUE`: Global default days until due (must be a number)
+- `PAYMENT_DAYS_UNTIL_CANCEL`: Global default days until cancellation (must be a number)

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

@@ -6,7 +6,7 @@ import { handlePaymentIntentEvent } from './payment-intent';
 import { handleSetupIntentEvent } from './setup-intent';
 import { handleSubscriptionEvent } from './subscription';
 
-export default function handleStripeEvent(event: any, client: Stripe) {
+export default async function handleStripeEvent(event: any, client: Stripe) {
   switch (event.type) {
     case 'payment_intent.canceled':
     case 'payment_intent.created':
@@ -14,8 +14,16 @@ export default function handleStripeEvent(event: any, client: Stripe) {
     case 'payment_intent.payment_failed':
     case 'payment_intent.processing':
     case 'payment_intent.requires_action':
-    case 'payment_intent.succeeded':
+    case 'payment_intent.succeeded': {
+      if (event.data?.object?.id) {
+        const record = await client.paymentIntents.retrieve(event.data.object.id);
+        event.data.object = {
+          ...event.data.object,
+          ...record,
+        };
+      }
       return handlePaymentIntentEvent(event, client);
+    }
 
     // case 'setup_intent.created':
     case 'setup_intent.canceled':

package/api/src/libs/invoice.ts

@@ -67,7 +67,7 @@ export async function getOneTimeProductInfo(invoiceId: string, paymentCurrency:
       include: [{ model: InvoiceItem, as: 'lines' }],
     });
     if (!doc) {
-      throw new Error(`Invoice not found in ${invoiceId}`);
+      throw new Error(`Invoice not found: ${invoiceId}`);
     }
     const json = doc.toJSON();
     const products = (await Product.findAll()).map((x) => x.toJSON());
@@ -733,19 +733,19 @@ export async function ensureOverdraftProtectionInvoiceAndItems({
   const invoicePrice = price?.currency_options?.find((x: any) => x.currency_id === paymentIntent?.currency_id);
 
   if (!subscription.overdraft_protection?.enabled) {
-    throw new Error('create overdraft protection invoice skipped due to overdraft protection not enabled');
+    throw new Error('Overdraft protection invoice creation skipped: overdraft protection is not enabled');
   }
 
   if (!invoicePrice) {
-    throw new Error('overdraft protection invoice price not found');
+    throw new Error('Overdraft protection invoice price not found');
   }
   const currency = await PaymentCurrency.findByPk(invoicePrice.currency_id);
   if (!currency) {
-    throw new Error('overdraft protection invoice currency not found');
+    throw new Error('Overdraft protection invoice currency not found');
   }
   const paymentMethod = await PaymentMethod.findByPk(currency?.payment_method_id);
   if (!paymentMethod) {
-    throw new Error('overdraft protection invoice payment method not found');
+    throw new Error('Overdraft protection invoice payment method not found');
   }
 
   if (paymentMethod.type !== 'arcblock') {
@@ -754,7 +754,7 @@ export async function ensureOverdraftProtectionInvoiceAndItems({
 
   const { unused } = await isSubscriptionOverdraftProtectionEnabled(subscription, paymentIntent?.currency_id);
   if (new BN(unused).lt(new BN(invoicePrice.unit_amount))) {
-    throw new Error('create overdraft protection invoice skipped due to insufficient overdraft protection');
+    throw new Error('Overdraft protection invoice creation skipped: insufficient overdraft protection funds');
   }
 
   const result = await createInvoiceWithItems({

package/api/src/libs/vendor-util/adapters/launcher-adapter.ts

@@ -1,5 +1,6 @@
 import { VendorAuth } from '@blocklet/payment-vendor';
 
+import { joinURL } from 'ufo';
 import { ProductVendor } from '../../../store/models';
 import logger from '../../logger';
 import { api } from '../../util';
@@ -53,11 +54,14 @@ export class LauncherAdapter implements VendorAdapter {
       };
 
       const { headers, body } = VendorAuth.signRequestWithHeaders(orderData);
-      const response = await fetch(`${launcherApiUrl}/api/vendor/deliveries`, {
-        method: 'POST',
-        headers,
-        body,
-      });
+      const response = await fetch(
+        joinURL(launcherApiUrl, vendorConfig.metadata?.mountPoint || '', '/api/vendor/deliveries'),
+        {
+          method: 'POST',
+          headers,
+          body,
+        }
+      );
 
       if (!response.ok) {
         const errorBody = await response.text();
@@ -125,11 +129,14 @@ export class LauncherAdapter implements VendorAdapter {
     const launcherApiUrl = vendorConfig.app_url;
     const { headers, body } = VendorAuth.signRequestWithHeaders(params);
 
-    const response = await fetch(`${launcherApiUrl}/api/vendor/return`, {
-      method: 'POST',
-      headers,
-      body,
-    });
+    const response = await fetch(
+      joinURL(launcherApiUrl, vendorConfig.metadata?.mountPoint || '', '/api/vendor/return'),
+      {
+        method: 'POST',
+        headers,
+        body,
+      }
+    );
 
     if (!response.ok) {
       const errorBody = await response.text();

package/api/src/libs/vendor-util/fulfillment.ts

@@ -1,13 +1,12 @@
 import { BN } from '@ocap/util';
+import { Customer, PaymentMethod } from '../../store/models';
 import { CheckoutSession } from '../../store/models/checkout-session';
-import { Product } from '../../store/models/product';
-import { ProductVendor } from '../../store/models/product-vendor';
-import { Payout } from '../../store/models/payout';
 import { PaymentIntent } from '../../store/models/payment-intent';
-import { Price } from '../../store/models/price';
-import { calculateVendorCommission, VendorAdapterFactory } from './adapters/factory';
-import { Customer } from '../../store/models';
+import { Payout } from '../../store/models/payout';
+import { ProductVendor } from '../../store/models/product-vendor';
+import env from '../env';
 import logger from '../logger';
+import { calculateVendorCommission, VendorAdapterFactory } from './adapters/factory';
 
 const DEFAULT_COMMISSION_RATE = 20;
 
@@ -80,11 +79,11 @@ export class VendorFulfillmentService {
         amount: orderInfo.amount_total,
         currency: orderInfo.currency_id,
 
-        description: 'This is build a instance for Third Party',
+        description: `This is an app launched by ${env.appName || 'Third Party'}`,
         userInfo: {
           userDid: orderInfo.customer_did!,
           email: userEmail,
-          description: 'This is build a instance for Third Party',
+          description: `This is an app launched by ${env.appName || 'Third Party'}`,
         },
         deliveryParams: {
           blockletMetaUrl: vendor.metadata?.blockletMetaUrl,
@@ -125,117 +124,6 @@ export class VendorFulfillmentService {
     }
   }
 
-  // Calculate commission data (no fulfillment, only calculate commission)
-  private static async calculateCommissionData(checkoutSessionId: string): Promise<VendorFulfillmentResult[]> {
-    try {
-      logger.info('Calculating commission data for checkout session', { checkoutSessionId });
-
-      const checkoutSession = await CheckoutSession.findByPk(checkoutSessionId);
-      if (!checkoutSession) {
-        throw new Error(`CheckoutSession not found: ${checkoutSessionId}`);
-      }
-
-      const priceIds = checkoutSession.line_items.map((item: any) => item.price_id).filter(Boolean);
-
-      if (priceIds.length === 0) {
-        throw new Error(`No price IDs found in checkout session line items: ${checkoutSessionId}`);
-      }
-
-      // Find corresponding product_ids through price_ids
-      const prices = await Price.findAll({
-        where: { id: priceIds },
-        attributes: ['id', 'product_id'],
-      });
-
-      // Create a map of price_id to line_item for amount calculation
-      const priceToLineItemMap = new Map();
-      checkoutSession.line_items.forEach((item: any) => {
-        if (item.price_id) {
-          priceToLineItemMap.set(item.price_id, item);
-        }
-      });
-
-      const productIds = prices.map((price: any) => price.product_id).filter(Boolean);
-
-      if (productIds.length === 0) {
-        throw new Error(`No product IDs found from prices: ${checkoutSessionId}`);
-      }
-
-      // Get all products with vendor configurations
-      const products = await Product.findAll({
-        where: { id: productIds },
-        attributes: ['id', 'vendor_config'],
-      });
-
-      const commissionResults: VendorFulfillmentResult[] = [];
-
-      // Process each product separately
-      for (const product of products) {
-        if (!product.vendor_config || product.vendor_config.length === 0) {
-          logger.debug('No vendor configuration found for product', {
-            productId: product.id,
-            checkoutSessionId,
-          });
-          // eslint-disable-next-line no-continue
-          continue;
-        }
-
-        // Find all prices for this product
-        const productPrices = prices.filter((price: any) => price.product_id === product.id);
-
-        // Calculate total amount for this product across all line items
-        let productTotalAmount = '0';
-        for (const price of productPrices) {
-          const lineItem = priceToLineItemMap.get(price.id);
-          if (lineItem && lineItem.amount_total) {
-            productTotalAmount = new BN(productTotalAmount).add(new BN(lineItem.amount_total || '0')).toString();
-          }
-        }
-
-        // Calculate commission for each vendor of this product
-        for (const vendorConfig of product.vendor_config) {
-          const commissionAmount = calculateVendorCommission(
-            productTotalAmount, // Use product-specific amount instead of total order amount
-            vendorConfig.commission_rate || 0,
-            vendorConfig.commission_type || 'percentage',
-            vendorConfig.amount
-          );
-
-          commissionResults.push({
-            vendorId: vendorConfig.vendor_key,
-            vendorKey: vendorConfig.vendor_key,
-            orderId: `commission_${checkoutSessionId}_${product.id}_${vendorConfig.vendor_id}`,
-            status: 'completed',
-            commissionAmount,
-            commissionType: vendorConfig.commission_type || 'percentage',
-            commissionRate: vendorConfig.commission_rate || 0,
-            productId: product.id, // Add product ID for tracking
-          });
-        }
-      }
-
-      if (commissionResults.length === 0) {
-        logger.warn('No vendor configurations found for any products', {
-          productIds,
-          checkoutSessionId,
-        });
-      }
-
-      logger.info('Commission data calculated', {
-        checkoutSessionId,
-        commissionCount: commissionResults.length,
-      });
-
-      return commissionResults;
-    } catch (error: any) {
-      logger.error('Failed to calculate commission data', {
-        checkoutSessionId,
-        error: error.message,
-      });
-      throw error;
-    }
-  }
-
   static async createVendorPayouts(
     checkoutSessionId: string,
     fulfillmentResults?: VendorFulfillmentResult[]
@@ -257,13 +145,19 @@ export class VendorFulfillmentService {
       // If fulfillmentResults not provided, calculate commission info
       let commissionData = fulfillmentResults;
       if (!commissionData) {
-        commissionData = await this.calculateCommissionData(checkoutSessionId);
+        commissionData = checkoutSession.vendor_info?.map((vendorInfo: any) => ({
+          vendorId: vendorInfo.vendor_id,
+          orderId: vendorInfo.order_id,
+          status: vendorInfo.status,
+          commissionAmount: vendorInfo.commissionAmount,
+        })) as VendorFulfillmentResult[];
       }
 
       const payoutPromises = commissionData
         .filter((result) => result.status !== 'failed' && new BN(result.commissionAmount).gt(new BN('0')))
         .map(async (result) => {
           const vendor = await ProductVendor.findByPk(result.vendorId);
+          const paymentMethod = await PaymentMethod.findByPk(paymentMethodId);
 
           const appPid = vendor?.app_pid;
           const destination = appPid || vendor?.metadata?.wallet_address || vendor?.metadata?.destination || '';
@@ -278,7 +172,7 @@ export class VendorFulfillmentService {
             customer_id: checkoutSession.customer_id || '',
             payment_intent_id: checkoutSession.payment_intent_id || '',
             payment_method_id: paymentMethodId,
-            status: 'pending',
+            status: paymentMethod?.type === 'stripe' ? 'deferred' : 'pending',
             attempt_count: 0,
             attempted: false,
             vendor_info: {

package/api/src/locales/en.ts

@@ -54,45 +54,45 @@ export default flat({
 
     billingDiscrepancy: {
       title: '{productName} billing discrepancy',
-      body: 'Detected billing discrepancy for {productName}, please check.',
+      body: 'A billing discrepancy has been detected for {productName}. Please review your billing details.',
     },
 
     sendTo: 'Sent to',
     mintNFT: {
       title: '{collection} NFT minted',
-      message: 'A new {collection} NFT is minted and sent to your wallet, please check it out.',
+      message: 'A new {collection} NFT has been minted and sent to your wallet. Please check your wallet to view it.',
     },
 
     usageReportEmpty: {
       title: 'No usage report for {productName}',
-      body: 'No usage report for {productName} detected, please check.',
+      body: 'No usage report has been detected for {productName}. Please verify your usage reporting configuration.',
     },
 
     meteringSubscriptionDetection: {
       title: '[{appName}] Metering subscription detection',
-      body: 'During {startTimeStr} - {endTimeStr}, a total of {totalCount} subscriptions with usage-based billing were scanned. \nOut of these, {normalCount} were normal, while {abnormalCount} had anomalies, including {unreportedCount} unreported subscriptions and {discrepantCount} with billing discrepancies. \n\n Abnormal subscriptions:',
+      body: 'During {startTimeStr} - {endTimeStr}, a total of {totalCount} subscriptions with usage-based billing were scanned.\nOf these, {normalCount} were normal, while {abnormalCount} had anomalies, including {unreportedCount} unreported subscriptions and {discrepantCount} with billing discrepancies.\n\nAbnormal subscriptions:',
       healthyBody:
-        'During {startTimeStr} - {endTimeStr}, a total of {totalCount} subscriptions with usage-based billing were scanned, and all subscriptions were normal.',
+        'During {startTimeStr} - {endTimeStr}, a total of {totalCount} subscriptions with usage-based billing were scanned, and all subscriptions were functioning normally.',
       view: 'Manage subscriptions',
     },
 
     subscriptionTrialStart: {
       title: 'Welcome to the start of your {productName} trial',
-      body: 'Congratulations on your {productName} trial! The length of the trial is {trialDuration} and will end at {subscriptionTrialEnd}. Have fun with {productName}!',
+      body: 'Congratulations on starting your {productName} trial! Your trial period is {trialDuration} and will end on {subscriptionTrialEnd}. Enjoy exploring {productName}!',
     },
 
     subscriptionTrialWillEnd: {
       title: 'The {productName} trial will end soon',
       body: 'Your trial for {productName} will end in {willRenewDuration}. Please ensure your account balance is sufficient for automatic billing after the trial ends. Thank you for your support and trust!',
       unableToPayBody:
-        'Your trial for {productName} will end in {willRenewDuration}.Your current balance is {balance}, which is less than {price}, Please ensure your balance is sufficient for automatic billing. Thank you for your support and trust!',
+        'Your trial for {productName} will end in {willRenewDuration}. Your current balance is {balance}, which is less than {price}. Please ensure your balance is sufficient for automatic billing. Thank you for your support and trust!',
       unableToPayReason:
-        'The estimated payment amount is {price}, but the current balance is insufficient ({balance}), please ensure that your account has enough balance to avoid payment failure.',
+        'The estimated payment amount is {price}, but your current balance is insufficient ({balance}). Please ensure your account has enough balance to avoid payment failure.',
     },
 
     subscriptionSucceed: {
       title: "Congratulations! You've successfully subscribed to {productName}",
-      body: 'Thank you for successfully subscribing to {productName} on {at}. We will be happy to provide you with excellent service, and we wish you a pleasant experience.',
+      body: 'Thank you for successfully subscribing to {productName} on {at}. We are happy to provide you with excellent service, and we wish you a pleasant experience.',
     },
 
     oneTimePaymentSucceeded: {
@@ -102,7 +102,7 @@ export default flat({
 
     subscriptionUpgraded: {
       title: 'Congratulations! Your subscription plan for {productName} has been successfully upgraded',
-      body: 'Your subscription plan for {productName} has been successfully upgraded at {at}, thank you for your support, we wish you a pleasant experience!',
+      body: 'Your subscription plan for {productName} has been successfully upgraded on {at}. Thank you for your support, and we wish you a pleasant experience!',
     },
 
     subscriptionWillRenew: {
@@ -111,53 +111,53 @@ export default flat({
       unableToPayBody:
         'Your subscription to {productName} is scheduled for automatic payment on {at}({willRenewDuration} later). If you have any questions or need assistance, please feel free to contact us.',
       unableToPayReason:
-        'The estimated payment amount is {price}, but the current balance is insufficient ({balance}), please ensure that your account has enough balance to avoid payment failure.',
+        'The estimated payment amount is {price}, but your current balance is insufficient ({balance}). Please ensure your account has enough balance to avoid payment failure.',
       renewAmount: 'Payment amount',
       estimatedAmountNote: 'Estimate {amount}, billed based on final usage',
     },
 
     subscriptionRenewed: {
       title: '{productName} payment successful',
-      body: 'Payment for your subscription {productName} is successfully collected on {at}. Thanks for your continued support and trust, we wish you a pleasant journey when using this service!',
-      noExpenseIncurred: 'No expenses incurred during the service ',
+      body: 'Payment for your {productName} subscription was successfully collected on {at}. Thanks for your continued support and trust. We wish you a pleasant experience using this service!',
+      noExpenseIncurred: 'No expenses incurred during the service period',
     },
 
     subscriptionRenewFailed: {
       title: '{productName} automatic payment failed',
-      body: 'We are sorry to inform you that your {productName} failed to go through the automatic payment on {at}. If you have any questions, please contact us in time. Thank you!',
+      body: 'We are sorry to inform you that your {productName} automatic payment failed on {at}. If you have any questions, please contact us promptly. Thank you!',
       reason: {
-        noDidWallet: 'You have not bound DID Wallet, please bind DID Wallet to ensure sufficient balance',
-        noDelegation: 'Your DID Wallet has not been authorized, please update authorization',
+        noDidWallet: 'You have not connected a DID Wallet. Please connect your DID Wallet to ensure sufficient balance',
+        noDelegation: 'Your DID Wallet has not been authorized. Please update authorization',
         noTransferPermission:
-          'Your DID Wallet has not granted transfer permission to the application, please update authorization',
+          'Your DID Wallet has not granted transfer permission to the application. Please update authorization',
         noTokenPermission:
-          'Your DID Wallet has not granted token transfer permission to the application, please update authorization',
+          'Your DID Wallet has not granted token transfer permission to the application. Please update authorization',
         noTransferTo:
-          'Your DID Wallet has not granted the application automatic payment permission, please update authorization',
-        noEnoughAllowance: 'The deduction amount exceeds the single transfer limit, please update authorization',
-        noToken: 'Your account has no tokens, please add funds',
-        noEnoughToken: 'Your account token balance is {balance}, insufficient for {price}, please add funds',
-        noSupported: 'It is not supported to automatically pay with tokens, please check your package',
+          'Your DID Wallet has not granted automatic payment permission to the application. Please update authorization',
+        noEnoughAllowance: 'The deduction amount exceeds the single transfer limit. Please update authorization',
+        noToken: 'Your account has no tokens. Please add funds',
+        noEnoughToken: 'Your account token balance is {balance}, which is insufficient for {price}. Please add funds',
+        noSupported: 'Automatic payment with tokens is not supported. Please check your package',
         txSendFailed: 'Failed to send automatic payment transaction',
       },
     },
 
     autoRechargeFailed: {
       title: 'Auto Top-Up payment failed',
-      body: 'We are sorry to inform you that your {creditCurrencyName} auto top-up failed to go through the automatic payment on {at}. If you have any questions, please contact us in time. Thank you!',
+      body: 'We are sorry to inform you that your {creditCurrencyName} auto top-up automatic payment failed on {at}. If you have any questions, please contact us promptly. Thank you!',
       reason: {
-        noDidWallet: 'You have not bound DID Wallet, please bind DID Wallet to ensure sufficient balance',
-        noDelegation: 'Your DID Wallet has not been authorized, please update authorization',
+        noDidWallet: 'You have not connected a DID Wallet. Please connect your DID Wallet to ensure sufficient balance',
+        noDelegation: 'Your DID Wallet has not been authorized. Please update authorization',
         noTransferPermission:
-          'Your DID Wallet has not granted transfer permission to the application, please update authorization',
+          'Your DID Wallet has not granted transfer permission to the application. Please update authorization',
         noTokenPermission:
-          'Your DID Wallet has not granted token transfer permission to the application, please update authorization',
+          'Your DID Wallet has not granted token transfer permission to the application. Please update authorization',
         noTransferTo:
-          'Your DID Wallet has not granted the application automatic payment permission, please update authorization',
-        noEnoughAllowance: 'The deduction amount exceeds the single transfer limit, please update authorization',
-        noToken: 'Your account has no tokens, please add funds',
-        noEnoughToken: 'Your account token balance is {balance}, insufficient for {price}, please add funds',
-        noSupported: 'It is not supported to automatically pay with tokens, please check your package',
+          'Your DID Wallet has not granted automatic payment permission to the application. Please update authorization',
+        noEnoughAllowance: 'The deduction amount exceeds the single transfer limit. Please update authorization',
+        noToken: 'Your account has no tokens. Please add funds',
+        noEnoughToken: 'Your account token balance is {balance}, which is insufficient for {price}. Please add funds',
+        noSupported: 'Automatic payment with tokens is not supported. Please check your package',
         txSendFailed: 'Failed to send automatic payment transaction',
       },
     },
@@ -187,7 +187,7 @@ export default flat({
 
     customerRewardSucceeded: {
       title: 'Thanks for your reward of {amount}',
-      body: 'Thanks for your reward on {at}, the amount of reward is {amount}. Your support is our driving force, thanks for your generous support!',
+      body: 'Thank you for your reward on {at}. The reward amount is {amount}. Your support is our driving force. Thank you for your generous support!',
       received: '{address} has received {amount}',
       viewDetail: 'View Reference',
     },
@@ -204,14 +204,14 @@ export default flat({
       },
       sender: 'Payer',
       viewDetail: 'View Details',
-      sended: '{address} has sent {amount}',
+      sent: '{address} has sent {amount}',
     },
     subscriptWillCanceled: {
-      title: '{productName} subscription is about to be cancelled ',
+      title: '{productName} subscription is about to be cancelled',
       pastDue:
-        'Your subscription {productName} will be automatically unsubscribed by the system after {at} (after {willCancelDuration}) due to a long period of failure to automatically complete the automatic payment. Please handle the problem of automatic payment manually in time, so as not to affect the use. If you have any questions, please feel free to contact us.',
+        'Your {productName} subscription will be automatically cancelled by the system after {at} ({willCancelDuration} later) due to repeated automatic payment failures. Please resolve the automatic payment issue manually to avoid service interruption. If you have any questions, please feel free to contact us.',
       body: 'Your subscription to {productName} will be automatically canceled on {at} ({willCancelDuration} later). If you have any questions, please feel free to contact us.',
-      renewAmount: 'deduction amount ',
+      renewAmount: 'Deduction amount',
       cancelReason: 'Cancel reason',
       revokeStake: 'Revoke stake',
       adminCanceled: 'Admin canceled',

package/api/src/queues/payment.ts

@@ -373,11 +373,7 @@ export const handlePaymentSucceed = async (
       );
   }
 
-  // Trigger vendor commission queue
-  events.emit('vendor.commission.queued', `vendor-commission-${paymentIntent.id}`, {
-    paymentIntentId: paymentIntent.id,
-    retryOnError: true,
-  });
+  // Trigger vendor commission queue by invoice.paid
 
   let invoice;
   if (paymentIntent.invoice_id) {

package/api/src/queues/vendors/commission.ts

@@ -167,25 +167,27 @@ export const startVendorCommissionQueue = async () => {
   });
 };
 
-events.on('vendor.commission.queued', async (id, job, args = {}) => {
+events.on('invoice.paid', async (invoice) => {
   try {
-    const { ...extraArgs } = args;
-    const exist = await vendorCommissionQueue.get(id);
+    const paymentIntent = await PaymentIntent.findOne({ where: { invoice_id: invoice.id } });
 
-    if (!exist) {
-      logger.info('Vendor commission job added successfully', { id });
-      vendorCommissionQueue.push({
-        id,
-        job,
-        ...extraArgs,
-      });
-    } else {
+    if (!paymentIntent) {
+      logger.warn('PaymentIntent not found', { id: invoice.id });
+      return;
+    }
+
+    const id = `vendor-commission-${paymentIntent.id}`;
+    const exist = await vendorCommissionQueue.get(id);
+    if (exist) {
       logger.info('Vendor commission job already exists, skipping', { id });
+      return;
     }
-  } catch (error: any) {
-    logger.error('Failed to handle vendor commission queue event', {
+
+    vendorCommissionQueue.push({
       id,
-      error,
+      job: { paymentIntentId: paymentIntent.id, retryOnError: true },
     });
+  } catch (error) {
+    logger.error('Failed to trigger vendor commission queue', { invoiceId: invoice.id, error });
   }
 });

package/api/src/queues/vendors/fulfillment-coordinator.ts

@@ -273,14 +273,14 @@ async function updateSingleVendorInfo(
           vendor_id: current[index]?.vendor_id || vendorId,
           order_id: update.order_id || current[index]?.order_id || '',
           status: update.status || current[index]?.status || 'pending',
-          amount: update.amount || current[index]?.amount || '0',
+          amount: update.commissionAmount || current[index]?.amount || '0',
         } as VendorInfo;
       } else {
         current.push({
           vendor_id: vendorId,
           order_id: update.order_id || '',
           status: update.status || 'pending',
-          amount: update.amount || '0',
+          amount: update.commissionAmount || '0',
           ...update,
         } as VendorInfo);
       }

package/api/src/queues/vendors/status-check.ts

@@ -1,6 +1,6 @@
 import { joinURL } from 'ufo';
+import { VendorAuth } from '@blocklet/payment-vendor';
 import createQueue from '../../libs/queue';
-import { getBlockletJson } from '../../libs/util';
 import { CheckoutSession } from '../../store/models/checkout-session';
 import { ProductVendor } from '../../store/models';
 import { fulfillmentCoordinatorQueue } from './fulfillment-coordinator';
@@ -99,12 +99,17 @@ export const handleVendorStatusCheck = async (job: VendorStatusCheckJob) => {
       logger.info('found vendor url', { url, productVendor });
 
       if (url) {
-        const vendorMeta = await getBlockletJson(url);
-        const mountPoint = vendorMeta.componentMountPoints?.find((x: any) => x.appId === vendorId)?.mountPoint;
-        const serverStatusUrl = joinURL(url, mountPoint, '/api/vendor/status', vendor.order_id);
-
-        const result = await fetch(serverStatusUrl);
+        const serverStatusUrl = joinURL(
+          url,
+          productVendor?.metadata?.mountPoint,
+          '/api/vendor/status',
+          vendor.order_id
+        );
+        const { headers } = VendorAuth.signRequestWithHeaders({});
+
+        const result = await fetch(serverStatusUrl, { headers });
         const data = await result.json();
+
         vendor.app_url = data?.appUrl || '';
       }
     }

package/api/src/routes/vendor.ts

@@ -22,6 +22,9 @@ const createVendorSchema = Joi.object({
   app_url: Joi.string().uri().max(512).required(),
   app_pid: Joi.string().max(255).allow('').optional(),
   app_logo: Joi.string().max(512).allow('').optional(),
+  vendor_did: Joi.string()
+    .pattern(/^(did:abt:)?[1-9A-HJ-NP-Za-km-z]{37}$/)
+    .required(),
   status: Joi.string().valid('active', 'inactive').default('active'),
   metadata: MetadataSchema,
 }).unknown(false);
@@ -33,6 +36,9 @@ const updateVendorSchema = Joi.object({
   app_url: Joi.string().uri().max(512).optional(),
   app_pid: Joi.string().max(255).allow('').optional(),
   app_logo: Joi.string().max(512).allow('').optional(),
+  vendor_did: Joi.string()
+    .pattern(/^(did:abt:)?[1-9A-HJ-NP-Za-km-z]{37}$/)
+    .required(),
   status: Joi.string().valid('active', 'inactive').optional(),
   metadata: MetadataSchema,
 }).unknown(true);
@@ -139,6 +145,7 @@ async function createVendor(req: any, res: any) {
       name,
       description,
       app_url: appUrl,
+      vendor_did: vendorDid,
       metadata,
       app_pid: appPid,
       app_logo: appLogo,
@@ -158,6 +165,7 @@ async function createVendor(req: any, res: any) {
       name,
       description,
       app_url: appUrl,
+      vendor_did: vendorDid?.replace('did:abt:', '').trim(),
       status: status || 'active',
       app_pid: appPid,
       app_logo: appLogo,
@@ -195,6 +203,7 @@ async function updateVendor(req: any, res: any) {
       name,
       description,
       app_url: appUrl,
+      vendor_did: vendorDid,
       status,
       metadata,
       app_pid: appPid,
@@ -214,6 +223,7 @@ async function updateVendor(req: any, res: any) {
       name,
       description,
       app_url: appUrl,
+      vendor_did: vendorDid,
       status,
       metadata,
       app_pid: appPid,
@@ -276,7 +286,15 @@ async function getVendorStatusByVendorId(vendorId: string, orderId: string, isDe
   }
 
   const vendor = await ProductVendor.findByPk(vendorId);
-  const url = vendor?.app_url ? joinURL(vendor.app_url, '/api/vendor/', isDetail ? 'orders' : 'status', orderId) : null;
+  const url = vendor?.app_url
+    ? joinURL(
+        vendor.app_url,
+        vendor.metadata?.mountPoint || '',
+        '/api/vendor/',
+        isDetail ? 'orders' : 'status',
+        orderId
+      )
+    : null;
 
   const { headers } = VendorAuth.signRequestWithHeaders({});
   const name = vendor?.name;
@@ -427,6 +445,7 @@ async function redirectToVendor(req: any, res: any) {
 
 const router = Router();
 
+// FIXME: Authentication not yet added, awaiting implementation @Pengfei
 router.get('/order/:sessionId/status', validateParams(sessionIdParamSchema), getVendorFulfillmentStatus);
 router.get('/order/:sessionId/detail', validateParams(sessionIdParamSchema), getVendorFulfillmentDetail);
 

package/api/src/store/migrations/20250916-add-vendor-did.ts

@@ -0,0 +1,20 @@
+import { safeApplyColumnChanges, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  // Add vendor_did column to product_vendors table
+  await safeApplyColumnChanges(context, {
+    product_vendors: [
+      {
+        name: 'vendor_did',
+        field: {
+          type: 'STRING',
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('product_vendors', 'vendor_did');
+};

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

@@ -38,7 +38,7 @@ export class Payout extends Model<InferAttributes<Payout>, InferCreationAttribut
     commission_amount: string;
   };
 
-  declare status: LiteralUnion<'pending' | 'paid' | 'failed' | 'canceled' | 'in_transit', string>;
+  declare status: LiteralUnion<'pending' | 'paid' | 'failed' | 'canceled' | 'in_transit' | 'deferred', string>;
 
   // retry logic
   declare failure_message?: string;
@@ -118,7 +118,7 @@ export class Payout extends Model<InferAttributes<Payout>, InferCreationAttribut
       allowNull: true,
     },
     status: {
-      type: DataTypes.ENUM('paid', 'pending', 'failed', 'canceled', 'in_transit'),
+      type: DataTypes.ENUM('paid', 'pending', 'failed', 'canceled', 'in_transit', 'deferred'),
       allowNull: false,
     },
     failure_message: {

package/api/src/store/models/product-vendor.ts

@@ -15,6 +15,7 @@ export class ProductVendor extends Model<InferAttributes<ProductVendor>, InferCr
   declare app_url: string;
   declare app_pid?: string;
   declare app_logo?: string;
+  declare vendor_did?: string;
 
   declare status: 'active' | 'inactive';
   declare metadata: Record<string, any>;
@@ -60,6 +61,10 @@ export class ProductVendor extends Model<InferAttributes<ProductVendor>, InferCr
       type: DataTypes.STRING(512),
       allowNull: true,
     },
+    vendor_did: {
+      type: DataTypes.STRING(255),
+      allowNull: true,
+    },
     status: {
       type: DataTypes.ENUM('active', 'inactive'),
       allowNull: false,

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

@@ -60,6 +60,7 @@ export class Product extends Model<InferAttributes<Product>, InferCreationAttrib
     commission_rate?: number;
     commission_type?: 'percentage' | 'fixed_amount';
     amount?: string;
+    commissionAmount?: string;
     custom_params?: Record<string, any>;
   }>;
 

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

package/doc/vendor_fulfillment_system.md

@@ -1,63 +1,63 @@
-# 多供应商发货系统完整实现方案
+# Multi-Vendor Fulfillment System Complete Implementation
 
-## 📋 项目概述
+## 📋 Project Overview
 
-本文档总结了 Payment Kit 中多供应商发货系统的完整实现，包括架构设计、流程逻辑、技术实现和问题解决方案。
+This document summarizes the complete implementation of the multi-vendor fulfillment system in Payment Kit, including architecture design, process logic, technical implementation, and problem-solving solutions.
 
-## 🎯 系统目标
+## 🎯 System Goals
 
-### 核心需求
+### Core Requirements
 
-1. **多供应商支持**: 一个订单可以包含多个供应商的商品
-2. **异步发货**: 不同供应商可以独立、并行发货
-3. **状态协调**: 统一管理所有供应商的发货状态
-4. **容错机制**: 处理发货失败、重试、超时等异常情况
-5. **分成处理**: 所有供应商发货完成后，自动进行佣金分成
-6. **退款保障**: 任何供应商失败即全额退款，确保用户权益
+1. **Multi-vendor Support**: A single order can contain products from multiple vendors
+2. **Asynchronous Fulfillment**: Different vendors can fulfill orders independently and in parallel
+3. **State Coordination**: Unified management of fulfillment status across all vendors
+4. **Fault Tolerance**: Handle fulfillment failures, retries, timeouts, and other exceptional situations
+5. **Commission Processing**: Automatic commission distribution after all vendors complete fulfillment
+6. **Refund Protection**: Full refund if any vendor fails, ensuring user rights
 
-### 业务规则
+### Business Rules
 
-- **全部成功**: 所有供应商发货成功 → 进行佣金分成
-- **任何失败**: 有任何供应商失败、超时或超过重试次数 → **对已成功的供应商发起退货请求** → 全额退款给用户
-- **超时时间**: 5分钟无响应视为超时
-- **重试次数**: 最多3次重试
-- **退货机制**: 对已完成发货的供应商发起退货请求
+- **All Success**: All vendors fulfill successfully → Process commission distribution
+- **Any Failure**: If any vendor fails, times out, or exceeds retry limit → **Initiate return requests for successful vendors** → Full refund to user
+- **Timeout Period**: 5 minutes of no response is considered timeout
+- **Retry Limit**: Maximum 3 retries
+- **Return Mechanism**: Initiate return requests for vendors that have completed fulfillment
 
-## 🏗️ 系统架构
+## 🏗️ System Architecture
 
-### 架构模式: 协调器模式 (Coordinator Pattern)
+### Architecture Pattern: Coordinator Pattern
 
-#### 🔄 **核心流程 (文字版)**
+#### 🔄 **Core Process Flow (Text Version)**
 
 ```
 1. Payment Success
    ↓
 2. vendor-commission.ts
-   ├─ 检查供应商配置
-   ├─ 无供应商 → 直接冷钱包转账 ✅
-   └─ 有供应商 → 调用协调器
+   ├─ Check vendor configuration
+   ├─ No vendors → Direct cold wallet transfer ✅
+   └─ Has vendors → Call coordinator
 
 3. vendor-fulfillment-coordinator.ts
-   ├─ 启动发货流程
-   ├─ 初始化 vendor_info 状态
-   ├─ 为每个供应商创建发货任务
-   └─ 被动等待通知
+   ├─ Start fulfillment process
+   ├─ Initialize vendor_info status
+   ├─ Create fulfillment tasks for each vendor
+   └─ Wait passively for notifications
 
-4. vendor-fulfillment.ts (并行执行)
-   ├─ 供应商A发货 → 通知协调器 ✅
-   ├─ 供应商B发货 → 通知协调器 ✅
-   ├─ 供应商C发货 → 通知协调器 ❌
-   └─ 重试机制 (最多3次)
+4. vendor-fulfillment.ts (parallel execution)
+   ├─ Vendor A fulfills → Notify coordinator ✅
+   ├─ Vendor B fulfills → Notify coordinator ✅
+   ├─ Vendor C fulfills → Notify coordinator ❌
+   └─ Retry mechanism (max 3 times)
 
 5. vendor-fulfillment-coordinator.ts
-   ├─ 接收所有通知
-   ├─ 更新 vendor_info 状态 (事务+锁)
-   ├─ 检查整体状态
-   ├─ 全部成功 → 分成 + 冷钱包 ✅
-   └─ 任何失败 → 🔄 对已成功供应商发起退货请求 → 全额退款 ❌
+   ├─ Receive all notifications
+   ├─ Update vendor_info status (transaction + lock)
+   ├─ Check overall status
+   ├─ All success → Commission distribution + cold wallet ✅
+   └─ Any failure → 🔄 Initiate return requests for successful vendors → Full refund ❌
 ```
 
-#### 📊 **详细架构图**
+#### 📊 **Detailed Architecture Diagram**
 
 ```mermaid
 graph TD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.20.9",
+  "version": "1.20.11",
   "scripts": {
     "dev": "blocklet dev --open",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
@@ -56,8 +56,8 @@
     "@blocklet/error": "^0.2.5",
     "@blocklet/js-sdk": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@blocklet/logger": "^1.16.52-beta-20250912-112002-e3499e9c",
-    "@blocklet/payment-react": "1.20.9",
-    "@blocklet/payment-vendor": "1.20.9",
+    "@blocklet/payment-react": "1.20.11",
+    "@blocklet/payment-vendor": "1.20.11",
     "@blocklet/sdk": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@blocklet/ui-react": "^3.1.40",
     "@blocklet/uploader": "^0.2.10",
@@ -126,7 +126,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.20.9",
+    "@blocklet/payment-types": "1.20.11",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -173,5 +173,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "e89c0a9b6a3f3b7f7cb3cc0845b1775c1f587f6e"
+  "gitHead": "b69becabf1721f6238cf24004537bee1e4ade860"
 }

package/src/locales/en.tsx

@@ -11,11 +11,11 @@ export default flat({
       add: 'Add more metadata',
       edit: 'Edit metadata',
       empty: 'No metadata',
-      emptyTip: "You haven't added any metadata yet, you can add it",
+      emptyTip: "You haven't added any metadata yet. You can add it now",
       formMode: 'Switch to form mode',
       jsonMode: 'Switch to JSON mode',
       jsonPlaceholder: 'Enter JSON data...',
-      invalidJson: 'Invalid JSON format, please check your input',
+      invalidJson: 'Invalid JSON format. Please check your input',
       formatJson: 'Format JSON',
     },
     price: 'Price',
@@ -26,7 +26,7 @@ export default flat({
     minLength: 'Min {len} characters',
     invalidCharacters: 'Invalid characters',
     latinOnly:
-      'At least one letter and cannot include Chinese characters and special characters such as <, >、"、’ or \\',
+      'Must contain at least one letter and cannot include Chinese characters or special characters such as <, >, ", \' or \\',
     loading: 'Loading...',
     rechargeTime: 'Recharge Time',
     submit: 'Submit',
@@ -41,8 +41,8 @@ export default flat({
     quickStarts: 'Quick Starts',
     copy: 'Copy',
     copied: 'Copied',
-    copySuccess: 'Copy Success',
-    copyFailed: 'Copy Failed',
+    copySuccess: 'Copied successfully',
+    copyFailed: 'Copy failed',
     copyTip: 'Please copy manually',
     save: 'Save',
     cancel: 'Cancel',
@@ -254,7 +254,7 @@ export default flat({
         'Credit products are used to provide consumable credits to users, supporting both one-time purchase and package pricing models.',
       creditAmount: {
         label: 'Credit Amount',
-        placeholder: 'Amount of credits users get when purchasing this price',
+        placeholder: 'Amount of credits users receive when purchasing this price',
         help: 'Leave empty for pay-per-unit pricing, enter a number for fixed package deals',
         description: 'Purchase quantity determines the amount of Credits received',
       },
@@ -367,14 +367,14 @@ export default flat({
       archiveTip: 'Archiving will hide this product from new purchases. Are you sure you want to archive this product?',
       unarchive: 'Unarchive product',
       unarchiveTip:
-        'Unarchiving will enable this product from new purchases. Are you sure you want to unarchive this product?',
+        'Unarchiving will enable this product for new purchases. Are you sure you want to unarchive this product?',
       remove: 'Remove product',
       removeTip: 'Removing will hide this product from new purchases. Are you sure you want to remove this product?',
       archived: 'This product has been archived',
       archivedTip:
         "This product can't be added to new invoices, subscriptions, payment links, or pricing tables. Any existing subscriptions with this product remain active until canceled and any existing payment links or pricing tables are deactivated.",
       locked: 'This product is locked because at least one of its prices is used by a subscription or a payment.',
-      currencyNotAligned: 'all prices must have the same currency settings',
+      currencyNotAligned: 'All prices must have the same currency settings',
       image: {
         label: 'Image',
         add: 'Add image',
@@ -431,7 +431,7 @@ export default flat({
       vendorConfig: {
         title: 'Vendor Configuration',
         add: 'Add Vendor',
-        empty: 'No vendors configured. Click "Add Vendor" to configure vendor services.',
+        empty: 'No vendors configured. Click "Add Vendor" to configure vendor services',
         vendor: 'Vendor',
         vendorRequired: 'Vendor is required',
         productCode: 'Product Code',
@@ -508,7 +508,7 @@ export default flat({
         packageDesc: 'Price by number of units',
         graduated: 'Graduated Pricing',
         volume: 'Volume pricing',
-        custom: 'Customer choose price',
+        custom: 'Customer chooses price',
         usageBased: 'Usage-based',
         creditMetered: 'Credit metered',
       },
@@ -520,7 +520,7 @@ export default flat({
         selectMeter: 'Select meter',
         pricingNote: 'For metered products, pricing is automatically based on usage tracked by the selected meter.',
         description:
-          'Credit metered billing requires a corresponding Credit consumption. If the Credit is consumed, the corresponding service will stop.',
+          'Credit metered billing requires corresponding credit consumption. If credits are consumed, the corresponding service will stop.',
       },
       credit: {
         saveAsBasePrice: 'Set as Top-up Package',
@@ -557,7 +557,7 @@ export default flat({
         tip: '',
       },
       quantity: {
-        tip: 'Quantity must be equal or greater than 0',
+        tip: 'Quantity must be equal to or greater than 0',
       },
       quantityAvailable: {
         label: 'Available quantity',
@@ -597,10 +597,10 @@ export default flat({
       afterPay: 'After payment',
       products: 'Products',
       addProduct: 'Add another product',
-      requireBillingAddress: 'Collect customers billing addresses',
-      requirePhoneNumber: 'Collect customers phone numbers',
+      requireBillingAddress: 'Collect customer billing addresses',
+      requirePhoneNumber: 'Collect customer phone numbers',
       allowPromotionCodes: 'Allow promotion codes',
-      requireCrossSell: 'Require cross sell products selected if eligible',
+      requireCrossSell: 'Require cross-sell products to be selected if eligible',
       includeFreeTrial: 'Include a free trial',
       noStakeRequired: 'No stake required',
       showProductFeatures: 'Show product features',
@@ -684,7 +684,7 @@ export default flat({
         expiredUncapturedCharge: 'Expired uncaptured charge',
         amountRange: 'Refund amount must be between {min} and {max} {symbol}',
         amountHelper: 'Refund amount must be less than or equal to {max} {symbol}',
-        required: 'please fill in the refund information',
+        required: 'Please fill in the refund information',
         empty: 'The current order has been fully refunded',
       },
     },
@@ -718,11 +718,11 @@ export default flat({
       },
       name: {
         label: 'Name',
-        tip: 'Consumer facing',
+        tip: 'Customer-facing',
       },
       description: {
         label: 'Description',
-        tip: 'Not consumer facing',
+        tip: 'Not customer-facing',
       },
       stripe: {
         dashboard: {
@@ -749,11 +749,11 @@ export default flat({
         },
         api_host: {
           label: 'API Host',
-          tip: 'The graphql endpoint to send transaction to',
+          tip: 'The GraphQL endpoint to send transactions to',
         },
         explorer_host: {
           label: 'Explorer Host',
-          tip: 'The webapp endpoint to view transaction details',
+          tip: 'The web app endpoint to view transaction details',
         },
       },
       ethereum: {
@@ -763,11 +763,11 @@ export default flat({
         },
         api_host: {
           label: 'RPC Endpoint',
-          tip: 'The RPC endpoint to send transaction to',
+          tip: 'The RPC endpoint to send transactions to',
         },
         explorer_host: {
           label: 'Explorer Host',
-          tip: 'The webapp endpoint to view transaction details',
+          tip: 'The web app endpoint to view transaction details',
         },
         native_symbol: {
           label: 'Native Symbol',
@@ -775,7 +775,7 @@ export default flat({
         },
         confirmation: {
           label: 'Confirmation Count',
-          tip: 'How many blocks since transaction execution',
+          tip: 'Number of blocks required since transaction execution',
         },
       },
       evm: {
@@ -792,11 +792,11 @@ export default flat({
         },
         api_host: {
           label: 'RPC Endpoint',
-          tip: 'The RPC endpoint to send transaction to',
+          tip: 'The RPC endpoint to send transactions to',
         },
         explorer_host: {
           label: 'Explorer Host',
-          tip: 'The webapp endpoint to view transaction details',
+          tip: 'The web app endpoint to view transaction details',
         },
         native_symbol: {
           label: 'Native Symbol',
@@ -804,7 +804,7 @@ export default flat({
         },
         confirmation: {
           label: 'Confirmation Count',
-          tip: 'How many blocks since transaction execution',
+          tip: 'Number of blocks required since transaction execution',
         },
       },
     },
@@ -905,6 +905,9 @@ export default flat({
       appUrlRequired: 'App URL is required',
       appUrlInvalid: 'Please enter a valid URL starting with http:// or https://',
       appUrlHelp: 'The base URL of the vendor application',
+      vendorDid: 'Vendor DID',
+      vendorDidInvalid: 'Please enter a valid DID',
+      vendorDidHelp: 'Optional DID address for the vendor',
       webhookPath: 'Webhook Path',
       webhookPathInvalid: 'Please enter a valid path starting with /',
       webhookPathHelp: 'Optional webhook callback path (e.g., /webhooks/status)',

package/src/locales/zh.tsx

@@ -881,8 +881,11 @@ export default flat({
       displayNameHelp: '此数据会展示到付款成功后的安装界面',
       appUrl: '应用地址',
       appUrlRequired: '应用地址是必填项',
-      appUrlInvalid: '请输入以http://或https://开头的有效URL',
-      appUrlHelp: '供应商应用的基础URL',
+      appUrlInvalid: '请输入有效的 URL，以 http:// 或 https:// 开头',
+      appUrlHelp: '供应商应用的基础 URL 地址',
+      vendorDid: '供应商 DID',
+      vendorDidInvalid: '请输入有效的 DID',
+      vendorDidHelp: '供应商的可选 DID 地址',
       webhookPath: 'Webhook路径',
       webhookPathInvalid: '请输入以/开头的有效路径',
       webhookPathHelp: '可选的webhook回调路径（如：/webhooks/status）',

package/src/pages/admin/products/vendors/create.tsx

@@ -30,6 +30,7 @@ interface Vendor {
   name: string;
   description: string;
   app_url: string;
+  vendor_did?: string;
   status: 'active' | 'inactive';
   metadata: Record<string, any>;
   created_at: string;
@@ -49,6 +50,7 @@ interface VendorFormData {
   name: string;
   description: string;
   app_url: string;
+  vendor_did?: string;
   status: 'active' | 'inactive';
   metadata: Array<{ key: string; value: string }>;
   app_pid?: string;
@@ -82,6 +84,7 @@ export default function VendorCreate({
         name: '',
         description: '',
         app_url: '',
+        vendor_did: '',
         status: 'inactive' as const,
         metadata: [{ key: 'blockletMetaUrl', value: '' }],
         app_pid: '',
@@ -114,6 +117,16 @@ export default function VendorCreate({
     }
   };
 
+  const validateDid = (did: string | undefined) => {
+    if (!did) return true; // DID 是可选的
+    // DID 格式验证
+    const didPattern = /^(did:abt:)?[1-9A-HJ-NP-Za-km-z]{37}$/;
+    if (!didPattern.test(did.trim())) {
+      return t('admin.vendor.vendorDidInvalid');
+    }
+    return true;
+  };
+
   const onSubmit = async (data: VendorFormData) => {
     try {
       setLoading(true);
@@ -144,6 +157,7 @@ export default function VendorCreate({
 
       const submitData = {
         ...restData,
+        vendor_did: restData.vendor_did?.replace('did:abt:', '').trim(),
         metadata: metadataObj,
       };
 
@@ -167,6 +181,10 @@ export default function VendorCreate({
           // 从响应中获取appPid和appLogo
           const blockletInfo = await response.json();
           if (blockletInfo) {
+            const component = blockletInfo.componentMountPoints?.find((x: any) => x.did === submitData.vendor_did);
+            if (component && !['', '/'].includes(component.mountPoint) && submitData.metadata) {
+              submitData.metadata.mountPoint = component.mountPoint;
+            }
             submitData.app_pid = blockletInfo.pid || blockletInfo.appPid;
             submitData.app_logo = blockletInfo.logo || blockletInfo.appLogo;
           }
@@ -307,6 +325,24 @@ export default function VendorCreate({
             )}
           />
 
+          <Controller
+            name="vendor_did"
+            control={control}
+            rules={{
+              required: t('admin.vendor.vendorDidRequired'),
+              validate: validateDid,
+            }}
+            render={({ field }) => (
+              <TextField
+                {...field}
+                label={t('admin.vendor.vendorDid')}
+                fullWidth
+                error={!!errors.vendor_did}
+                helperText={errors.vendor_did?.message || t('admin.vendor.vendorDidHelp')}
+              />
+            )}
+          />
+
           <MetadataForm title={t('common.metadata.label')} />
 
           <Controller