payment-kit 1.22.20 → 1.22.22

package/api/src/libs/vendor-util/adapters/types.ts

@@ -84,6 +84,7 @@ export interface RefundRequestParams {
   contract: string;
   chainType: string;
   chainApiHost: string;
+  reason?: string;
 }
 
 export interface RefundRequestResult {

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

@@ -1,6 +1,7 @@
 import { PaymentCurrency, PaymentMethod, Payout } from '../../store/models';
 
 export interface RefundInfo {
+  reason?: string;
   livemode: number;
   amount: string;
   contract: string;
@@ -12,7 +13,7 @@ export interface RefundInfo {
  * Build refund info from payout record
  * Extracts contract, chain type, and chain API host from payout's associated payment method and currency
  */
-export async function buildRefundInfoFromPayout(payout: Payout): Promise<RefundInfo> {
+export async function buildRefundInfoFromPayout(payout: Payout, reason?: string): Promise<RefundInfo> {
   const paymentMethod = await PaymentMethod.findByPk(payout.payment_method_id);
   if (!paymentMethod) {
     throw new Error(`PaymentMethod not found: ${payout.payment_method_id} | Payout ID: ${payout.id}`);
@@ -42,5 +43,6 @@ export async function buildRefundInfoFromPayout(payout: Payout): Promise<RefundI
     contract: paymentCurrency.contract,
     chainType,
     chainApiHost,
+    reason,
   };
 }

package/api/src/queues/vendors/return-processor.ts

@@ -208,7 +208,7 @@ async function callVendorReturn(vendor: VendorInfo, checkoutSession: CheckoutSes
       },
     });
 
-    if (payoutInfo && result.data?.payoutResult?.status === 'paid') {
+    if (payoutInfo && result.data?.refundResult?.status === 'succeeded') {
       logger.info('[callVendorReturn] Vendor payout refund successful', {
         checkoutSessionId: checkoutSession.id,
         vendorId: vendor.vendor_id,
@@ -221,7 +221,7 @@ async function callVendorReturn(vendor: VendorInfo, checkoutSession: CheckoutSes
         vendorId: vendor.vendor_id,
         orderId: vendor.order_id,
         refundInfo,
-        payoutResult: result.data?.payoutResult,
+        refundResult: result.data?.refundResult,
       });
     }
 

package/api/src/routes/payouts.ts

@@ -1,21 +1,12 @@
 import { isValid } from '@arcblock/did';
-import OcapClient from '@ocap/client';
-import { BN } from '@ocap/util';
-import { ethers } from 'ethers';
 import { Router } from 'express';
 import Joi from 'joi';
 import pick from 'lodash/pick';
 
 import { sessionMiddleware } from '@blocklet/sdk/lib/middlewares/session';
-import { getWallet } from '@blocklet/sdk/lib/wallet';
 import type { WhereOptions } from 'sequelize';
-import { Op } from 'sequelize';
-import { sendErc20ToUser } from '../integrations/ethereum/token';
 import { createListParamSchema, getOrder, getWhereFromKvQuery, MetadataSchema } from '../libs/api';
-import { wallet } from '../libs/auth';
-import { EVM_CHAIN_TYPES } from '../libs/constants';
 import logger from '../libs/logger';
-import { getGasPayerExtra } from '../libs/payment';
 import { authenticate } from '../libs/security';
 import { formatMetadata } from '../libs/util';
 import { PaymentLink, TPaymentIntentExpanded } from '../store/models';
@@ -185,378 +176,6 @@ router.get('/mine', sessionMiddleware({ accessKey: true }), async (req, res) =>
   }
 });
 
-const syncPayoutRequestSchema = Joi.object({
-  // Payout creation required fields
-  livemode: Joi.number().required().description('Testnet (0) or mainnet (1)'),
-  amount: Joi.string().required().description('Transfer amount in unit format'),
-  destination: Joi.string().required().description('Output account address (to address)'),
-
-  // Transfer execution required fields
-  contract: Joi.string().required().description('Token contract address for transfer'),
-  chainType: Joi.string().required().description('Chain type, e.g. "arcblock", "ethereum", "base", "bitcoin"'),
-  chainApiHost: Joi.string().required().description('RPC API endpoint for the chain'),
-
-  // Optional fields
-  description: Joi.string().max(512).optional().description('Payout description (optional)'),
-  orderId: Joi.string().optional().description('Order ID for duplicate check (optional)'),
-});
-
-// Helper function: Query payment method and currency by contract and chain type
-async function queryPaymentMethodAndCurrency(
-  chainType: string,
-  livemode: boolean,
-  contract: string
-): Promise<{
-  paymentCurrency: PaymentCurrency | null;
-  paymentMethodId: string;
-  currencyId: string;
-}> {
-  let paymentMethod: PaymentMethod | null = null;
-  let paymentCurrency: PaymentCurrency | null = null;
-  let paymentMethodId = '';
-  let currencyId = '';
-
-  paymentMethod = await PaymentMethod.findOne({
-    where: { type: chainType, livemode },
-  });
-
-  if (paymentMethod) {
-    paymentMethodId = paymentMethod.id;
-    paymentCurrency = await PaymentCurrency.findOne({
-      where: { contract, payment_method_id: paymentMethod.id },
-    });
-    if (paymentCurrency) {
-      currencyId = paymentCurrency.id;
-      logger.info('PaymentMethod and Currency ID queried by contract and chain_type', {
-        paymentMethodId,
-        currencyId,
-        contract,
-        chainType,
-      });
-    } else {
-      logger.warn('PaymentCurrency not found by contract and chain_type', {
-        contract,
-        chainType,
-        paymentMethodId: paymentMethod.id,
-      });
-    }
-  } else {
-    logger.warn('PaymentMethod not found by chain_type', { chainType, livemode });
-  }
-
-  return { paymentCurrency, paymentMethodId, currencyId };
-}
-
-// Helper function: Resolve or create payment intent
-async function resolveOrCreatePaymentIntent(
-  finalPaymentMethodId: string,
-  finalCurrencyId: string,
-  customerId: string,
-  livemode: boolean,
-  amount: string,
-  chainType: string,
-  destination: string,
-  description: string | undefined,
-  metadata: Record<string, any> | undefined
-): Promise<string> {
-  if (!finalPaymentMethodId || !finalCurrencyId) {
-    logger.warn('Cannot create payment intent: missing payment_method_id or currency_id', {
-      hasPaymentMethod: !!finalPaymentMethodId,
-      hasCurrency: !!finalCurrencyId,
-    });
-    return '';
-  }
-
-  const newPaymentIntent = await PaymentIntent.create({
-    livemode,
-    amount,
-    amount_received: amount,
-    amount_capturable: '0',
-    currency_id: finalCurrencyId,
-    payment_method_id: finalPaymentMethodId,
-    customer_id: customerId,
-    description: description || `Payout to ${destination}`,
-    status: 'succeeded',
-    capture_method: 'automatic',
-    confirmation_method: 'automatic',
-    payment_method_types: [chainType],
-    statement_descriptor: description || `Payout to ${destination}`,
-    statement_descriptor_suffix: '',
-    metadata: formatMetadata(metadata || {}),
-  });
-
-  logger.info('Created new payment intent for payout', {
-    paymentIntentId: newPaymentIntent.id,
-    payoutAmount: amount,
-  });
-
-  return newPaymentIntent.id;
-}
-
-// Returns transaction hash and payment details
-async function processDirectTransfer({
-  payout,
-  contract,
-  chainType,
-  chainApiHost,
-  description,
-}: {
-  payout: Payout;
-  contract: string;
-  chainType: string;
-  chainApiHost: string;
-  description: string;
-}): Promise<{ txHash: string; paymentDetails: any }> {
-  if (chainType === 'arcblock') {
-    const client = new OcapClient(chainApiHost);
-    const signed = await client.signTransferV2Tx({
-      tx: {
-        itx: {
-          to: payout.destination,
-          value: '0',
-          assets: [],
-          tokens: [{ address: contract, value: payout.amount }],
-          data: {
-            typeUrl: 'json',
-            // @ts-ignore
-            value: {
-              appId: wallet.address,
-              reason: description || `Payout to ${payout.destination}`,
-              payoutId: payout.id,
-            },
-          },
-        },
-      },
-      wallet,
-    });
-
-    // @ts-ignore
-    const { buffer } = await client.encodeTransferV2Tx({ tx: signed });
-    // @ts-ignore
-    const txHash = await client.sendTransferV2Tx({ tx: signed, wallet }, await getGasPayerExtra(buffer));
-
-    return {
-      txHash,
-      paymentDetails: {
-        arcblock: {
-          tx_hash: txHash,
-          payer: wallet.address,
-          type: 'transfer',
-        },
-      },
-    };
-  }
-  if (EVM_CHAIN_TYPES.includes(chainType)) {
-    const provider = new ethers.JsonRpcProvider(chainApiHost);
-    const receipt = await sendErc20ToUser(provider, contract, payout.destination, payout.amount);
-    const tx = await provider.getTransaction(receipt.hash);
-    const payerAddress = tx?.from || '';
-
-    const paymentDetails: any = {
-      [chainType]: {
-        tx_hash: receipt.hash,
-        payer: payerAddress,
-        type: 'transfer',
-      },
-    };
-
-    if (receipt) {
-      paymentDetails[chainType].block_height = receipt.blockNumber.toString();
-      paymentDetails[chainType].gas_used = receipt.gasUsed.toString();
-      paymentDetails[chainType].gas_price = receipt.gasPrice?.toString() || '0';
-    }
-
-    return {
-      txHash: receipt.hash,
-      paymentDetails,
-    };
-  }
-  throw new Error(`Unsupported chain type: ${chainType}`);
-}
-
-router.post('/sync', async (req, res) => {
-  const { error } = syncPayoutRequestSchema.validate(req.body);
-  if (error) {
-    return res.status(400).json({ error: `Payout request invalid: ${error.message}` });
-  }
-
-  // Extract and validate request data
-  const { livemode, amount, destination, contract, chainType, chainApiHost } = req.body;
-  const { description, metadata, orderId } = req.body;
-
-  try {
-    // Convert and validate input types
-    const livemodeBoolean = !!livemode;
-    const amountString = String(amount);
-    const amountBN = new BN(amountString);
-    if (amountBN.lte(new BN('0'))) {
-      throw new Error('Payout amount must be greater than 0');
-    }
-
-    // Query payment method and currency first (needed for duplicate check)
-    const { paymentMethodId: finalPaymentMethodId, currencyId: finalCurrencyId } = await queryPaymentMethodAndCurrency(
-      chainType,
-      livemodeBoolean,
-      contract
-    );
-
-    // Check for existing payout with same orderId in metadata if provided
-    if (orderId && orderId.trim()) {
-      const existingPayout = await Payout.findOne({
-        where: {
-          metadata: { orderId: orderId.trim() },
-          status: { [Op.in]: ['paid', 'in_transit'] },
-        },
-      });
-
-      if (existingPayout) {
-        logger.info('Order payout already completed or in-progress. Current request interrupted/terminated', {
-          orderId,
-          payoutId: existingPayout.id,
-          status: existingPayout.status,
-        });
-
-        return res.json(existingPayout);
-      }
-    }
-
-    // Get system DID as default payer (发款方)
-    const systemDid = getWallet().address;
-
-    // Resolve or create payment intent
-    const finalPaymentIntentId = await resolveOrCreatePaymentIntent(
-      finalPaymentMethodId,
-      finalCurrencyId,
-      systemDid,
-      livemodeBoolean,
-      amountString,
-      chainType,
-      destination,
-      description,
-      metadata
-    );
-
-    // Build metadata with orderId only
-    const payoutMetadata = {
-      ...formatMetadata(metadata || {}),
-      ...(orderId && orderId.trim() ? { orderId: orderId.trim() } : {}),
-    };
-
-    // Create payout record
-    const payout = await Payout.create({
-      livemode: livemodeBoolean,
-      automatic: false,
-      description: description || `Transfer to ${destination}`,
-      amount: amountString,
-      destination,
-      payment_intent_id: finalPaymentIntentId || '',
-      customer_id: systemDid,
-      currency_id: finalCurrencyId || '',
-      payment_method_id: finalPaymentMethodId || '',
-      status: 'in_transit',
-      attempt_count: 0,
-      attempted: false,
-      next_attempt: 0,
-      last_attempt_error: null,
-      metadata: payoutMetadata,
-    });
-
-    logger.info('Synchronous payout created, processing transfer directly', {
-      payoutId: payout.id,
-      destination,
-      amount,
-      chainType,
-      requestedBy: req.user?.did,
-    });
-
-    // Process transfer
-    try {
-      const { txHash, paymentDetails } = await processDirectTransfer({
-        payout,
-        contract,
-        chainType,
-        chainApiHost,
-        description,
-      });
-
-      await payout.update({
-        status: 'paid',
-        last_attempt_error: null,
-        attempt_count: payout.attempt_count + 1,
-        attempted: true,
-        payment_details: paymentDetails,
-      });
-
-      logger.info('Synchronous payout transfer completed', {
-        payoutId: payout.id,
-        txHash,
-        requestedBy: req.user?.did,
-      });
-
-      // Reload and enrich payout data
-      const updatedPayout = await Payout.findByPk(payout.id, {
-        include: [
-          { model: PaymentCurrency, as: 'paymentCurrency', required: false },
-          { model: PaymentIntent, as: 'paymentIntent', required: false },
-          { model: PaymentMethod, as: 'paymentMethod', required: false },
-        ],
-      });
-
-      if (!updatedPayout) {
-        throw new Error('Payout not found after processing');
-      }
-
-      return res.json(updatedPayout.toJSON());
-    } catch (processError: any) {
-      logger.error('Synchronous payout transfer failed', {
-        error: processError,
-        requestedBy: req.user?.did,
-      });
-      // Handle transfer failure
-      await payout.update({
-        status: 'failed',
-        last_attempt_error: {
-          type: 'api_error',
-          code: processError.code || 'api_error',
-          message: processError.message || 'Transfer failed',
-        },
-        attempt_count: payout.attempt_count + 1,
-        attempted: true,
-        failure_message: processError.message || 'Transfer failed',
-      });
-
-      logger.error('Synchronous payout transfer failed', {
-        payoutId: payout.id,
-        error: processError.message || processError.error?.message,
-        requestedBy: req.user?.did,
-      });
-
-      // Reload and enrich failed payout data
-      const failedPayout = await Payout.findByPk(payout.id, {
-        include: [
-          { model: PaymentCurrency, as: 'paymentCurrency', required: false },
-          { model: PaymentIntent, as: 'paymentIntent', required: false },
-          { model: PaymentMethod, as: 'paymentMethod', required: false },
-        ],
-      });
-
-      if (failedPayout) {
-        return res.status(400).json({
-          ...failedPayout.toJSON(),
-          error: processError.message || processError.error?.message || 'Payout transfer failed',
-        });
-      }
-      throw processError;
-    }
-  } catch (err: any) {
-    logger.error('Create synchronous payout failed', {
-      error: err,
-      requestedBy: req.user?.did,
-    });
-    return res.status(400).json({ error: err.message });
-  }
-});
-
 router.get('/:id', authPortal, async (req, res) => {
   try {
     const doc = (await Payout.findOne({

package/api/src/routes/refunds.ts

@@ -1,11 +1,18 @@
 /* eslint-disable no-console */
 /* eslint-disable consistent-return */
+import OcapClient from '@ocap/client';
+import { BN, fromTokenToUnit } from '@ocap/util';
+import { ethers } from 'ethers';
 import { Router } from 'express';
 import Joi from 'joi';
 import pick from 'lodash/pick';
 
-import { BN, fromTokenToUnit } from '@ocap/util';
+import { getWallet } from '@blocklet/sdk/lib/wallet';
+import { Op } from 'sequelize';
+import { sendErc20ToUser } from '../integrations/ethereum/token';
 import { BNPositiveValidator, createListParamSchema, getOrder, getWhereFromKvQuery, MetadataSchema } from '../libs/api';
+import { wallet } from '../libs/auth';
+import { EVM_CHAIN_TYPES } from '../libs/constants';
 import { authenticate } from '../libs/security';
 import { formatMetadata } from '../libs/util';
 import {
@@ -18,6 +25,7 @@ import {
   Subscription,
 } from '../store/models';
 import logger from '../libs/logger';
+import { getGasPayerExtra } from '../libs/payment';
 import { getRefundAmountSetup } from '../libs/refund';
 
 const router = Router();
@@ -208,6 +216,450 @@ router.get('/search', auth, async (req, res) => {
   res.json({ count, list, paging: { page, pageSize } });
 });
 
+// Helper function: Query payment method and currency by contract and chain type
+async function queryPaymentMethodAndCurrency(
+  chainType: string,
+  livemode: boolean,
+  contract: string
+): Promise<{
+  paymentCurrency: PaymentCurrency | null;
+  paymentMethodId: string;
+  currencyId: string;
+}> {
+  let paymentMethod: PaymentMethod | null = null;
+  let paymentCurrency: PaymentCurrency | null = null;
+  let paymentMethodId = '';
+  let currencyId = '';
+
+  paymentMethod = await PaymentMethod.findOne({
+    where: { type: chainType, livemode },
+  });
+
+  if (paymentMethod) {
+    paymentMethodId = paymentMethod.id;
+    paymentCurrency = await PaymentCurrency.findOne({
+      where: { contract, payment_method_id: paymentMethod.id },
+    });
+    if (paymentCurrency) {
+      currencyId = paymentCurrency.id;
+      logger.info('PaymentMethod and Currency ID queried by contract and chain_type', {
+        paymentMethodId,
+        currencyId,
+        contract,
+        chainType,
+      });
+    } else {
+      logger.warn('PaymentCurrency not found by contract and chain_type', {
+        contract,
+        chainType,
+        paymentMethodId: paymentMethod.id,
+      });
+    }
+  } else {
+    logger.warn('PaymentMethod not found by chain_type', { chainType, livemode });
+  }
+
+  return { paymentCurrency, paymentMethodId, currencyId };
+}
+
+// Helper function: Resolve or create payment intent
+async function resolveOrCreatePaymentIntent(
+  customerId: string,
+  finalPaymentMethodId: string,
+  finalCurrencyId: string,
+  livemode: boolean,
+  amount: string,
+  chainType: string,
+  destination: string,
+  description: string | undefined,
+  metadata: Record<string, any> | undefined
+): Promise<string> {
+  if (!finalPaymentMethodId || !finalCurrencyId) {
+    logger.warn('Cannot create payment intent: missing payment_method_id or currency_id', {
+      hasPaymentMethod: !!finalPaymentMethodId,
+      hasCurrency: !!finalCurrencyId,
+    });
+    return '';
+  }
+
+  // Validate and normalize customer_id - must be non-empty string if provided
+  let finalCustomerId: string | undefined;
+  if (customerId && customerId.trim().length > 0) {
+    finalCustomerId = customerId.trim();
+  } else if (customerId && customerId.trim().length === 0) {
+    logger.warn('Invalid customer_id: empty string, will not set customer_id', {
+      customerId,
+    });
+  }
+
+  const createData: any = {
+    livemode,
+    amount,
+    amount_received: amount,
+    amount_capturable: '0',
+    currency_id: finalCurrencyId,
+    payment_method_id: finalPaymentMethodId,
+    description: description || `Refund to ${destination}`,
+    status: 'succeeded',
+    capture_method: 'automatic',
+    confirmation_method: 'automatic',
+    payment_method_types: [chainType],
+    statement_descriptor: '',
+    statement_descriptor_suffix: '',
+    metadata: formatMetadata(metadata || {}),
+  };
+
+  // Only set customer_id if it's a valid non-empty string
+  if (finalCustomerId) {
+    createData.customer_id = finalCustomerId;
+  }
+
+  try {
+    const newPaymentIntent = await PaymentIntent.create(createData);
+
+    logger.info('Created new payment intent for refund', {
+      paymentIntentId: newPaymentIntent.id,
+      refundAmount: amount,
+    });
+
+    return newPaymentIntent.id;
+  } catch (error: any) {
+    logger.error('Failed to create payment intent for refund', {
+      error,
+      createData: {
+        ...createData,
+        customer_id: createData.customer_id || 'null',
+        customer_id_length: createData.customer_id?.length || 0,
+      },
+    });
+    throw error;
+  }
+}
+
+// Returns transaction hash and payment details
+async function processDirectTransfer({
+  destination,
+  amount,
+  recordId,
+  contract,
+  chainType,
+  chainApiHost,
+  description,
+}: {
+  destination: string;
+  amount: string;
+  recordId: string;
+  contract: string;
+  chainType: string;
+  chainApiHost: string;
+  description: string;
+}): Promise<{ txHash: string; paymentDetails: any }> {
+  if (chainType === 'arcblock') {
+    const client = new OcapClient(chainApiHost);
+    const signed = await client.signTransferV2Tx({
+      tx: {
+        itx: {
+          to: destination,
+          value: '0',
+          assets: [],
+          tokens: [{ address: contract, value: amount }],
+          data: {
+            typeUrl: 'json',
+            // @ts-ignore
+            value: {
+              appId: wallet.address,
+              reason: description || `Refund to ${destination}`,
+              refundId: recordId,
+            },
+          },
+        },
+      },
+      wallet,
+    });
+
+    // @ts-ignore
+    const { buffer } = await client.encodeTransferV2Tx({ tx: signed });
+    // @ts-ignore
+    const txHash = await client.sendTransferV2Tx({ tx: signed, wallet }, await getGasPayerExtra(buffer));
+
+    return {
+      txHash,
+      paymentDetails: {
+        arcblock: {
+          tx_hash: txHash,
+          payer: wallet.address,
+          type: 'transfer',
+        },
+      },
+    };
+  }
+  if (EVM_CHAIN_TYPES.includes(chainType)) {
+    const provider = new ethers.JsonRpcProvider(chainApiHost);
+    const receipt = await sendErc20ToUser(provider, contract, destination, amount);
+    const tx = await provider.getTransaction(receipt.hash);
+    const payerAddress = tx?.from || '';
+
+    const paymentDetails: any = {
+      [chainType]: {
+        tx_hash: receipt.hash,
+        payer: payerAddress,
+        type: 'transfer',
+      },
+    };
+
+    if (receipt) {
+      paymentDetails[chainType].block_height = receipt.blockNumber.toString();
+      paymentDetails[chainType].gas_used = receipt.gasUsed.toString();
+      paymentDetails[chainType].gas_price = receipt.gasPrice?.toString() || '0';
+    }
+
+    return {
+      txHash: receipt.hash,
+      paymentDetails,
+    };
+  }
+  throw new Error(`Unsupported chain type: ${chainType}`);
+}
+
+const syncRefundRequestSchema = Joi.object({
+  // Refund creation required fields
+  livemode: Joi.number().required().description('Testnet (0) or mainnet (1)'),
+  amount: Joi.string().required().description('Transfer amount in unit format'),
+  destination: Joi.string().required().description('Output account address (to address)'),
+
+  // Transfer execution required fields
+  contract: Joi.string().required().description('Token contract address for transfer'),
+  chainType: Joi.string().required().description('Chain type, e.g. "arcblock", "ethereum", "base", "bitcoin"'),
+  chainApiHost: Joi.string().required().description('RPC API endpoint for the chain'),
+
+  // Optional fields
+  description: Joi.string().max(512).optional().description('Refund description (optional)'),
+  orderId: Joi.string().optional().description('Order ID for duplicate check (optional)'),
+  customerName: Joi.string().optional().description('Customer name for mock user (default: "Broker")'),
+  metadata: MetadataSchema.optional(),
+});
+
+router.post('/sync', authAdmin, async (req: any, res: any) => {
+  const { error } = syncRefundRequestSchema.validate(req.body);
+  if (error) {
+    return res.status(400).json({ error: `Refund request invalid: ${error.message}` });
+  }
+
+  // Extract and validate request data
+  const { livemode, amount, destination, contract, chainType, chainApiHost } = req.body;
+  const { description, metadata, orderId, customerName } = req.body;
+
+  try {
+    // Convert and validate input types
+    const livemodeBoolean = !!livemode;
+    const amountString = String(amount);
+    const amountBN = new BN(amountString);
+    if (amountBN.lte(new BN('0'))) {
+      throw new Error('Refund amount must be greater than 0');
+    }
+
+    // Query payment method and currency first (needed for duplicate check)
+    const { paymentMethodId: finalPaymentMethodId, currencyId: finalCurrencyId } = await queryPaymentMethodAndCurrency(
+      chainType,
+      livemodeBoolean,
+      contract
+    );
+
+    // Check for existing refund with same orderId in metadata if provided
+    if (orderId && orderId.trim()) {
+      const existingRefund = await Refund.findOne({
+        where: {
+          metadata: { orderId: orderId.trim() },
+          status: { [Op.in]: ['succeeded', 'pending'] },
+        },
+      });
+
+      if (existingRefund) {
+        logger.info('Order refund already completed or in-progress. Current request interrupted/terminated', {
+          orderId,
+          refundId: existingRefund.id,
+          status: existingRefund.status,
+        });
+
+        return res.json(existingRefund);
+      }
+    }
+
+    // Get system DID as default payer (发款方)
+    const systemDid = getWallet().address;
+
+    // Create mock customer if customerName is provided, otherwise use "Broker" as default
+    const finalCustomerName = customerName || 'Broker';
+    let finalCustomer = await Customer.findOne({
+      where: { did: systemDid },
+    });
+
+    if (!finalCustomer) {
+      finalCustomer = await Customer.create({
+        livemode: livemodeBoolean,
+        did: systemDid,
+        name: finalCustomerName,
+        email: '',
+        phone: '',
+        address: Customer.formatAddressFromUser(null),
+        description: 'Broker customer for refund',
+        metadata: { isBroker: true },
+        balance: '0',
+        next_invoice_sequence: 1,
+        delinquent: false,
+        invoice_prefix: Customer.getInvoicePrefix(),
+      });
+      logger.info('Created mock customer for refund', {
+        customerId: finalCustomer.id,
+        customerName: finalCustomerName,
+        did: systemDid,
+      });
+    }
+
+    if (finalCustomerName !== finalCustomer?.name) {
+      finalCustomer = await finalCustomer.update({ name: finalCustomerName, metadata: { isBroker: true } });
+    }
+
+    // Resolve or create payment intent
+    const finalPaymentIntentId = await resolveOrCreatePaymentIntent(
+      finalCustomer.id,
+      finalPaymentMethodId,
+      finalCurrencyId,
+      livemodeBoolean,
+      amountString,
+      chainType,
+      destination,
+      description,
+      { ...metadata, payerDid: systemDid }
+    );
+
+    // Build metadata with orderId and destination (Refund model doesn't have destination field)
+    const refundMetadata = {
+      ...formatMetadata(metadata || {}),
+      ...(orderId && orderId.trim() ? { orderId: orderId.trim() } : {}),
+      payerDid: systemDid,
+    };
+
+    // Create refund record
+    const refund = await Refund.create({
+      livemode: livemodeBoolean,
+      description: description || `Refund to ${destination}`,
+      amount: amountString,
+      payment_intent_id: finalPaymentIntentId || '',
+      customer_id: finalCustomer.id,
+      currency_id: finalCurrencyId || '',
+      payment_method_id: finalPaymentMethodId || '',
+      status: 'pending',
+      attempt_count: 0,
+      attempted: false,
+      next_attempt: 0,
+      last_attempt_error: null,
+      starting_balance: '0',
+      ending_balance: '0',
+      starting_token_balance: {},
+      ending_token_balance: {},
+      type: 'refund',
+      metadata: refundMetadata,
+    });
+
+    logger.info('Synchronous refund created, processing transfer directly', {
+      refundId: refund.id,
+      destination,
+      amount,
+      chainType,
+      requestedBy: req.user?.did,
+    });
+
+    // Process transfer
+    try {
+      const { txHash, paymentDetails } = await processDirectTransfer({
+        destination,
+        amount: amountString,
+        recordId: refund.id,
+        contract,
+        chainType,
+        chainApiHost,
+        description: description || `Refund to ${destination}`,
+      });
+
+      await refund.update({
+        status: 'succeeded',
+        last_attempt_error: null,
+        attempt_count: refund.attempt_count + 1,
+        attempted: true,
+        payment_details: paymentDetails,
+      });
+
+      logger.info('Synchronous refund transfer completed', {
+        refundId: refund.id,
+        txHash,
+        requestedBy: req.user?.did,
+      });
+
+      // Reload and enrich refund data
+      const updatedRefund = await Refund.findByPk(refund.id, {
+        include: [
+          { model: PaymentCurrency, as: 'paymentCurrency', required: false },
+          { model: PaymentIntent, as: 'paymentIntent', required: false },
+          { model: PaymentMethod, as: 'paymentMethod', required: false },
+        ],
+      });
+
+      if (!updatedRefund) {
+        throw new Error('Refund not found after processing');
+      }
+
+      return res.json(updatedRefund.toJSON());
+    } catch (processError: any) {
+      logger.error('Synchronous refund transfer failed', {
+        error: processError,
+        requestedBy: req.user?.did,
+      });
+      // Handle transfer failure
+      await refund.update({
+        status: 'failed',
+        last_attempt_error: {
+          type: 'api_error',
+          code: processError.code || 'api_error',
+          message: processError.message || 'Transfer failed',
+        },
+        attempt_count: refund.attempt_count + 1,
+        attempted: true,
+        failure_reason: 'unknown',
+      });
+
+      logger.error('Synchronous refund transfer failed', {
+        refundId: refund.id,
+        error: processError.message || processError.error?.message,
+        requestedBy: req.user?.did,
+      });
+
+      // Reload and enrich failed refund data
+      const failedRefund = await Refund.findByPk(refund.id, {
+        include: [
+          { model: PaymentCurrency, as: 'paymentCurrency', required: false },
+          { model: PaymentIntent, as: 'paymentIntent', required: false },
+          { model: PaymentMethod, as: 'paymentMethod', required: false },
+        ],
+      });
+
+      if (failedRefund) {
+        return res.status(400).json({
+          ...failedRefund.toJSON(),
+          error: processError.message || processError.error?.message || 'Refund transfer failed',
+        });
+      }
+      throw processError;
+    }
+  } catch (err: any) {
+    logger.error('Create synchronous refund failed', {
+      error: err,
+      requestedBy: req.user?.did,
+    });
+    return res.status(400).json({ error: err.message });
+  }
+});
+
 router.get('/:id', auth, async (req, res) => {
   const doc = await Refund.findByPk(req.params.id as string, {
     include: [

package/api/src/routes/vendor.ts

@@ -686,6 +686,7 @@ async function handleSubscriptionRedirect(req: any, res: any) {
 
 async function vendorRefund(req: any, res: any) {
   const { id } = req.params;
+  const { reason } = req.body;
   try {
     const payout = await Payout.findByPk(id);
 
@@ -708,7 +709,7 @@ async function vendorRefund(req: any, res: any) {
 
     let refundInfo;
     try {
-      refundInfo = await buildRefundInfoFromPayout(payout);
+      refundInfo = await buildRefundInfoFromPayout(payout, reason);
     } catch (err: any) {
       return res.status(400).json({ error: err.message });
     }
@@ -731,24 +732,24 @@ async function vendorRefund(req: any, res: any) {
       orderId: payout.vendor_info.order_id,
     });
 
-    if (['paid'].includes(result.data?.payoutResult?.status)) {
+    if (result.data?.refundResult?.status === 'succeeded') {
       logger.info('Vendor payout refund successful', {
         payoutId: payout.id,
         orderId: payout.vendor_info.order_id,
-        payoutResult: result.data?.payoutResult,
+        refundResult: result.data?.refundResult,
       });
-      await payout.update({ status: 'reverted' });
-      return res.json({ data: result.data?.payoutResult });
+      await payout.update({ status: 'reverted', description: reason || 'Refund requested by admin' });
+      return res.json({ data: result.data?.refundResult });
     }
     logger.error('Vendor payout refund failed', {
       payoutId: payout.id,
       orderId: payout.vendor_info.order_id,
       refundInfo,
-      payoutResult: result.data?.payoutResult,
+      refundResult: result.data?.refundResult,
     });
     return res.status(400).json({
       error: result.message || 'Vendor payout refund failed',
-      data: result.data?.payoutResult,
+      data: result.data?.refundResult,
       requestedBy: req.user?.did,
     });
   } catch (err: 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.22.20
+version: 1.22.22
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.22.20",
+  "version": "1.22.22",
   "scripts": {
     "dev": "blocklet dev --open",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
@@ -57,9 +57,9 @@
     "@blocklet/error": "^0.3.3",
     "@blocklet/js-sdk": "^1.17.3-beta-20251119-102907-28b69b76",
     "@blocklet/logger": "^1.17.3-beta-20251119-102907-28b69b76",
-    "@blocklet/payment-broker-client": "1.22.20",
-    "@blocklet/payment-react": "1.22.20",
-    "@blocklet/payment-vendor": "1.22.20",
+    "@blocklet/payment-broker-client": "1.22.22",
+    "@blocklet/payment-react": "1.22.22",
+    "@blocklet/payment-vendor": "1.22.22",
     "@blocklet/sdk": "^1.17.3-beta-20251119-102907-28b69b76",
     "@blocklet/ui-react": "^3.2.7",
     "@blocklet/uploader": "^0.3.11",
@@ -129,7 +129,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.17.3-beta-20251119-102907-28b69b76",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.22.20",
+    "@blocklet/payment-types": "1.22.22",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -176,5 +176,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "2928d141aea59ed8c5b332a017b40d639fafd976"
+  "gitHead": "4324caf5e314593d0a56b4893f503932ae83d8ae"
 }

package/src/components/customer/link.tsx

@@ -3,6 +3,8 @@ import { Link } from 'react-router-dom';
 import UserCard from '@arcblock/ux/lib/UserCard';
 import { getCustomerAvatar } from '@blocklet/payment-react';
 import { InfoType, UserCardProps } from '@arcblock/ux/lib/UserCard/types';
+import DID from '@arcblock/ux/lib/DID';
+import { Box, Typography } from '@mui/material';
 
 export default function CustomerLink({
   customer,
@@ -21,6 +23,15 @@ export default function CustomerLink({
   if (!customer) {
     return null;
   }
+
+  if (customer?.metadata?.isBroker) {
+    return (
+      <Box>
+        <Typography variant="body2">{customer.name}</Typography>
+        <DID did={customer.did} {...(size !== 'small' ? { responsive: false, compact: true } : {})} />
+      </Box>
+    );
+  }
   const CustomerCard = (
     // @ts-ignore
     <UserCard

package/src/components/payouts/actions.tsx

@@ -1,10 +1,12 @@
 import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
 import Toast from '@arcblock/ux/lib/Toast';
-import { ConfirmDialog, api, formatError } from '@blocklet/payment-react';
+import { api, formatError } from '@blocklet/payment-react';
 import type { TPayoutExpanded } from '@blocklet/payment-types';
 import { useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import type { LiteralUnion } from 'type-fest';
+import Dialog from '@arcblock/ux/lib/Dialog';
+import { Box, Button, Stack, TextField, Typography } from '@mui/material';
 
 import Actions from '../actions';
 import ClickBoundary from '../click-boundary';
@@ -12,24 +14,56 @@ import ClickBoundary from '../click-boundary';
 type Props = {
   data: TPayoutExpanded;
   variant?: LiteralUnion<'compact' | 'normal', string>;
+  isCanceledSubscription?: boolean;
 };
 
-export default function PayoutActions({ data, variant = 'compact' }: Props) {
+export default function PayoutActions({ data, variant = 'compact', isCanceledSubscription = false }: Props) {
   const { t } = useLocaleContext();
   const navigate = useNavigate();
   const [loading, setLoading] = useState(false);
   const [showRefundDialog, setShowRefundDialog] = useState(false);
+  const [refundReason, setRefundReason] = useState('');
+  const [refundReasonError, setRefundReasonError] = useState('');
+
+  const MIN_REASON_LENGTH = 5;
+
+  const validateRefundReason = (value: string) => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      setRefundReasonError(t('admin.payout.refundReasonRequired'));
+      return false;
+    }
+    if (trimmed.length < MIN_REASON_LENGTH) {
+      setRefundReasonError(t('admin.payout.refundReasonMinLength', { min: MIN_REASON_LENGTH }));
+      return false;
+    }
+    setRefundReasonError('');
+    return true;
+  };
+
+  const handleRefundReasonChange = (value: string) => {
+    setRefundReason(value);
+    if (refundReasonError) {
+      validateRefundReason(value);
+    }
+  };
 
   const handleRequestRefund = async () => {
+    if (!validateRefundReason(refundReason)) {
+      return;
+    }
+
     setLoading(true);
     try {
       const { data: refundData } = await api.post(`/api/vendors/refund/${data.id}`, {
-        reason: 'Refund requested by admin',
+        reason: refundReason.trim(),
       });
 
       if (!refundData.error) {
         Toast.success(t('admin.payout.refundRequested'));
         setShowRefundDialog(false);
+        setRefundReason('');
+        setRefundReasonError('');
         // Optionally refresh the page or update the UI
         window.location.reload();
       } else {
@@ -42,6 +76,14 @@ export default function PayoutActions({ data, variant = 'compact' }: Props) {
     }
   };
 
+  const handleCloseDialog = () => {
+    setShowRefundDialog(false);
+    setRefundReason('');
+    setRefundReasonError('');
+  };
+
+  const isRefundReasonValid = refundReason.trim().length >= MIN_REASON_LENGTH;
+
   const actions = [
     {
       label: t('admin.customer.view'),
@@ -52,7 +94,7 @@ export default function PayoutActions({ data, variant = 'compact' }: Props) {
   ];
 
   // Add Request Refund button if payout is paid and has vendor info
-  if (data.status === 'paid' && data.vendor_info?.vendor_id && data.vendor_info?.order_id) {
+  if (isCanceledSubscription && data.status === 'paid' && data.vendor_info?.vendor_id && data.vendor_info?.order_id) {
     actions.push({
       label: t('admin.payout.requestRefund'),
       handler: () => setShowRefundDialog(true),
@@ -73,15 +115,48 @@ export default function PayoutActions({ data, variant = 'compact' }: Props) {
   return (
     <ClickBoundary>
       <Actions variant={variant} actions={actions} />
-      {showRefundDialog && (
-        <ConfirmDialog
-          onConfirm={handleRequestRefund}
-          onCancel={() => setShowRefundDialog(false)}
-          title={t('admin.payout.requestRefund')}
-          message={t('admin.payout.confirmRefund')}
-          loading={loading}
-        />
-      )}
+      <Dialog
+        open={showRefundDialog}
+        onClose={handleCloseDialog}
+        title={t('admin.payout.requestRefund')}
+        fullWidth
+        actions={
+          <Box sx={{ display: 'flex', gap: 1, justifyContent: 'flex-end' }}>
+            <Button onClick={handleCloseDialog} disabled={loading} size="small" variant="outlined">
+              {t('common.cancel')}
+            </Button>
+            <Button
+              onClick={handleRequestRefund}
+              disabled={loading || !isRefundReasonValid}
+              variant="contained"
+              color="warning"
+              size="small">
+              {t('common.confirm')}
+            </Button>
+          </Box>
+        }>
+        <Stack spacing={2}>
+          <Typography variant="body2" color="text.secondary" sx={{ lineHeight: 1.6 }}>
+            {t('admin.payout.confirmRefund')}
+          </Typography>
+          <TextField
+            value={refundReason}
+            onChange={(e) => handleRefundReasonChange(e.target.value)}
+            onBlur={() => validateRefundReason(refundReason)}
+            label={t('admin.payout.refundReason')}
+            placeholder={t('admin.payout.refundReasonPlaceholder')}
+            multiline
+            minRows={4}
+            maxRows={8}
+            fullWidth
+            required
+            disabled={loading}
+            error={!!refundReasonError}
+            helperText={refundReasonError || t('admin.payout.refundReasonHelper', { min: MIN_REASON_LENGTH })}
+            slotProps={{ htmlInput: { maxLength: 500 } }}
+          />
+        </Stack>
+      </Dialog>
     </ClickBoundary>
   );
 }

package/src/components/payouts/list.tsx

@@ -58,6 +58,7 @@ type ListProps = {
   status?: string;
   customer_id?: string;
   payment_intent_id?: string;
+  isCanceledSubscription?: boolean;
 };
 
 const getListKey = (props: ListProps) => {
@@ -79,6 +80,7 @@ export default function PayoutList({
     customer: true,
     filter: true,
   },
+  isCanceledSubscription = false,
 }: ListProps) {
   const { t } = useLocaleContext();
   const [searchParams] = useSearchParams();
@@ -219,7 +221,7 @@ export default function PayoutList({
       options: {
         customBodyRenderLite: (_: string, index: number) => {
           const item = data.list[index] as TPayoutExpanded;
-          return <PayoutActions data={item} />;
+          return <PayoutActions data={item} isCanceledSubscription={isCanceledSubscription} />;
         },
       },
     },

package/src/locales/en.tsx

@@ -1062,6 +1062,11 @@ export default flat({
       requestRefund: 'Request Refund',
       confirmRefund: 'Are you sure you want to request a refund from the vendor?',
       refundRequested: 'Refund request sent to vendor',
+      refundReason: 'Refund Reason',
+      refundReasonPlaceholder: 'Please enter the reason for refund (at least 5 characters)',
+      refundReasonRequired: 'Refund reason is required',
+      refundReasonMinLength: 'Refund reason must be at least {min} characters',
+      refundReasonHelper: 'Please enter at least {min} characters',
       status: {
         active: 'Active',
         paid: 'Paid',

package/src/locales/zh.tsx

@@ -963,6 +963,11 @@ export default flat({
       requestRefund: '请求退款',
       confirmRefund: '确定要向供应商请求退款吗?',
       refundRequested: '退款请求已发送给供应商',
+      refundReason: '退款原因',
+      refundReasonPlaceholder: '请输入退款原因（至少 5 个字符）',
+      refundReasonRequired: '退款原因为必填项',
+      refundReasonMinLength: '退款原因至少需要 {min} 个字符',
+      refundReasonHelper: '请输入至少 {min} 个字符',
       status: {
         active: '生效中',
         paid: '已支付',

package/src/pages/admin/payments/intents/detail.tsx

@@ -19,8 +19,10 @@ import { Alert, Avatar, Box, Button, CircularProgress, Divider, Stack, Tooltip,
 import { styled } from '@mui/system';
 import { useRequest, useSetState } from 'ahooks';
 import { Link } from 'react-router-dom';
+import { isValid } from '@arcblock/did';
 
 import { startCase } from 'lodash';
+import DID from '@arcblock/ux/lib/DID';
 import Copyable from '../../../../components/copyable';
 import CustomerLink from '../../../../components/customer/link';
 import EventList from '../../../../components/event/list';
@@ -93,6 +95,8 @@ export default function PaymentIntentDetail(props: { id: string }) {
   const handleEditMetadata = () => {
     setState((prev) => ({ editing: { ...prev.editing, metadata: true } }));
   };
+
+  const canceledSubscription = data.subscription?.status === 'canceled';
   return (
     <Root direction="column" spacing={2.5} mb={4}>
       <Box>
@@ -207,7 +211,17 @@ export default function PaymentIntentDetail(props: { id: string }) {
             />
             {/* <InfoMetric label={t('common.createdAt')} value={formatTime(data.created_at)} divider />
             <InfoMetric label={t('common.updatedAt')} value={formatTime(data.updated_at)} divider /> */}
-            <InfoMetric label={t('common.customer')} value={<CustomerLink customer={data.customer} />} divider />
+            <InfoMetric
+              label={t('common.customer')}
+              value={
+                data.metadata?.payerDid && isValid(data.metadata?.payerDid) ? (
+                  <DID did={data.metadata?.payerDid} {...(isMobile ? { responsive: false, compact: true } : {})} />
+                ) : (
+                  <CustomerLink customer={data.customer} />
+                )
+              }
+              divider
+            />
           </Stack>
         </Box>
         <Divider />
@@ -318,7 +332,11 @@ export default function PaymentIntentDetail(props: { id: string }) {
           <Box className="section">
             <SectionHeader title={t('admin.payouts')} />
             <Box className="section-body">
-              <PayoutList features={{ toolbar: false }} payment_intent_id={data?.id} />
+              <PayoutList
+                features={{ toolbar: false }}
+                payment_intent_id={data?.id}
+                isCanceledSubscription={canceledSubscription}
+              />
             </Box>
           </Box>
           <Divider />

package/src/pages/admin/payments/payouts/detail.tsx

@@ -117,7 +117,7 @@ export default function PayoutDetail(props: { id: string }) {
 
   const isAnonymousPayer = paymentIntent?.customer?.metadata?.anonymous;
 
-  const customerDid = paymentIntent?.customer?.did || paymentIntent?.customer_id || '';
+  const customerDid = paymentIntent?.customer?.did || paymentIntent?.metadata?.payerDid || '';
 
   return (
     <Root direction="column" spacing={2.5} mb={4}>