payment-kit 1.18.13 → 1.18.14

package/api/src/index.ts

@@ -25,6 +25,7 @@ import { startEventQueue } from './queues/event';
 import { startInvoiceQueue } from './queues/invoice';
 import { startNotificationQueue } from './queues/notification';
 import { startPaymentQueue } from './queues/payment';
+import { startPayoutQueue } from './queues/payout';
 import { startRefundQueue } from './queues/refund';
 import { startSubscriptionQueue } from './queues/subscription';
 import routes from './routes';
@@ -108,6 +109,7 @@ export const server = app.listen(port, (err?: any) => {
   startInvoiceQueue().then(() => logger.info('invoice queue started'));
   startSubscriptionQueue().then(() => logger.info('subscription queue started'));
   startEventQueue().then(() => logger.info('event queue started'));
+  startPayoutQueue().then(() => logger.info('payout queue started'));
   startCheckoutSessionQueue().then(() => logger.info('checkoutSession queue started'));
   startNotificationQueue().then(() => logger.info('notification queue started'));
   startRefundQueue().then(() => logger.info('refund queue started'));

package/api/src/integrations/stripe/resource.ts

@@ -24,6 +24,7 @@ import {
 } from '../../store/models';
 import { syncStripeInvoice } from './handlers/invoice';
 import { syncStripePayment } from './handlers/payment-intent';
+import { getLock } from '../../libs/lock';
 
 export async function ensureStripeProduct(internal: Product, method: PaymentMethod) {
   const client = method.getStripeClient();
@@ -118,16 +119,45 @@ export async function ensureStripePrice(internal: Price, method: PaymentMethod,
 
 export async function ensureStripeCustomer(internal: Customer, method: PaymentMethod) {
   const client = method.getStripeClient();
+
+  // 1. check local metadata
+  if (internal.metadata?.stripe_id) {
+    try {
+      const customer = await client.customers.retrieve(internal.metadata.stripe_id);
+      if (customer) {
+        return customer;
+      }
+    } catch (error) {
+      logger.warn('Stored Stripe customer ID not found, will recreate', {
+        customerId: internal.id,
+        stripeId: internal.metadata.stripe_id,
+      });
+    }
+  }
+
+  // 2. search customer on stripe
   const result = await client.customers.search({ query: `metadata['did']:'${internal.did}'` });
   if (result.data.length > 0) {
-    return result.data[0] as any;
+    const stripeCustomer = result.data[0];
+    if (stripeCustomer) {
+      // update local metadata
+      if (!internal.metadata?.stripe_id || internal.metadata.stripe_id !== stripeCustomer!.id) {
+        await internal.update({
+          metadata: merge(internal.metadata || {}, {
+            stripe_id: stripeCustomer!.id,
+            stripe_invoice_prefix: stripeCustomer!.invoice_prefix,
+          }),
+        });
+      }
+      return stripeCustomer;
+    }
   }
 
+  // 3. create new customer, let stripe generate invoice prefix
   const customer = await client.customers.create({
     name: internal.name,
     email: internal.email,
     phone: internal.phone,
-    invoice_prefix: internal.invoice_prefix,
     metadata: {
       appPid: env.appPid,
       id: internal.id,
@@ -135,7 +165,14 @@ export async function ensureStripeCustomer(internal: Customer, method: PaymentMe
     },
   });
 
-  await internal.update({ metadata: merge(internal.metadata || {}, { stripe_id: customer.id }) });
+  // 4. update local metadata
+  await internal.update({
+    metadata: merge(internal.metadata || {}, {
+      stripe_id: customer.id,
+      stripe_invoice_prefix: customer.invoice_prefix,
+    }),
+  });
+
   logger.info('customer created on stripe', { local: internal.id, remote: customer.id });
 
   return customer;
@@ -143,15 +180,20 @@ export async function ensureStripeCustomer(internal: Customer, method: PaymentMe
 
 export async function ensureStripePaymentCustomer(internal: any, method: PaymentMethod) {
   const client = method.getStripeClient();
-  let customer = null;
-  if (internal.payment_details?.stripe?.customer_id) {
-    customer = await client.customers.retrieve(internal.payment_details.stripe.customer_id);
-  } else {
-    const local = await Customer.findByPk(internal.customer_id);
-    customer = await ensureStripeCustomer(local as Customer, method);
+  const lock = getLock(`stripe-customer-${internal.customer_id}`);
+  await lock.acquire();
+  try {
+    let customer = null;
+    if (internal.payment_details?.stripe?.customer_id) {
+      customer = await client.customers.retrieve(internal.payment_details.stripe.customer_id);
+    } else {
+      const local = await Customer.findByPk(internal.customer_id);
+      customer = await ensureStripeCustomer(local as Customer, method);
+    }
+    return customer;
+  } finally {
+    lock.release();
   }
-
-  return customer;
 }
 
 export async function ensureStripePaymentIntent(

package/api/src/libs/auth.ts

@@ -10,6 +10,7 @@ import type { LiteralUnion } from 'type-fest';
 import type { WalletObject } from '@ocap/wallet';
 
 import env from './env';
+import logger from './logger';
 
 export const wallet: WalletObject = getWallet();
 export const ethWallet: WalletObject = getWallet('ethereum');
@@ -25,6 +26,19 @@ export const handlers = new WalletHandler({
 
 export const blocklet = new AuthService();
 
+export async function getVaultAddress() {
+  try {
+    const vault = await blocklet.getVault();
+    if (!vault) {
+      return null;
+    }
+    return vault;
+  } catch (error) {
+    logger.info('get vault wallet failed', { error });
+    return null;
+  }
+}
+
 export type CallbackArgs = {
   request: Request & { context: Record<string, any> };
   userDid: string;

package/api/src/libs/payment.ts

@@ -18,12 +18,14 @@ import {
   PaymentMethod,
   TCustomer,
   TLineItemExpanded,
+  Payout,
 } from '../store/models';
 import type { TPaymentCurrency } from '../store/models/payment-currency';
-import { blocklet, ethWallet, wallet } from './auth';
+import { blocklet, ethWallet, wallet, getVaultAddress } from './auth';
 import logger from './logger';
-import { getBlockletJson, getUserOrAppInfo, OCAP_PAYMENT_TX_TYPE } from './util';
+import { getBlockletJson, getUserOrAppInfo, OCAP_PAYMENT_TX_TYPE, resolveAddressChainTypes } from './util';
 import { CHARGE_SUPPORTED_CHAIN_TYPES, EVM_CHAIN_TYPES } from './constants';
+import { getTokenByAddress } from '../integrations/arcblock/stake';
 
 export interface SufficientForPaymentResult {
   sufficient: boolean;
@@ -390,3 +392,76 @@ export async function getDonationBenefits(paymentLink: PaymentLink, url?: string
   );
   return result;
 }
+
+/**
+ * 检查是否需要向冷钱包转账及可转账金额
+ * @param paymentCurrencyId
+ * @returns {Promise<{depositAmount: string, message?: string, vaultAddress?: string, paymentMethod?: PaymentMethod, paymentCurrency?: PaymentCurrency}>}
+ */
+export async function checkDepositVaultAmount(paymentCurrencyId: string): Promise<{
+  depositAmount: string;
+  message?: string;
+  vaultAddress?: string;
+  paymentCurrency?: PaymentCurrency;
+}> {
+  const paymentCurrency = await PaymentCurrency.scope('withVaultConfig').findByPk(paymentCurrencyId);
+  if (!paymentCurrency) {
+    return { depositAmount: '0', message: 'Payment currency not found' };
+  }
+
+  if (!paymentCurrency?.vault_config?.enabled) {
+    return { depositAmount: '0', message: 'Deposit vault is not enabled' };
+  }
+
+  const depositThreshold = paymentCurrency?.vault_config?.deposit_threshold;
+  if (!depositThreshold || depositThreshold === '0') {
+    return { depositAmount: '0', message: 'Deposit threshold is not set or zero' };
+  }
+
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+  if (!paymentMethod) {
+    return { depositAmount: '0', message: 'Payment method not found' };
+  }
+
+  const vaultAddress = await getVaultAddress();
+  if (!vaultAddress) {
+    return { depositAmount: '0', message: 'Vault address is not found' };
+  }
+
+  const vaultChainTypes = resolveAddressChainTypes(vaultAddress);
+  if (!vaultChainTypes.includes(paymentMethod.type)) {
+    return { depositAmount: '0', message: 'Vault chain type is not supported' };
+  }
+
+  const walletAddress = paymentMethod.type === 'arcblock' ? wallet.address : ethWallet.address;
+  const balance = await getTokenByAddress(walletAddress, paymentMethod, paymentCurrency);
+
+  const depositThresholdBN = new BN(depositThreshold);
+  if (new BN(balance).lte(depositThresholdBN)) {
+    return { depositAmount: '0', message: 'No enough balance to deposit to vault' };
+  }
+
+  const balanceBN = new BN(balance);
+  let amountToDeposit = balanceBN.sub(depositThresholdBN).toString();
+
+  const { [paymentCurrency.id]: lockedAmount } = await Payout.getPayoutLockedAmount({
+    currency_id: paymentCurrency.id,
+  });
+
+  // check if the amount to payout is already greater than the deposit threshold
+  if (new BN(lockedAmount).add(depositThresholdBN).gte(balanceBN)) {
+    return { depositAmount: '0', message: 'Amount to payout is already greater than the deposit threshold' };
+  }
+
+  amountToDeposit = new BN(amountToDeposit).sub(new BN(lockedAmount)).toString();
+
+  if (new BN(amountToDeposit).lte(new BN(0))) {
+    return { depositAmount: '0', message: 'No amount available to deposit after calculations' };
+  }
+
+  return {
+    depositAmount: amountToDeposit,
+    vaultAddress,
+    paymentCurrency,
+  };
+}

package/api/src/libs/util.ts

@@ -9,6 +9,7 @@ import type { LiteralUnion } from 'type-fest';
 import { joinURL, withQuery, withTrailingSlash } from 'ufo';
 
 import axios from 'axios';
+import { ethers } from 'ethers';
 import dayjs from './dayjs';
 import { blocklet, wallet } from './auth';
 import type { PaymentMethod, Subscription } from '../store/models';
@@ -508,3 +509,10 @@ export async function isUserInBlocklist(did: string, paymentMethod: PaymentMetho
     return false; // Default to allowing payment on error
   }
 }
+
+export function resolveAddressChainTypes(address: string): LiteralUnion<'ethereum' | 'base' | 'arcblock', string>[] {
+  if (ethers.isAddress(address)) {
+    return ['ethereum', 'base', 'arcblock'];
+  }
+  return ['arcblock'];
+}

package/api/src/queues/payment.ts

@@ -9,7 +9,7 @@ import dayjs from '../libs/dayjs';
 import CustomError from '../libs/error';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
-import { getGasPayerExtra, isDelegationSufficientForPayment } from '../libs/payment';
+import { getGasPayerExtra, isDelegationSufficientForPayment, checkDepositVaultAmount } from '../libs/payment';
 import {
   checkRemainingStake,
   getDaysUntilCancel,
@@ -47,6 +47,10 @@ type PaymentJob = {
   retryOnError?: boolean;
 };
 
+type DepositVaultJob = {
+  currencyId: string;
+};
+
 async function updateQuantitySold(checkoutSession: CheckoutSession) {
   const updatePromises = checkoutSession.line_items.map((item) => {
     const priceId = item.upsell_price_id || item.price_id;
@@ -62,6 +66,46 @@ async function updateQuantitySold(checkoutSession: CheckoutSession) {
   await Promise.all(updatePromises);
 }
 
+const handleDepositVault = async (paymentCurrencyId: string) => {
+  const { depositAmount, message, vaultAddress, paymentCurrency } = await checkDepositVaultAmount(paymentCurrencyId);
+  if (depositAmount === '0') {
+    logger.info(`Deposit vault skipped: ${message}`, { currencyId: paymentCurrencyId });
+    return;
+  }
+  const payout = await Payout.create({
+    livemode: paymentCurrency!.livemode,
+    automatic: true,
+    description: 'Deposit vault',
+    amount: depositAmount,
+    destination: vaultAddress!,
+    payment_method_id: paymentCurrency!.payment_method_id,
+    currency_id: paymentCurrency!.id,
+    customer_id: '',
+    payment_intent_id: '',
+    status: 'pending',
+    attempt_count: 0,
+    attempted: false,
+    next_attempt: 0,
+    last_attempt_error: null,
+    metadata: {
+      system: true,
+    },
+  });
+  logger.info('Deposit vault payout created', { payoutId: payout.id });
+};
+
+export const depositVaultQueue = createQueue<DepositVaultJob>({
+  name: 'deposit-vault',
+  onJob: async (job) => {
+    await handleDepositVault(job.currencyId);
+  },
+  options: {
+    concurrency: 1,
+    maxRetries: 3,
+    enableScheduledJob: true,
+  },
+});
+
 export const handlePaymentSucceed = async (
   paymentIntent: PaymentIntent,
   triggerRenew: boolean = true,
@@ -128,6 +172,11 @@ export const handlePaymentSucceed = async (
       );
   }
 
+  depositVaultQueue.push({
+    id: `deposit-vault-${paymentIntent.currency_id}`,
+    job: { currencyId: paymentIntent.currency_id },
+  });
+
   let invoice;
   if (paymentIntent.invoice_id) {
     invoice = await Invoice.findByPk(paymentIntent.invoice_id);

package/api/src/queues/payout.ts

@@ -0,0 +1,297 @@
+import dayjs from '../libs/dayjs';
+import { events } from '../libs/event';
+import logger from '../libs/logger';
+import { getGasPayerExtra } from '../libs/payment';
+import createQueue from '../libs/queue';
+import { wallet, ethWallet } from '../libs/auth';
+import { sendErc20ToUser } from '../integrations/ethereum/token';
+import { PaymentMethod } from '../store/models/payment-method';
+import { PaymentCurrency } from '../store/models/payment-currency';
+import { Payout } from '../store/models/payout';
+import { EVM_CHAIN_TYPES } from '../libs/constants';
+import type { PaymentError } from '../store/models/types';
+import { getNextRetry, MAX_RETRY_COUNT } from '../libs/util';
+
+type PayoutJob = {
+  payoutId: string;
+  retryOnError?: boolean;
+};
+
+type ValidationResult =
+  | { valid: false }
+  | { valid: true; payout: Payout; paymentMethod: PaymentMethod; paymentCurrency: PaymentCurrency };
+
+// Validate payout and fetch required data
+async function validatePayoutAndFetchData(job: PayoutJob): Promise<ValidationResult> {
+  const payout = await Payout.findByPk(job.payoutId);
+  if (!payout) {
+    logger.warn('Payout not found', { id: job.payoutId });
+    return { valid: false };
+  }
+
+  if (payout.status !== 'pending') {
+    logger.warn('Payout status not expected', { id: payout.id, status: payout.status });
+    return { valid: false };
+  }
+
+  const paymentMethod = await PaymentMethod.findByPk(payout.payment_method_id);
+  if (!paymentMethod) {
+    logger.warn('PaymentMethod not found', { id: payout.payment_method_id });
+    return { valid: false };
+  }
+
+  const paymentCurrency = await PaymentCurrency.findByPk(payout.currency_id);
+  if (!paymentCurrency) {
+    logger.warn('PaymentCurrency not found', { id: payout.currency_id });
+    return { valid: false };
+  }
+
+  return {
+    valid: true,
+    payout,
+    paymentMethod,
+    paymentCurrency,
+  };
+}
+
+// Process Arcblock chain payout
+async function processArcblockPayout(payout: Payout, paymentMethod: PaymentMethod, paymentCurrency: PaymentCurrency) {
+  const client = paymentMethod.getOcapClient();
+
+  const signed = await client.signTransferV2Tx({
+    tx: {
+      itx: {
+        to: payout.destination,
+        value: '0',
+        assets: [],
+        tokens: [{ address: paymentCurrency.contract, value: payout.amount }],
+        data: {
+          typeUrl: 'json',
+          // @ts-ignore Type issue, won't affect server runtime
+          value: {
+            appId: wallet.address,
+            reason: 'payout',
+            payoutId: payout.id,
+          },
+        },
+      },
+    },
+    wallet,
+  });
+  // @ts-ignore
+  const { buffer } = await client.encodeTransferV2Tx({ tx: signed });
+  // @ts-ignore
+  const txHash = await client.sendTransferV2Tx({ tx: signed, wallet }, getGasPayerExtra(buffer));
+
+  logger.info('Payout completed', { id: payout.id, txHash });
+
+  await payout.update({
+    status: 'paid',
+    last_attempt_error: null,
+    attempt_count: payout.attempt_count + 1,
+    attempted: true,
+    payment_details: {
+      arcblock: {
+        tx_hash: txHash,
+        payer: wallet.address,
+        type: 'transfer',
+      },
+    },
+  });
+}
+
+// Process EVM chain payout
+async function processEvmPayout(payout: Payout, paymentMethod: PaymentMethod, paymentCurrency: PaymentCurrency) {
+  if (!paymentCurrency.contract) {
+    throw new Error('Payout not supported for ethereum payment currencies without contract');
+  }
+
+  const client = paymentMethod.getEvmClient();
+  const paymentType = paymentMethod.type;
+
+  // Send ERC20 tokens from system wallet to user address
+  const receipt = await sendErc20ToUser(client, paymentCurrency.contract, payout.destination, payout.amount);
+
+  logger.info('Payout completed', { id: payout.id, txHash: receipt.hash });
+
+  await payout.update({
+    status: 'paid',
+    last_attempt_error: null,
+    attempt_count: payout.attempt_count + 1,
+    attempted: true,
+    payment_details: {
+      [paymentType]: {
+        tx_hash: receipt.hash,
+        payer: ethWallet.address,
+        block_height: receipt.blockNumber.toString(),
+        gas_used: receipt.gasUsed.toString(),
+        gas_price: receipt.gasPrice.toString(),
+        type: 'transfer',
+      },
+    },
+  });
+}
+
+// Handle payout failure with retry logic
+async function handlePayoutFailure(payout: Payout, paymentMethod: PaymentMethod, error: any, retryOnError: boolean) {
+  const paymentError: PaymentError = {
+    type: 'card_error',
+    code: error.code,
+    message: error.message,
+    payment_method_id: paymentMethod.id,
+    payment_method_type: paymentMethod.type,
+  };
+
+  if (!retryOnError) {
+    // Mark as failed without retry
+    await payout.update({
+      status: 'failed',
+      last_attempt_error: paymentError,
+      attempt_count: payout.attempt_count + 1,
+      attempted: true,
+      failure_message: error.message,
+    });
+    return;
+  }
+
+  const attemptCount = payout.attempt_count + 1;
+
+  if (attemptCount >= MAX_RETRY_COUNT) {
+    // Exceeded max retry count
+    await payout.update({
+      status: 'failed',
+      last_attempt_error: paymentError,
+      attempt_count: attemptCount,
+      attempted: true,
+      failure_message: error.message,
+    });
+    logger.info('Payout job deleted since max retry exceeded', { id: payout.id });
+    payoutQueue.delete(payout.id);
+    return;
+  }
+
+  const nextAttempt = getNextRetry(attemptCount);
+  await payout.update({
+    status: 'pending',
+    last_attempt_error: paymentError,
+    attempt_count: attemptCount,
+    attempted: true,
+    next_attempt: nextAttempt,
+  });
+
+  payoutQueue.push({
+    id: payout.id,
+    job: { payoutId: payout.id, retryOnError: true },
+    runAt: nextAttempt,
+  });
+
+  logger.error('Payout retry scheduled', { id: payout.id, nextAttempt, retryCount: attemptCount });
+}
+
+// Process payout transaction
+export const handlePayout = async (job: PayoutJob) => {
+  logger.info('handle payout', job);
+
+  const result = await validatePayoutAndFetchData(job);
+  if (!result.valid) {
+    return;
+  }
+
+  const { payout, paymentMethod, paymentCurrency } = result;
+
+  logger.info('Payout attempt', { id: payout.id, attempt: payout.attempt_count });
+  try {
+    await payout.update({ status: 'in_transit', last_attempt_error: null });
+    logger.info('Payout status updated to in_transit', { payoutId: payout.id });
+
+    if (paymentMethod.type === 'arcblock') {
+      await processArcblockPayout(payout, paymentMethod, paymentCurrency);
+    } else if (EVM_CHAIN_TYPES.includes(paymentMethod.type)) {
+      await processEvmPayout(payout, paymentMethod, paymentCurrency);
+    }
+  } catch (err) {
+    logger.error('Payout failed', { error: err, id: payout.id });
+    await handlePayoutFailure(payout, paymentMethod, err, !!job.retryOnError);
+  }
+};
+
+// Create queue processor
+export const payoutQueue = createQueue<PayoutJob>({
+  name: 'payout',
+  onJob: handlePayout,
+  options: {
+    concurrency: 1,
+    maxRetries: 0,
+    enableScheduledJob: true,
+  },
+});
+
+// Handle queue failure events
+payoutQueue.on('failed', ({ id, job, error }) => {
+  logger.error('Payout job failed', { id, job, error });
+});
+
+// Start queue, find all payouts with "pending" status
+export const startPayoutQueue = async () => {
+  const payouts = await Payout.findAll({
+    where: {
+      status: 'pending',
+    },
+  });
+
+  payouts.forEach(async (payout) => {
+    const exist = await payoutQueue.get(payout.id);
+    if (!exist) {
+      // Use next attempt time if set
+      if (payout.next_attempt && payout.next_attempt > dayjs().unix()) {
+        payoutQueue.push({
+          id: payout.id,
+          job: { payoutId: payout.id, retryOnError: true },
+          runAt: payout.next_attempt,
+        });
+      } else {
+        payoutQueue.push({
+          id: payout.id,
+          job: { payoutId: payout.id, retryOnError: true },
+        });
+      }
+    }
+  });
+};
+
+// Listen for newly created payouts
+events.on('payout.created', async (payout: Payout) => {
+  if (payout.status === 'pending') {
+    const exist = await payoutQueue.get(payout.id);
+    if (!exist) {
+      payoutQueue.push({
+        id: payout.id,
+        job: { payoutId: payout.id, retryOnError: true },
+      });
+    }
+  }
+});
+
+// Add synchronous payout processing event
+events.on('payout.queued', async (id, job, args = {}) => {
+  const { sync, ...extraArgs } = args;
+  if (sync) {
+    try {
+      await payoutQueue.pushAndWait({
+        id,
+        job,
+        ...extraArgs,
+      });
+      events.emit('payout.queued.done');
+    } catch (error) {
+      logger.error('Error in payout.queued', { id, job, error });
+      events.emit('payout.queued.error', error);
+    }
+    return;
+  }
+  payoutQueue.push({
+    id,
+    job,
+    ...extraArgs,
+  });
+});

package/api/src/routes/checkout-sessions.ts

@@ -17,11 +17,7 @@ import { MetadataSchema } from '../libs/api';
 import { checkPassportForPaymentLink } from '../integrations/blocklet/passport';
 import { handleStripePaymentSucceed } from '../integrations/stripe/handlers/payment-intent';
 import { handleStripeSubscriptionSucceed } from '../integrations/stripe/handlers/subscription';
-import {
-  ensureStripePaymentCustomer,
-  ensureStripePaymentIntent,
-  ensureStripeSubscription,
-} from '../integrations/stripe/resource';
+import { ensureStripePaymentIntent, ensureStripeSubscription } from '../integrations/stripe/resource';
 import dayjs from '../libs/dayjs';
 import logger from '../libs/logger';
 import { isCreditSufficientForPayment, isDelegationSufficientForPayment } from '../libs/payment';
@@ -1048,12 +1044,11 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
           trialInDays,
           trialEnd
         );
-        const stripeCustomer = await ensureStripePaymentCustomer(subscription, paymentMethod);
         if (stripeSubscription) {
           await subscription.update({
             payment_details: {
               stripe: {
-                customer_id: stripeCustomer.id,
+                customer_id: stripeSubscription.customer,
                 subscription_id: stripeSubscription.id,
                 setup_intent_id: stripeSubscription.pending_setup_intent?.id,
               },