payment-kit 1.22.32 → 1.23.1

package/api/src/routes/index.ts

@@ -5,6 +5,7 @@ import autoRechargeConfigs from './auto-recharge-configs';
 import checkoutSessions from './checkout-sessions';
 import coupons from './coupons';
 import creditGrants from './credit-grants';
+import creditTokens from './credit-tokens';
 import creditTransactions from './credit-transactions';
 import customers from './customers';
 import donations from './donations';
@@ -61,6 +62,7 @@ router.use('/auto-recharge-configs', autoRechargeConfigs);
 router.use('/checkout-sessions', checkoutSessions);
 router.use('/coupons', coupons);
 router.use('/credit-grants', creditGrants);
+router.use('/credit-tokens', creditTokens);
 router.use('/credit-transactions', creditTransactions);
 router.use('/customers', customers);
 router.use('/donations', donations);

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

@@ -335,7 +335,11 @@ router.get('/pending-amount', authMine, async (req, res) => {
       }
       params.customerId = customer.id;
     }
+    // eslint-disable-next-line no-console
+    console.time('pending-amount: getPendingAmounts');
     const [summary] = await MeterEvent.getPendingAmounts(params);
+    // eslint-disable-next-line no-console
+    console.timeEnd('pending-amount: getPendingAmounts');
     return res.json(summary);
   } catch (err) {
     logger.error('Error getting meter event pending amount', err);

package/api/src/routes/meters.ts

@@ -18,9 +18,13 @@ const meterSchema = Joi.object({
   aggregation_method: Joi.string().valid('sum', 'count', 'last').default('sum'),
   unit: Joi.string().max(32).required(),
   currency_id: Joi.string().max(40).optional(),
+  decimal: Joi.number().integer().min(2).max(18).default(10),
   description: Joi.string().max(255).allow('').optional(),
   metadata: MetadataSchema,
   component_did: Joi.string().max(40).optional(),
+  token: Joi.object({
+    tokenFactoryAddress: Joi.string().required(),
+  }).optional(),
 }).unknown(true);
 
 const updateMeterSchema = Joi.object({
@@ -78,6 +82,32 @@ router.post('/', auth, async (req, res) => {
       return res.status(400).json({ error: 'Aggregation method is not supported' });
     }
 
+    const needArcblockMethod = req.body.token?.tokenFactoryAddress || !req.body.currency_id;
+    const arcblockMethod = needArcblockMethod
+      ? await PaymentMethod.findOne({ where: { livemode: !!req.livemode, type: 'arcblock' } })
+      : null;
+    if (needArcblockMethod && !arcblockMethod) {
+      throw new Error('ArcBlock payment method not found');
+    }
+
+    let tokenConfig: Record<string, any> | undefined;
+    if (req.body.token?.tokenFactoryAddress) {
+      const client = arcblockMethod!.getOcapClient();
+      const { state: tokenFactoryState } = await client.getTokenFactoryState({
+        address: req.body.token.tokenFactoryAddress,
+      });
+      if (!tokenFactoryState) {
+        return res.status(400).json({ error: 'Token factory not found on chain' });
+      }
+      tokenConfig = {
+        address: tokenFactoryState.token.address,
+        symbol: tokenFactoryState.token.symbol,
+        name: tokenFactoryState.token.name,
+        decimal: tokenFactoryState.token.decimal,
+        token_factory_address: tokenFactoryState.address,
+      };
+    }
+
     const meterData = {
       ...pick(req.body, ['name', 'event_name', 'aggregation_method', 'unit', 'currency_id', 'description', 'metadata']),
       livemode: !!req.livemode,
@@ -87,17 +117,9 @@ router.post('/', auth, async (req, res) => {
     };
 
     if (!meterData.currency_id) {
-      const paymentMethod = await PaymentMethod.findOne({
-        where: {
-          livemode: !!req.livemode,
-          type: 'arcblock',
-        },
+      const paymentCurrency = await PaymentCurrency.createForMeter(meterData, arcblockMethod!.id, tokenConfig, {
+        decimal: req.body.decimal,
       });
-      if (!paymentMethod) {
-        return res.status(400).json({ error: 'Payment method not found' });
-      }
-
-      const paymentCurrency = await PaymentCurrency.createForMeter(meterData, paymentMethod.id);
       meterData.currency_id = paymentCurrency.id;
     }
 

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

@@ -351,6 +351,109 @@ router.put('/:id', auth, async (req, res) => {
   return res.json(updatedCurrency);
 });
 
+const tokenConfigSchema = Joi.object({
+  token_factory_address: Joi.string().required(),
+});
+
+router.put('/:id/token-config', auth, async (req, res) => {
+  try {
+    const { id } = req.params;
+
+    const { error, value } = tokenConfigSchema.validate(req.body);
+    if (error) {
+      return res.status(400).json({ error: error.message });
+    }
+
+    const currency = await PaymentCurrency.findByPk(id);
+    if (!currency) {
+      return res.status(404).json({ error: 'Payment currency not found' });
+    }
+
+    if (currency.type !== 'credit') {
+      return res.status(400).json({ error: 'Only credit currencies can have token_config' });
+    }
+
+    if (currency.token_config) {
+      return res.status(400).json({ error: 'Token config already exists. Cannot be updated once set.' });
+    }
+
+    const paymentMethod = await PaymentMethod.findOne({
+      where: {
+        livemode: currency.livemode,
+        type: 'arcblock',
+      },
+    });
+
+    if (!paymentMethod) {
+      return res.status(400).json({ error: 'ArcBlock payment method not found' });
+    }
+
+    const client = paymentMethod.getOcapClient();
+    const { state: tokenFactoryState } = await client.getTokenFactoryState({
+      address: value.token_factory_address,
+    });
+
+    if (!tokenFactoryState) {
+      return res.status(400).json({ error: 'Token factory not found on chain' });
+    }
+
+    const tokenConfig = {
+      address: tokenFactoryState.token.address,
+      symbol: tokenFactoryState.token.symbol,
+      name: tokenFactoryState.token.name,
+      decimal: tokenFactoryState.token.decimal,
+      token_factory_address: tokenFactoryState.address,
+    };
+
+    // Only update token_config, keep the original decimal to avoid breaking existing credit grants
+    await currency.update({
+      token_config: tokenConfig,
+    });
+
+    logger.info('Payment currency token_config updated', {
+      currencyId: id,
+      tokenConfig,
+    });
+
+    return res.json(currency.toJSON());
+  } catch (err) {
+    logger.error('update payment currency token_config failed', { error: err?.message, id: req.params.id });
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+router.delete('/:id/token-config', auth, async (req, res) => {
+  try {
+    const { id } = req.params;
+
+    const currency = await PaymentCurrency.findByPk(id);
+    if (!currency) {
+      return res.status(404).json({ error: 'Payment currency not found' });
+    }
+
+    if (currency.type !== 'credit') {
+      return res.status(400).json({ error: 'Only credit currencies can have token_config' });
+    }
+
+    if (!currency.token_config) {
+      return res.status(400).json({ error: 'Token config does not exist' });
+    }
+
+    await currency.update({
+      token_config: null,
+    });
+
+    logger.info('Payment currency token_config removed', {
+      currencyId: id,
+    });
+
+    return res.json(currency.toJSON());
+  } catch (err) {
+    logger.error('delete payment currency token_config failed', { error: err?.message, id: req.params.id });
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
 router.delete('/:id', auth, async (req, res) => {
   const { id } = req.params;
 

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

@@ -260,10 +260,12 @@ router.get('/', auth, async (req, res) => {
     const priceIds: string[] = list.reduce((acc: string[], x) => acc.concat(x.line_items.map((i) => i.price_id)), []);
     const prices = await Price.findAll({ where: { id: priceIds }, include: [{ model: Product, as: 'product' }] });
 
+    const priceMap = new Map(prices.map((p) => [p.id, p]));
+
     list.forEach((x) => {
       x.line_items.forEach((i) => {
         // @ts-ignore
-        i.price = prices.find((p) => p.id === i.price_id);
+        i.price = priceMap.get(i.price_id);
       });
     });
 

package/api/src/routes/products.ts

@@ -37,7 +37,7 @@ const ProductAndPriceSchema = Joi.object({
   description: Joi.string().max(250).empty('').optional(),
   images: Joi.any().optional(),
   metadata: MetadataSchema,
-  tax_code: Joi.string().max(30).empty('').optional(),
+  tax_code: Joi.string().max(30).allow(null).empty('').optional(),
   statement_descriptor: Joi.string()
     .max(22)
     .pattern(/^(?=.*[A-Za-z])[^\u4e00-\u9fa5<>"’\\]*$/)
@@ -48,7 +48,7 @@ const ProductAndPriceSchema = Joi.object({
     .allow(null, '')
     .empty('')
     .optional(),
-  unit_label: Joi.string().max(12).empty('').optional(),
+  unit_label: Joi.string().max(12).allow(null).empty('').optional(),
   nft_factory: Joi.string().max(40).allow(null).empty('').optional(),
   features: Joi.array()
     .items(Joi.object({ name: Joi.string().max(64).empty('').optional() }).unknown(true))

package/api/src/routes/settings.ts

@@ -31,9 +31,10 @@ router.get('/', async (req, res) => {
   });
 
   res.json({
-    paymentMethods: methods.map((x) =>
-      pick(x, ['id', 'name', 'type', 'logo', 'payment_currencies', 'default_currency_id', 'maximum_precision'])
-    ),
+    paymentMethods: methods.map((x) => ({
+      ...pick(x, ['id', 'name', 'type', 'logo', 'payment_currencies', 'default_currency_id', 'maximum_precision']),
+      api_host: x.settings?.arcblock?.api_host,
+    })),
     baseCurrency: await PaymentCurrency.findOne({
       where: { is_base_currency: true, livemode: req.livemode },
       attributes,

package/api/src/store/migrations/20251120-add-token-config-to-currencies.ts

@@ -0,0 +1,20 @@
+import { DataTypes } from 'sequelize';
+import { safeApplyColumnChanges, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  await safeApplyColumnChanges(context, {
+    payment_currencies: [
+      {
+        name: 'token_config',
+        field: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('payment_currencies', 'token_config');
+};

package/api/src/store/migrations/20251204-add-chain-fields.ts

@@ -0,0 +1,74 @@
+import { DataTypes } from 'sequelize';
+import { createIndexIfNotExists, safeApplyColumnChanges, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  // Add new columns to credit_transactions table
+  await safeApplyColumnChanges(context, {
+    credit_transactions: [
+      {
+        name: 'transfer_status',
+        field: {
+          type: DataTypes.ENUM('pending', 'completed', 'failed'),
+          allowNull: true,
+        },
+      },
+      {
+        name: 'transfer_hash',
+        field: {
+          type: DataTypes.STRING(255),
+          allowNull: true,
+        },
+      },
+    ],
+  });
+
+  // Add new columns to credit_grants table for on-chain operations
+  await safeApplyColumnChanges(context, {
+    credit_grants: [
+      {
+        name: 'chain_status',
+        field: {
+          type: DataTypes.ENUM(
+            'mint_pending',
+            'mint_completed',
+            'mint_failed',
+            'burn_pending',
+            'burn_completed',
+            'burn_failed'
+          ),
+          allowNull: true,
+        },
+      },
+      {
+        name: 'chain_detail',
+        field: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+      },
+    ],
+  });
+
+  // Add indexes for efficient querying
+  await createIndexIfNotExists(
+    context,
+    'credit_transactions',
+    ['transfer_status'],
+    'idx_credit_transactions_transfer_status'
+  );
+  await createIndexIfNotExists(context, 'credit_grants', ['chain_status'], 'idx_credit_grants_chain_status');
+};
+
+export const down: Migration = async ({ context }) => {
+  // Remove indexes
+  await context.removeIndex('credit_transactions', 'idx_credit_transactions_transfer_status');
+  await context.removeIndex('credit_grants', 'idx_credit_grants_chain_status');
+
+  // Remove columns from credit_transactions
+  await context.removeColumn('credit_transactions', 'transfer_hash');
+  await context.removeColumn('credit_transactions', 'transfer_status');
+
+  // Remove columns from credit_grants
+  await context.removeColumn('credit_grants', 'chain_detail');
+  await context.removeColumn('credit_grants', 'chain_status');
+};

package/api/src/store/migrations/20251211-optimize-slow-queries.ts

@@ -0,0 +1,33 @@
+/* eslint-disable no-console */
+import { createIndexIfNotExists, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  await createIndexIfNotExists(
+    context,
+    'meter_events',
+    ['livemode', 'event_name', 'timestamp'],
+    'idx_meter_events_livemode_event_timestamp'
+  );
+
+  await createIndexIfNotExists(
+    context,
+    'payment_currencies',
+    ['is_base_currency', 'livemode'],
+    'idx_payment_currencies_base_livemode'
+  );
+
+  await createIndexIfNotExists(context, 'jobs', ['queue', 'id'], 'idx_jobs_queue_id');
+  await createIndexIfNotExists(
+    context,
+    'jobs',
+    ['queue', 'cancelled', 'will_run_at', 'delay'],
+    'idx_jobs_queue_cancelled_run_at_delay'
+  );
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeIndex('meter_events', 'idx_meter_events_livemode_event_timestamp');
+  await context.removeIndex('payment_currencies', 'idx_payment_currencies_base_livemode');
+  await context.removeIndex('jobs', 'idx_jobs_queue_id');
+  await context.removeIndex('jobs', 'idx_jobs_queue_cancelled_run_at_delay');
+};

package/api/src/store/models/credit-grant.ts

@@ -6,9 +6,10 @@ import type { LiteralUnion } from 'type-fest';
 import { createEvent } from '../../libs/audit';
 import { createIdGenerator } from '../../libs/util';
 import dayjs from '../../libs/dayjs';
-import { CreditGrantApplicabilityConfig } from './types';
+import { CreditGrantApplicabilityConfig, CreditGrantChainDetail, CreditGrantChainStatus } from './types';
 import logger from '../../libs/logger';
 import { PaymentCurrency, TPaymentCurrency } from './payment-currency';
+import { Meter, TMeter } from './meter';
 
 const CREDIT_GRANT_STATUS_EVENTS = {
   depleted: 'depleted',
@@ -18,6 +19,7 @@ const CREDIT_GRANT_STATUS_EVENTS = {
 
 type CreditGrantSummary = {
   paymentCurrency: TPaymentCurrency;
+  meter?: TMeter;
   totalAmount: string;
   remainingAmount: string;
   grantCount: number;
@@ -62,6 +64,10 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
   declare status: LiteralUnion<'pending' | 'granted' | 'depleted' | 'expired' | 'voided', string>;
   declare remaining_amount: string; // 剩余金额
 
+  // On-chain credit token operation fields
+  declare chain_status?: CreditGrantChainStatus;
+  declare chain_detail?: CreditGrantChainDetail;
+
   // 审计字段
   declare created_by?: string;
   declare updated_by?: string;
@@ -148,6 +154,21 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
       type: DataTypes.STRING(32),
       allowNull: false,
     },
+    chain_status: {
+      type: DataTypes.ENUM(
+        'mint_pending',
+        'mint_completed',
+        'mint_failed',
+        'burn_pending',
+        'burn_completed',
+        'burn_failed'
+      ),
+      allowNull: true,
+    },
+    chain_detail: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
     created_by: {
       type: DataTypes.STRING(40),
       allowNull: true,
@@ -267,6 +288,16 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
     return true;
   }
 
+  // check if Credit Grant has on-chain token (mint completed)
+  public hasOnchainToken(): boolean {
+    return CreditGrant.hasOnchainToken(this);
+  }
+
+  // Static version that works with plain objects
+  public static hasOnchainToken(grant: { chain_status?: string | null }): boolean {
+    return grant.chain_status === 'mint_completed';
+  }
+
   public static initialize(sequelize: any) {
     this.init(this.GENESIS_ATTRIBUTES, {
       sequelize,
@@ -282,9 +313,6 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
       hooks: {
         afterCreate: (model: CreditGrant, options) => {
           createEvent('CreditGrant', 'customer.credit_grant.created', model, options).catch(console.error);
-          if (!model.effective_at || model.effective_at <= Math.floor(Date.now() / 1000)) {
-            createEvent('CreditGrant', 'customer.credit_grant.granted', model, options).catch(console.error);
-          }
         },
         afterUpdate: (model: CreditGrant, options) => {
           createEvent('CreditGrant', 'customer.credit_grant.updated', model, options).catch(console.error);
@@ -404,10 +432,7 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
     currencyId?: string[] | string;
     priceIds?: string[];
   }): Promise<Record<string, CreditGrantSummary>> {
-    const summary: Record<
-      string,
-      { paymentCurrency: TPaymentCurrency; totalAmount: string; remainingAmount: string; grantCount: number }
-    > = {};
+    const summary: Record<string, CreditGrantSummary> = {};
 
     let targetCurrencyIds: string[] = [];
     if (searchCurrencyId) {
@@ -436,6 +461,16 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
     });
     const currencyMap = new Map(currencies.map((c) => [c.id, c]));
 
+    // Query meters for credit currencies
+    const meters = await Meter.findAll({
+      where: {
+        currency_id: {
+          [Op.in]: Array.from(new Set(targetCurrencyIds)),
+        },
+      },
+    });
+    const meterMap = new Map(meters.map((m) => [m.currency_id, m]));
+
     await Promise.all(
       targetCurrencyIds.map(async (currencyId: string) => {
         const paymentCurrency = currencyMap.get(currencyId);
@@ -446,6 +481,7 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
           return null;
         }
 
+        const meter = meterMap.get(currencyId);
         const availableGrants = await this.getAvailableCreditsForCustomer(customerId, currencyId, priceIds);
 
         if (availableGrants.length > 0) {
@@ -459,8 +495,9 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
             grantCount += 1;
           });
 
-          const result = {
+          const result: CreditGrantSummary = {
             paymentCurrency,
+            meter,
             totalAmount,
             remainingAmount,
             grantCount,
@@ -471,6 +508,7 @@ export class CreditGrant extends Model<InferAttributes<CreditGrant>, InferCreati
         }
         summary[currencyId] = {
           paymentCurrency,
+          meter,
           totalAmount: '0',
           remainingAmount: '0',
           grantCount: 0,

package/api/src/store/models/credit-transaction.ts

@@ -29,6 +29,10 @@ export class CreditTransaction extends Model<
   declare description?: string;
   declare metadata?: Record<string, any>;
 
+  // Token transfer fields
+  declare transfer_status?: 'pending' | 'completed' | 'failed' | null;
+  declare transfer_hash?: string;
+
   declare created_at: CreationOptional<Date>;
   declare updated_at: CreationOptional<Date>;
 
@@ -88,6 +92,14 @@ export class CreditTransaction extends Model<
       type: DataTypes.JSON,
       allowNull: true,
     },
+    transfer_status: {
+      type: DataTypes.ENUM('pending', 'completed', 'failed'),
+      allowNull: true,
+    },
+    transfer_hash: {
+      type: DataTypes.STRING(255),
+      allowNull: true,
+    },
     created_at: {
       type: DataTypes.DATE,
       defaultValue: DataTypes.NOW,
@@ -107,7 +119,12 @@ export class CreditTransaction extends Model<
       tableName: 'credit_transactions',
       createdAt: 'created_at',
       updatedAt: 'updated_at',
-      indexes: [{ fields: ['customer_id'] }, { fields: ['credit_grant_id'] }, { fields: ['source'] }],
+      indexes: [
+        { fields: ['customer_id'] },
+        { fields: ['credit_grant_id'] },
+        { fields: ['source'] },
+        { fields: ['transfer_status'] },
+      ],
       hooks: {
         afterCreate: (model: CreditTransaction, options) =>
           createEvent('CreditTransaction', 'customer.credit_transaction.created', model, options).catch(console.error),

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

@@ -305,9 +305,10 @@ export type TCreditTransactionExpanded = TCreditTransaction & {
   customer: TCustomer;
   paymentCurrency: TPaymentCurrency;
   paymentMethod?: TPaymentMethod;
-  creditGrant: TCreditGrant;
+  creditGrant: TCreditGrant & { paymentCurrency?: TPaymentCurrency };
   meter: TMeter;
   subscription: TSubscription;
+  meterEvent?: TMeterEvent;
 };
 
 export type TMeterEventExpanded = TMeterEvent & {

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

@@ -46,6 +46,7 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
   declare vault_config?: VaultConfig;
   declare type: LiteralUnion<'standard' | 'credit', string>;
   declare recharge_config?: RechargeConfig;
+  declare token_config?: Record<string, any> | null;
 
   public static readonly GENESIS_ATTRIBUTES = {
     id: {
@@ -144,6 +145,10 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
           type: DataTypes.JSON,
           allowNull: true,
         },
+        token_config: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
       },
       {
         sequelize,
@@ -210,7 +215,12 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
     );
     return count > 0;
   }
-  public static async createForMeter(meter: any, paymentMethodId: string) {
+  public static async createForMeter(
+    meter: any,
+    paymentMethodId: string,
+    tokenConfig?: Record<string, any>,
+    options?: { decimal?: number }
+  ) {
     const existingCurrency = await this.findOne({
       where: {
         type: 'credit',
@@ -222,6 +232,8 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
     if (existingCurrency) {
       return existingCurrency;
     }
+
+    const decimal = options?.decimal ?? 10;
     const currency = await this.create({
       type: 'credit',
       payment_method_id: paymentMethodId,
@@ -229,8 +241,8 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
       description: `Credit for ${meter.unit}`,
       symbol: meter.unit,
       logo: getUrl('/methods/arcblock.png'), // 默认credit图标
-      decimal: 2,
-      maximum_precision: 2,
+      decimal,
+      maximum_precision: decimal,
       minimum_payment_amount: '1',
       maximum_payment_amount: '100000000000',
       active: true,
@@ -242,13 +254,28 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
         meter_event_name: meter.event_name,
         created_by_meter: true,
       },
+      token_config: tokenConfig,
     });
 
     return currency;
   }
 
   public isCredit(): boolean {
-    return this.type === 'credit';
+    return PaymentCurrency.isCredit(this);
+  }
+
+  public isOnChainCredit(): boolean {
+    return PaymentCurrency.isOnChainCredit(this);
+  }
+
+  // Static version that works with plain objects
+  public static isCredit(currency: { type?: string | null }): boolean {
+    return currency.type === 'credit';
+  }
+
+  // Static version that works with plain objects
+  public static isOnChainCredit(currency: { type?: string | null; token_config?: any }): boolean {
+    return PaymentCurrency.isCredit(currency) && !!currency.token_config;
   }
 }
 

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

@@ -32,7 +32,11 @@ export class Refund extends Model<InferAttributes<Refund>, InferCreationAttribut
 
   declare metadata?: Record<string, any>;
 
-  declare status: LiteralUnion<'pending' | 'requires_action' | 'failed' | 'canceled' | 'succeeded', string>;
+  // processing: refund transfer succeeded, waiting for credit burn (for onchain credit only)
+  declare status: LiteralUnion<
+    'pending' | 'requires_action' | 'processing' | 'failed' | 'canceled' | 'succeeded',
+    string
+  >;
   declare reason?: LiteralUnion<
     'duplicate' | 'requested_by_customer' | 'requested_by_admin' | 'fraudulent' | 'expired_uncaptured_charge',
     string
@@ -199,7 +203,13 @@ export class Refund extends Model<InferAttributes<Refund>, InferCreationAttribut
           afterCreate: (model: Refund, options) =>
             createEvent('Refund', 'refund.created', model, options).catch(console.error),
           afterUpdate: (model: Refund, options) =>
-            createStatusEvent('Refund', 'refund', { canceled: 'canceled', succeeded: 'succeeded' }, model, options),
+            createStatusEvent(
+              'Refund',
+              'refund',
+              { canceled: 'canceled', processing: 'processing', succeeded: 'succeeded' },
+              model,
+              options
+            ),
           afterDestroy: (model: Refund, options) =>
             createEvent('Refund', 'refund.deleted', model, options).catch(console.error),
         },