payment-kit 1.22.17 → 1.22.19

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

@@ -11,6 +11,8 @@ import {
   CheckOrderStatusResult,
   FulfillOrderParams,
   FulfillOrderResult,
+  RefundRequestParams,
+  RefundRequestResult,
   ReturnRequestParams,
   ReturnRequestResult,
   VendorAdapter,
@@ -377,16 +379,7 @@ export class DidnamesAdapter implements VendorAdapter {
 
       const didNamesResult = await response.json();
 
-      logger.info('domain return to DID Names processed', {
-        url,
-        orderId: params.orderId,
-        status: didNamesResult.status,
-      });
-
-      return {
-        status: didNamesResult.status || 'requested',
-        message: didNamesResult.message || 'Domain unbinding requested',
-      };
+      return didNamesResult;
     } catch (error: any) {
       logger.error('Failed to process return request', {
         error: error.message,
@@ -397,6 +390,39 @@ export class DidnamesAdapter implements VendorAdapter {
     }
   }
 
+  async requestRefund(params: RefundRequestParams): Promise<RefundRequestResult> {
+    logger.info('Requesting refund for payout', { params });
+
+    const vendorConfig = await this.getVendorConfig();
+    const { headers, body } = await VendorAuth.signRequestWithHeaders(params);
+
+    const response = await fetch(formatVendorUrl(vendorConfig, '/api/vendor/refund'), {
+      method: 'POST',
+      headers,
+      body,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      logger.error('Vendor refund API error', {
+        status: response.status,
+        statusText: response.statusText,
+        body: errorBody,
+        orderId: params.orderId,
+      });
+      throw new Error(`Vendor refund API error: ${response.status} ${response.statusText}`);
+    }
+
+    const result = await response.json();
+
+    logger.info('Vendor refund request completed', {
+      orderId: params.orderId,
+      status: result.status,
+    });
+
+    return result;
+  }
+
   async checkOrderStatus(params: CheckOrderStatusParams): Promise<CheckOrderStatusResult> {
     logger.info('Checking Didnames order status', {
       orderId: params.orderId,

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

@@ -11,6 +11,8 @@ import {
   CheckOrderStatusResult,
   FulfillOrderParams,
   FulfillOrderResult,
+  RefundRequestParams,
+  RefundRequestResult,
   ReturnRequestParams,
   ReturnRequestResult,
   VendorAdapter,
@@ -262,6 +264,39 @@ export class LauncherAdapter implements VendorAdapter {
     return launcherResult;
   }
 
+  async requestRefund(params: RefundRequestParams): Promise<RefundRequestResult> {
+    logger.info('Requesting refund for payout', { params });
+
+    const vendorConfig = await this.getVendorConfig();
+    const { headers, body } = await VendorAuth.signRequestWithHeaders(params);
+
+    const response = await fetch(formatVendorUrl(vendorConfig, '/api/vendor/refund'), {
+      method: 'POST',
+      headers,
+      body,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      logger.error('Vendor refund API error', {
+        status: response.status,
+        statusText: response.statusText,
+        body: errorBody,
+        orderId: params.orderId,
+      });
+      throw new Error(`Vendor refund API error: ${response.status} ${response.statusText}`);
+    }
+
+    const result = await response.json();
+
+    logger.info('Vendor refund request completed', {
+      orderId: params.orderId,
+      status: result.status,
+    });
+
+    return result;
+  }
+
   async checkOrderStatus(params: CheckOrderStatusParams): Promise<CheckOrderStatusResult> {
     try {
       const blockletInfo = await getBlockletInfo(params.appUrl);

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

@@ -72,9 +72,24 @@ export interface ReturnRequestParams {
 }
 
 export interface ReturnRequestResult {
-  status: 'requested' | 'accepted' | 'rejected' | 'failed';
+  code: string;
   message?: string;
-  success?: boolean;
+  data?: Record<string, any>;
+}
+
+export interface RefundRequestParams {
+  orderId: string;
+  amount: string;
+  livemode: number;
+  contract: string;
+  chainType: string;
+  chainApiHost: string;
+}
+
+export interface RefundRequestResult {
+  code?: string;
+  message?: string;
+  data?: Record<string, any>;
 }
 
 export interface CheckOrderStatusParams extends Record<string, any> {}
@@ -86,6 +101,7 @@ export interface CheckOrderStatusResult {
 export interface VendorAdapter {
   fulfillOrder(params: FulfillOrderParams): Promise<FulfillOrderResult>;
   requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult>;
+  requestRefund(params: RefundRequestParams): Promise<RefundRequestResult>;
   checkOrderStatus(params: CheckOrderStatusParams): Promise<CheckOrderStatusResult>;
   getOrder(vendor: ProductVendor, orderId: string, option?: Record<string, any>): Promise<any>;
   getOrderStatus(vendor: ProductVendor, orderId: string, option?: Record<string, any>): Promise<any>;

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

@@ -0,0 +1,46 @@
+import { PaymentCurrency, PaymentMethod, Payout } from '../../store/models';
+
+export interface RefundInfo {
+  livemode: number;
+  amount: string;
+  contract: string;
+  chainType: string;
+  chainApiHost: string;
+}
+
+/**
+ * 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> {
+  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}`);
+  }
+
+  const paymentCurrency = await PaymentCurrency.findByPk(payout.currency_id);
+  if (!paymentCurrency?.contract) {
+    throw new Error(`PaymentCurrency not found: ${payout.currency_id} | Payout ID: ${payout.id}`);
+  }
+
+  const chainType = paymentMethod.type;
+  const chainSettings = paymentMethod.settings[chainType as keyof typeof paymentMethod.settings] as
+    | {
+        api_host: string;
+      }
+    | undefined;
+  const chainApiHost = chainSettings?.api_host || '';
+  if (!chainApiHost) {
+    throw new Error(
+      `Chain API host not found for payment method: ${paymentMethod.id} | Chain type: ${chainType} | Payout ID: ${payout.id}`
+    );
+  }
+
+  return {
+    livemode: payout.livemode ? 1 : 0,
+    amount: payout.amount,
+    contract: paymentCurrency.contract,
+    chainType,
+    chainApiHost,
+  };
+}

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

@@ -852,6 +852,7 @@ async function requestReturnFromSingleVendor(
       throw new Error(`No adapter found for vendor: ${vendor.vendor_id}`);
     }
 
+    // revenue has not been split yet, so no refund operation is needed.
     const returnResult = await vendorAdapter.requestReturn({
       orderId: vendor.order_id,
       reason: `Return request due to: ${reason}`,
@@ -861,11 +862,10 @@ async function requestReturnFromSingleVendor(
       },
     });
 
-    let { status } = returnResult;
-    if (returnResult.status === 'requested') {
-      status = 'pending' as 'accepted';
-    } else if (returnResult.status === 'failed') {
-      status = 'rejected' as 'rejected';
+    const { code } = returnResult;
+    let status: 'pending' | 'rejected' = 'pending';
+    if (code) {
+      status = 'rejected';
     }
 
     await updateSingleVendorInfo(checkoutSession.id, vendor.vendor_id, {
@@ -873,7 +873,7 @@ async function requestReturnFromSingleVendor(
       returnRequest: {
         reason,
         requestedAt: new Date().toISOString(),
-        status: status as 'pending' | 'accepted' | 'rejected',
+        status,
         returnDetails: returnResult.message,
       },
     });
@@ -881,7 +881,7 @@ async function requestReturnFromSingleVendor(
     logger.info('Return request submitted successfully', {
       vendorId: vendor.vendor_id,
       orderId: vendor.order_id,
-      returnStatus: returnResult.status,
+      returnResult,
     });
   } catch (error: any) {
     logger.error('Return request failed', {

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

@@ -1,7 +1,9 @@
 import logger from '../../libs/logger';
 import createQueue from '../../libs/queue';
 import { VendorFulfillmentService } from '../../libs/vendor-util/fulfillment';
-import { CheckoutSession } from '../../store/models';
+import { buildRefundInfoFromPayout } from '../../libs/vendor-util/tool';
+import { CheckoutSession, Payout } from '../../store/models';
+import { payoutQueue } from '../payout';
 import { VendorInfo } from './fulfillment-coordinator';
 
 export const MAX_RETURN_RETRY = 3;
@@ -154,13 +156,83 @@ async function callVendorReturn(vendor: VendorInfo, checkoutSession: CheckoutSes
     throw new Error(`No adapter found for vendor: ${vendor.vendor_id}`);
   }
 
-  return vendorAdapter.requestReturn({
-    orderId: vendor.order_id,
-    reason: 'Subscription canceled',
-    customParams: {
-      checkoutSessionId: checkoutSession.id,
-      subscriptionId: checkoutSession.subscription_id,
-      vendorKey: vendor.vendor_key,
-    },
+  const payoutInfo = await Payout.findOne({
+    where: { vendor_info: { order_id: vendor.order_id, vendor_id: vendor.vendor_id } },
   });
+  let refundInfo;
+  if (payoutInfo) {
+    if (['pending', 'deferred', 'failed'].includes(payoutInfo.status)) {
+      logger.info('[callVendorReturn] Cancelling payout status to canceled', {
+        checkoutSessionId: checkoutSession.id,
+        vendorId: vendor.vendor_id,
+        orderId: vendor.order_id,
+      });
+      await payoutQueue.delete(payoutInfo.id);
+      await payoutInfo.update({ status: 'canceled' });
+    } else if (payoutInfo.status === 'paid') {
+      try {
+        refundInfo = await buildRefundInfoFromPayout(payoutInfo);
+      } catch (error: any) {
+        logger.error('[callVendorReturn] Error building refund info', {
+          checkoutSessionId: checkoutSession.id,
+          vendorId: vendor.vendor_id,
+          orderId: vendor.order_id,
+          error,
+        });
+        throw error;
+      }
+      logger.info('[callVendorReturn] Need to request vendor payout refund', {
+        checkoutSessionId: checkoutSession.id,
+        vendorId: vendor.vendor_id,
+        orderId: vendor.order_id,
+        refundInfo,
+      });
+    }
+  } else {
+    logger.error('[callVendorReturn] No payout info found', {
+      checkoutSessionId: checkoutSession.id,
+      vendorId: vendor.vendor_id,
+      orderId: vendor.order_id,
+    });
+  }
+
+  try {
+    const result = await vendorAdapter.requestReturn({
+      orderId: vendor.order_id,
+      reason: 'Subscription canceled',
+      customParams: {
+        checkoutSessionId: checkoutSession.id,
+        subscriptionId: checkoutSession.subscription_id,
+        vendorKey: vendor.vendor_key,
+        refundInfo,
+      },
+    });
+
+    if (payoutInfo && result.data?.payoutResult?.status === 'paid') {
+      logger.info('[callVendorReturn] Vendor payout refund successful', {
+        checkoutSessionId: checkoutSession.id,
+        vendorId: vendor.vendor_id,
+        orderId: vendor.order_id,
+      });
+      await payoutInfo.update({ status: 'reverted' });
+    } else {
+      logger.error('[callVendorReturn] Vendor payout refund failed', {
+        checkoutSessionId: checkoutSession.id,
+        vendorId: vendor.vendor_id,
+        orderId: vendor.order_id,
+        refundInfo,
+        payoutResult: result.data?.payoutResult,
+      });
+    }
+
+    return result;
+  } catch (error: any) {
+    logger.error('[callVendorReturn] Error requesting return', {
+      checkoutSessionId: checkoutSession.id,
+      vendorId: vendor.vendor_id,
+      orderId: vendor.order_id,
+      error,
+    });
+    throw error;
+  }
 }

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

@@ -2,6 +2,7 @@ import { isValid } from '@arcblock/did';
 import { Router } from 'express';
 import Joi from 'joi';
 import pick from 'lodash/pick';
+import { Op } from 'sequelize';
 
 import { BN, fromTokenToUnit } from '@ocap/util';
 import { syncStripeInvoice } from '../integrations/stripe/handlers/invoice';
@@ -356,6 +357,9 @@ router.get('/:id/refundable-amount', authPortal, async (req, res) => {
       const payouts = await Payout.findAll({
         where: {
           payment_intent_id: doc.id,
+          status: {
+            [Op.notIn]: ['canceled', 'reverted'],
+          },
         },
         attributes: ['id', 'amount'],
       });

package/api/src/routes/payouts.ts

@@ -1,21 +1,30 @@
 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';
+import { CheckoutSession } from '../store/models/checkout-session';
 import { Customer } from '../store/models/customer';
 import { PaymentCurrency } from '../store/models/payment-currency';
 import { PaymentIntent } from '../store/models/payment-intent';
 import { PaymentMethod } from '../store/models/payment-method';
 import { Payout } from '../store/models/payout';
-import { PaymentLink, TPaymentIntentExpanded } from '../store/models';
-import { CheckoutSession } from '../store/models/checkout-session';
-import logger from '../libs/logger';
 
 const router = Router();
 const authAdmin = authenticate<Payout>({ component: true, roles: ['owner', 'admin'] });
@@ -176,6 +185,378 @@ 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.number().required().description('Transfer amount in unit format (already converted)'),
+  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().valid('arcblock', 'ethereum', 'base', 'bitcoin').required().description('Chain type'),
+  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 = typeof amount === 'number' ? amount.toString() : 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/vendor.ts

@@ -15,7 +15,8 @@ import { authenticate } from '../libs/security';
 import { formatToShortUrl } from '../libs/url';
 import { getBlockletJson } from '../libs/util';
 import { VendorFulfillmentService } from '../libs/vendor-util/fulfillment';
-import { CheckoutSession, Invoice, Subscription } from '../store/models';
+import { buildRefundInfoFromPayout } from '../libs/vendor-util/tool';
+import { CheckoutSession, Invoice, Payout, PaymentCurrency, Subscription } from '../store/models';
 import { ProductVendor } from '../store/models/product-vendor';
 
 const VENDOR_DID = {
@@ -655,6 +656,14 @@ async function getVendorSubscription(req: any, res: any) {
       'description',
       'invoice_pdf',
     ],
+    include: [
+      {
+        model: PaymentCurrency,
+        as: 'paymentCurrency',
+        attributes: ['id', 'symbol', 'decimal', 'name', 'logo'],
+        required: false,
+      },
+    ],
     limit: 20,
   });
 
@@ -675,6 +684,83 @@ async function handleSubscriptionRedirect(req: any, res: any) {
   return res.redirect(getUrl(`/customer/subscription/${checkoutSession.subscription_id}`));
 }
 
+async function vendorRefund(req: any, res: any) {
+  const { id } = req.params;
+  try {
+    const payout = await Payout.findByPk(id);
+
+    if (!payout) {
+      return res.status(404).json({ error: 'Payout not found' });
+    }
+
+    if (payout.status !== 'paid') {
+      return res.status(400).json({ error: 'Only paid payouts can be refunded' });
+    }
+
+    if (!payout.vendor_info?.vendor_id || !payout.vendor_info?.order_id) {
+      return res.status(400).json({ error: 'Payout has no vendor information' });
+    }
+
+    const vendor = await ProductVendor.findByPk(payout.vendor_info.vendor_id);
+    if (!vendor) {
+      return res.status(404).json({ error: 'Vendor not found' });
+    }
+
+    let refundInfo;
+    try {
+      refundInfo = await buildRefundInfoFromPayout(payout);
+    } catch (err: any) {
+      return res.status(400).json({ error: err.message });
+    }
+
+    const vendorAdapter = await VendorFulfillmentService.getVendorAdapter(vendor.vendor_key);
+    if (!vendorAdapter) {
+      return res.status(404).json({ error: `No adapter found for vendor: ${vendor.vendor_key}` });
+    }
+
+    logger.info('Requesting refund from vendor', {
+      payoutId: payout.id,
+      vendorId: vendor.id,
+      orderId: payout.vendor_info.order_id,
+      refundInfo,
+      requestedBy: req.user?.did,
+    });
+
+    const result = await vendorAdapter.requestRefund({
+      ...refundInfo,
+      orderId: payout.vendor_info.order_id,
+    });
+
+    if (['paid'].includes(result.data?.payoutResult?.status)) {
+      logger.info('Vendor payout refund successful', {
+        payoutId: payout.id,
+        orderId: payout.vendor_info.order_id,
+        payoutResult: result.data?.payoutResult,
+      });
+      await payout.update({ status: 'reverted' });
+      return res.json({ data: result.data?.payoutResult });
+    }
+    logger.error('Vendor payout refund failed', {
+      payoutId: payout.id,
+      orderId: payout.vendor_info.order_id,
+      refundInfo,
+      payoutResult: result.data?.payoutResult,
+    });
+    return res.status(400).json({
+      error: result.message || 'Vendor payout refund failed',
+      data: result.data?.payoutResult,
+      requestedBy: req.user?.did,
+    });
+  } catch (err: any) {
+    logger.error('Request refund failed', {
+      error: err,
+      payoutId: req.params.id,
+      requestedBy: req.user?.did,
+    });
+    return res.status(500).json({ error: err.message || 'Failed to request refund' });
+  }
+}
+
 function getVendorConnectTest(req: any, res: any) {
   const sdkVersion = req.headers['x-broker-vendor-version'];
   if (sdkVersion && gte(sdkVersion, '1.21.4')) {
@@ -710,6 +796,8 @@ router.get(
   redirectToVendor
 );
 
+router.post('/refund/:id', authAdmin, vendorRefund);
+
 router.get('/', getAllVendors);
 router.get('/:id', authAdmin, validateParams(vendorIdParamSchema), getVendorInfo);
 router.post('/', authAdmin, createVendor);

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.22.17",
+  "version": "1.22.19",
   "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.17",
-    "@blocklet/payment-react": "1.22.17",
-    "@blocklet/payment-vendor": "1.22.17",
+    "@blocklet/payment-broker-client": "1.22.19",
+    "@blocklet/payment-react": "1.22.19",
+    "@blocklet/payment-vendor": "1.22.19",
     "@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.17",
+    "@blocklet/payment-types": "1.22.19",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -176,5 +176,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "5de77cb79635cdd8616113c587379fb430530d44"
+  "gitHead": "2a79b0a9d2a27f1605d8f59bec8c0d0d963ba334"
 }

package/src/components/payouts/actions.tsx

@@ -1,5 +1,8 @@
 import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
+import Toast from '@arcblock/ux/lib/Toast';
+import { ConfirmDialog, 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';
 
@@ -14,6 +17,31 @@ type Props = {
 export default function PayoutActions({ data, variant = 'compact' }: Props) {
   const { t } = useLocaleContext();
   const navigate = useNavigate();
+  const [loading, setLoading] = useState(false);
+  const [showRefundDialog, setShowRefundDialog] = useState(false);
+
+  const handleRequestRefund = async () => {
+    setLoading(true);
+    try {
+      const { data: refundData } = await api.post(`/api/vendors/refund/${data.id}`, {
+        reason: 'Refund requested by admin',
+      });
+
+      if (!refundData.error) {
+        Toast.success(t('admin.payout.refundRequested'));
+        setShowRefundDialog(false);
+        // Optionally refresh the page or update the UI
+        window.location.reload();
+      } else {
+        throw new Error(refundData.error || 'Failed to request refund');
+      }
+    } catch (error: any) {
+      Toast.error(formatError(error as any));
+    } finally {
+      setLoading(false);
+    }
+  };
+
   const actions = [
     {
       label: t('admin.customer.view'),
@@ -22,6 +50,17 @@ export default function PayoutActions({ data, variant = 'compact' }: Props) {
       disabled: false,
     },
   ];
+
+  // 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) {
+    actions.push({
+      label: t('admin.payout.requestRefund'),
+      handler: () => setShowRefundDialog(true),
+      color: 'warning',
+      disabled: loading || data.metadata?.refund_requested,
+    });
+  }
+
   if (variant === 'compact') {
     actions.push({
       label: t('admin.paymentIntent.view'),
@@ -34,6 +73,15 @@ 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}
+        />
+      )}
     </ClickBoundary>
   );
 }

package/src/locales/en.tsx

@@ -1059,6 +1059,9 @@ export default flat({
       view: 'View payout',
       empty: 'No payout',
       attention: 'Failed payouts',
+      requestRefund: 'Request Refund',
+      confirmRefund: 'Are you sure you want to request a refund from the vendor?',
+      refundRequested: 'Refund request sent to vendor',
       status: {
         active: 'Active',
         paid: 'Paid',

package/src/locales/zh.tsx

@@ -960,6 +960,9 @@ export default flat({
       view: '查看对外支付',
       empty: '没有记录',
       attention: '失败的对外支付',
+      requestRefund: '请求退款',
+      confirmRefund: '确定要向供应商请求退款吗?',
+      refundRequested: '退款请求已发送给供应商',
       status: {
         active: '生效中',
         paid: '已支付',

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

@@ -1,5 +1,6 @@
 /* eslint-disable react/no-unstable-nested-components */
 import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
+import { isValid } from '@arcblock/did';
 import Toast from '@arcblock/ux/lib/Toast';
 import {
   Amount,
@@ -116,6 +117,8 @@ export default function PayoutDetail(props: { id: string }) {
 
   const isAnonymousPayer = paymentIntent?.customer?.metadata?.anonymous;
 
+  const customerDid = paymentIntent?.customer?.did || paymentIntent?.customer_id || '';
+
   return (
     <Root direction="column" spacing={2.5} mb={4}>
       <Box>
@@ -269,10 +272,9 @@ export default function PayoutDetail(props: { id: string }) {
                       </Typography>
                     }
                     description={
-                      <DID
-                        did={paymentIntent?.customer?.did}
-                        {...(isMobile ? { responsive: false, compact: true } : {})}
-                      />
+                      isValid(customerDid) && (
+                        <DID did={customerDid} {...(isMobile ? { responsive: false, compact: true } : {})} />
+                      )
                     }
                     size={40}
                   />