WordPress多站点Stripe自定义关联账户待处理余额转账问题求助

问题根源 #

你当前的代码是在订单付款完成后事后转账，但Stripe收到的资金会进入「待处理余额」（通常因账户风控、首次收款或支付方式清算周期导致），此时余额不可用，直接触发转账必然失败。

最佳实践是在付款时直接拆分资金，彻底避免事后转账的问题；如果必须处理待处理余额，也可通过Webhook或特殊参数实现转账。

方案1：付款时直接拆分资金（推荐） #

利用WooCommerce Stripe Gateway的钩子，在创建Stripe Payment Intent时直接指定资金拆分规则，让付款金额实时分配到主账户和商家关联账户，无需事后二次转账。

代码实现 #

// 修改Stripe支付意图参数，付款阶段直接拆分资金
add_filter('wc_stripe_payment_intent_params', 'custom_stripe_split_payment_at_checkout', 10, 3);

function custom_stripe_split_payment_at_checkout($params, $order, $source) {
    // 仅针对Stripe支付处理
    if ($order->get_payment_method() !== 'stripe') {
        return $params;
    }

    // 获取当前站点的商家关联账户ID与佣金比例
    $blog_id = get_current_blog_id();
    $connected_account_id = get_site_option('vendor_stripe_id_' . $blog_id);
    if (!$connected_account_id) {
        return $params;
    }

    $commission_percentage = get_site_option('vendor_commission_percentage_' . $blog_id, 10); // 默认10%佣金比例
    $order_total = $order->get_total();
    $vendor_amount = $order_total * ((100 - $commission_percentage) / 100); // 商家实际所得金额

    // 转换为Stripe要求的分单位
    $vendor_amount_cents = intval($vendor_amount * 100);

    // 设置资金拆分规则：直接将商家所得打入其关联账户
    $params['transfer_data'] = [
        'destination' => $connected_account_id,
        'amount' => $vendor_amount_cents,
    ];

    // 若需主账户以应用费用形式收取佣金，可启用以下代码（需Stripe账户模式支持）
    // $commission_amount_cents = intval($order_total * ($commission_percentage / 100) * 100);
    // $params['application_fee_amount'] = $commission_amount_cents;

    return $params;
}

说明 #

• 此方法跳过事后转账环节，付款完成后资金直接分配到对应账户，彻底规避待处理余额问题。
• 需确保你的Stripe账户已启用Connect功能，且关联账户为Standard/Express类型。

方案2：处理待处理余额的事后转账 #

若必须保留事后转账逻辑，可通过以下两种方式解决待处理余额无法转账的问题：

方法A：允许从待处理余额扣款 #

在创建转账时添加source_type参数，明确指定从待处理余额中扣款：

// 修改原代码中的转账参数数组
$array = [
    'amount' => $commission_amount * 100,  // 单位：分
    'currency' => 'usd',
    'destination' => $connected_account_id,
    'source_type' => 'pending', // 允许从待处理余额转账
];

方法B：监听Stripe Webhook，资金可用时自动转账 #

1. 在Stripe后台启用balance.available或payment_intent.succeeded Webhook事件；
2. 在WordPress中添加Webhook处理函数，当Stripe通知资金变为可用时执行转账：

// 处理Stripe余额可用事件的Webhook
add_action('woocommerce_api_stripe_webhook', 'custom_stripe_webhook_handle_balance');

function custom_stripe_webhook_handle_balance() {
    $payload = file_get_contents('php://input');
    $event = \Stripe\Event::constructFromJson($payload);

    if ($event->type === 'balance.available') {
        $balance_obj = $event->data->object;
        // 通过Stripe交易ID关联到对应订单
        $order = wc_get_order_by_meta_key('_stripe_payment_intent_id', $balance_obj->source_transaction);
        
        if ($order) {
            $blog_id = get_current_blog_id(); // 或从订单元数据获取对应站点ID
            $connected_account_id = get_site_option('vendor_stripe_id_' . $blog_id);
            $commission_percentage = get_site_option('vendor_commission_percentage_' . $blog_id);
            $commission_amount = $order->get_total() * ($commission_percentage / 100);

            // 初始化Stripe客户端
            $stripe_api_keys = get_site_option('stripe_api_keys');
            $key = $stripe_api_keys["test_mode"] ? $stripe_api_keys['test_secret_key'] : $stripe_api_keys['live_secret_key'];
            $stripe = new \Stripe\StripeClient($key);

            // 执行转账
            try {
                $stripe->transfers->create([
                    'amount' => intval($commission_amount * 100),
                    'currency' => 'usd',
                    'destination' => $connected_account_id,
                ]);
                $order->add_order_note('佣金已成功转账至商家Stripe账户');
            } catch (\Stripe\Exception\ApiErrorException $e) {
                error_log('Stripe转账错误: ' . $e->getMessage());
                $order->add_order_note('佣金转账失败: ' . $e->getMessage());
            }
        }
    }

    wp_send_json_success();
}

原代码的关键问题修正 #

1. 移除die()：会中断WooCommerce后续流程，导致订单状态无法正常更新；
2. 移除重复的$stripe->transfers->create调用：仅需在try块内执行一次；
3. 优化错误处理：不要直接echo错误信息，改为记录到WordPress日志并添加订单备注：

// 替换原错误处理逻辑
catch (\Stripe\Exception\ApiErrorException $e) {
    error_log('Stripe转账错误: ' . $e->getMessage());
    $order->add_order_note('Stripe佣金转账失败: ' . $e->getMessage());
} catch (Exception $e) {
    error_log('系统转账错误: ' . $e->getMessage());
    $order->add_order_note('佣金转账失败: ' . $e->getMessage());
}

内容的提问来源于stack exchange，提问作者Muhammad Junaid Khan