Desarrollo de Marketplaces B2B y B2C en WooCommerce: Guía Técnica de Split Payments con Stripe Connect

Crear una plataforma de comercio electrónico multivendedor (estilo Amazon, Mercado Libre o Etsy) sobre WooCommerce ofrece la máxima flexibilidad de personalización y control total sobre las comisiones del negocio. Sin embargo, el reto principal radica en la gestión financiera: cómo dividir los pagos de un carrito que contiene productos de diferentes vendedores (split payments) y liquidar fondos de forma automática y legal. En esta guía técnica analizamos la arquitectura de integración con Stripe Connect y Dokan / WCFM.

Arquitectura de un Marketplace Multivendedor con Split Payments#

Cuando un comprador realiza un checkout con productos pertenecientes a múltiples vendedores, el flujo de fondos debe segregarse en tiempo real:

[Comprador en Checkout: $150 USD]
  ├── Producto Vendedor A: $100 USD
  └── Producto Vendedor B: $50 USD
                 │
                 ▼
     [Stripe Connect PaymentIntent]
                 │
   ┌─────────────┴─────────────┐
   │                           │
   ▼                           ▼
[Transferencia Vendedor A]  [Transferencia Vendedor B]
- Monto: $90 USD (90%)      - Monto: $45 USD (90%)
- Subcuenta Connect A       - Subcuenta Connect B
   │                           │
   └─────────────┬─────────────┘
                 │
                 ▼
      [Comisión Marketplace]
      - Fee Plataforma (10%): $15 USD
      - Retenido en Cuenta Principal

Modos de Integración de Stripe Connect#

Para marketplaces en WooCommerce existen dos esquemas principales según la responsabilidad fiscal y operativa:

1. Direct Charges con application_fee_amount#

El cliente realiza la transacción directamente con el vendedor conectado. La plataforma toma una tarifa de aplicación (Application Fee) y el vendedor asume las comisiones de procesamiento de tarjeta y disputas.

2. Destination Charges con transfer_data (Recomendado)#

El cliente paga a la plataforma del Marketplace. Stripe crea una transferencia inmediata o programada a las cuentas conectadas de los vendedores descontando la comisión del marketplace.

Implementación Técnica: Hook de Creación de PaymentIntent en WooCommerce#

A continuación se muestra la lógica personalizada en PHP para calcular las comisiones por vendedor y adjuntar los parámetros de transferencia a la API de Stripe:

<?php
/**
 * Plugin Name: Marketplace Split Payments Engine
 * Description: Divide los pagos de WooCommerce automáticamente entre los vendedores mediante Stripe Connect.
 * Version: 1.0.0
 * Author: Brayan Developer
 */

if (!defined('ABSPATH')) exit;

add_filter('wc_stripe_payment_intent_args', 'custom_marketplace_split_payment_intent', 10, 2);

function custom_marketplace_split_payment_intent($args, $order) {
    $marketplace_fee_percentage = 0.10; // 10% de comisión para la plataforma
    $items = $order->get_items();
    
    $vendor_totals = [];
    
    // 1. Agrupar montos por vendedor conectado
    foreach ($items as $item) {
        $product_id = $item->get_product_id();
        $author_id = get_post_field('post_author', $product_id);
        
        // Obtener el Stripe Account ID del vendedor (almacenado en usermeta)
        $stripe_account_id = get_user_meta($author_id, '_stripe_connect_account_id', true);
        
        if ($stripe_account_id) {
            $line_total = (float) $item->get_total();
            if (!isset($vendor_totals[$stripe_account_id])) {
                $vendor_totals[$stripe_account_id] = 0;
            }
            $vendor_totals[$stripe_account_id] += $line_total;
        }
    }
    
    // 2. Si es una orden mono-vendedor, aplicar Destination Charge directo
    if (count($vendor_totals) === 1) {
        $stripe_account_id = array_key_first($vendor_totals);
        $total_vendor_amount = $vendor_totals[$stripe_account_id];
        
        $order_currency = strtolower($order->get_currency());
        $multiplier = in_array($order_currency, ['jpy']) ? 1 : 100;
        
        $args['transfer_data'] = [
            'destination' => $stripe_account_id,
            'amount'      => round(($total_vendor_amount * (1 - $marketplace_fee_percentage)) * $multiplier),
        ];
    }
    
    // 3. Metadata para auditoría y trazabilidad
    $args['metadata']['order_id'] = $order->get_id();
    $args['metadata']['vendor_count'] = count($vendor_totals);
    
    return $args;
}

Sincronización de Webhooks y Liquidaciones Automáticas#

Para gestionar cancelaciones, devoluciones y disputas (chargebacks), el webhook de Stripe debe procesar los siguientes eventos:

• account.updated: Valida si el vendedor ha completado su verificación de identidad (KYC) y puede recibir transferencias (charges_enabled / payouts_enabled).
• payment_intent.succeeded: Confirma la orden en WooCommerce y marca las sub-órdenes de cada vendedor como pagadas.
• charge.refunded: Descuenta automáticamente la comisión proporcional y retira los fondos de la subcuenta del vendedor.

// Handler de webhook en endpoint REST
add_action('rest_api_init', function () {
    register_rest_route('marketplace/v1', '/stripe-webhook', [
        'methods'  => 'POST',
        'callback' => 'handle_marketplace_stripe_webhook',
        'permission_callback' => '__return_true',
    ]);
});

function handle_marketplace_stripe_webhook(WP_REST_Request $request) {
    $payload = $request->get_body();
    $sig_header = $_SERVER['HTTP_STRIPE_SIGNATURE'] ?? '';
    $endpoint_secret = get_option('marketplace_stripe_webhook_secret');
    
    try {
        $event = \Stripe\Webhook::constructEvent($payload, $sig_header, $endpoint_secret);
    } catch (\Exception $e) {
        return new WP_REST_Response(['error' => $e->getMessage()], 400);
    }
    
    if ($event->type === 'account.updated') {
        $account = $event->data->object;
        $user = get_users([
            'meta_key'   => '_stripe_connect_account_id',
            'meta_value' => $account->id,
            'number'     => 1,
        ]);
        
        if (!empty($user)) {
            $user_id = $user[0]->ID;
            $can_receive_payouts = $account->payouts_enabled && $account->charges_enabled;
            update_user_meta($user_id, '_stripe_payouts_enabled', $can_receive_payouts ? '1' : '0');
        }
    }
    
    return new WP_REST_Response(['status' => 'success'], 200);
}

Optimización de Rendimiento para Catálogos Multivendedor#

Un marketplace acumula rápidamente miles de productos, variantes y atributos. Para mantener tiempos de respuesta inferiores a 800ms:

1. High-Performance Order Storage (HPOS): Migrar de wp_posts a las tablas dedicadas de pedidos de WooCommerce.
2. Redis Object Cache: Cachear consultas complejas de inventario y balances de vendedores.
3. Buscador Predictivo AJAX: Desacoplar las búsquedas del motor nativo de SQL para evitar bloqueos de tabla.

Conclusión#

Desarrollar un Marketplace en WooCommerce con Stripe Connect permite crear un modelo de negocio altamente rentable con comisiones automáticas, onboarding KYC seguro y experiencia de compra fluida.

¿Estás planeando lanzar un Marketplace multivendedor B2B o B2C con liquidación automática de pagos? Conoce nuestras soluciones en Desarrollo de E-commerce y Marketplaces o agenda una consultoría técnica directa.