--- title: "Conciliación Automática de Pagos en Turismo y Hotelería: Sincronización Contable en VikBooking con Mercado Pago y Pasarelas Locales" description: "Descubre cómo automatizar la conciliación financiera y contable en hoteles. Guía de integración entre VikBooking, Mercado Pago Settlement Reports y deducción de retenciones fiscales en LATAM." date: 2026-09-07 category: "Finanzas Dev" imageUrl: "/assets/images/blog/conciliacion-automatica-pagos-turismo-vikbooking.webp" imageAlt: "Tablero de conciliación contable y financiera para hoteles con reservas de VikBooking, balance de transacciones bancarias y pasarelas de pago" readTime: "11 min de lectura" author: "DoneAPI Engineering Team" tags: ["VikBooking", "Mercado Pago", "Conciliación", "Finanzas Dev", "Hotelería", "WordPress", "Fintech"] lang: "es" translationSlug: "automated-payment-reconciliation-hospitality-vikbooking" featured: false --- En la industria de la hospitalidad y el turismo, la gestión financiera no concluye cuando el huésped completa el pago de su reserva con tarjeta de crédito o transferencia bancaria. Para el departamento contable de un hotel, hostal o cadena de cabañas vacacionales, ese momento marca apenas el inicio de un laberinto operativo: **la conciliación de pagos**. Cuando un hotel utiliza **VikBooking** sobre WordPress junto a procesadores como **Mercado Pago**, existe una brecha notable entre el valor bruto de la reserva (*Gross Booking Value*) y el dinero real que ingresa a la cuenta bancaria del hotel semanas después. Comisiones de la pasarela (entre el 2.99% y el 3.49% + IVA), retenciones impositivas obligatorias en origen (ReteFuente, ReteIVA y ReteICA en Colombia, percepciones de IIBB en Argentina, retenciones de ISR en México) y tarifas de liberación inmediata crean desajustes continuos en los libros contables. Muchos hoteles intentan conciliar estos valores descargando archivos CSV de Mercado Pago y cruzando celdas manualmente en hojas de cálculo de Excel. Este método manual no solo consume decenas de horas al mes, sino que provoca errores humanos, fugas de capital y retrasos en el cierre contable fiscal. En este artículo técnico para desarrolladores, directores financieros (CFOs) y administradores hoteleros, analizaremos la arquitectura de **conciliación bancaria automatizada**, cómo consumir la API de Balance y Reportes de Liquidación (*Settlement Reports*) de Mercado Pago y cómo sincronizar automáticamente los estados financieros dentro de la base de datos de VikBooking. --- ## 1. La Ecuación Contable del Pago Hotelero en América Latina Para diseñar un sistema automatizado de conciliación, primero debemos modelar matemáticamente el flujo de fondos de cada transacción: ``` ┌────────────────────────────────────────────────────────────────────────┐ │ Desglose Financiero de una Reserva │ └────────────────────────────────────────────────────────────────────────┘ [Tarifa Neta de la Habitación] $ 1,000,000 COP + [Impuestos Locales / IVA 19%] $ 190,000 COP --------------------------------------------------------- = [Monto Cobrado al Huésped (Bruto)] $ 1,190,000 COP (Registrado en VikBooking) - [Comisión Mercado Pago (3.19% + IVA)] -$ 45,208 COP - [Retención en la Fuente (ReteFuente)] -$ 17,850 COP - [Retención de IVA (ReteIVA 15%)] -$ 5,415 COP - [Retención de ICA (ReteICA)] -$ 4,926 COP --------------------------------------------------------- = [Monto Neto Liquidado en Banco] $ 1,116,601 COP (Fondos Disponibles) ``` Si el software de reservas solo registra que se cobraron `$1,190,000 COP`, pero el banco recibe `$1,116,601 COP`, existe una discrepancia contable de `$73,399 COP`. Sin un software que registre de forma transparente el desglose de cada deducción fiscal y comisión financiera asociado al `booking_id`, los balances de fin de mes jamás cuadrarán ante las autoridades tributarias (DIAN, SAT o AFIP). --- ## 2. Arquitectura de Conciliación: Dos Capas de Sincronización La conciliación profesional no depende únicamente del webhook instantáneo. Requiere una arquitectura desacoplada en dos etapas: ``` [Etapa 1: En Tiempo Real (Webhooks IPN)] Mercado Pago ──► Webhook Listener ──► Marca Reserva como PAGADA en VikBooking (Garantiza el Check-in del Huésped) [Etapa 2: Nocturna / Diferida (Settlement Reports API)] Cron Job / CLI ──► Consulta /v1/balance/history en Mercado Pago │ ▼ (Cruza External Reference: "VB-4589") Calcula Comisiones Netas y Retenciones Impositivas │ ▼ Actualiza Libro Diario y Tabla Contable en WordPress ``` 1. **Capa Transaccional Operativa (Tiempo Real)**: Verifica que la tarjeta fue aprobada y confirma la habitación en VikBooking para evitar sobreventas (*overbooking*). 2. **Capa de Conciliación Financiera (Cierre Diario)**: Se ejecuta de manera programada (típicamente a las 02:00 AM) cuando Mercado Pago consolida los reportes de liquidación. Esta capa descarga los identificadores de liquidación (*settlement IDs*), clasifica las deducciones impositivas y marca la transacción como **CONCILIADA**. --- ## 3. Consumo de la API de Balance y Movimientos de Mercado Pago Mercado Pago ofrece el endpoint `/v1/balance/history` para auditar todos los movimientos financieros asociados a una cuenta de recaudación. A diferencia del endpoint de pagos común `/v1/payments/{id}`, este recurso expone el detalle exacto de las retenciones impositivas y el costo financiero de cada operación: ```bash # Consulta de movimientos financieros liquidados en las últimas 24 horas curl -X GET "https://api.mercadopago.com/v1/balance/history?begin_date=2026-09-06T00:00:00Z&end_date=2026-09-06T23:59:59Z" \ -H "Authorization: Bearer TEST-789456123-APP-TOKEN" \ -H "Content-Type: application/json" ``` El payload devuelto contiene un desglose estructurado dentro de la matriz `charges_details`: ```json { "id": 987654321, "date_created": "2026-09-06T14:32:10.000-04:00", "date_approved": "2026-09-06T14:33:05.000-04:00", "date_released": "2026-09-08T00:00:00.000-04:00", "external_reference": "VB-4589", "transaction_amount": 1190000.00, "net_amount": 1116601.00, "fee_details": [ { "type": "mercadopago_fee", "amount": 45208.00, "fee_payer": "collector" } ], "charges_details": [ { "type": "tax_withholding", "name": "rete_fuente", "amount": 17850.00 }, { "type": "tax_withholding", "name": "rete_iva", "amount": 5415.00 }, { "type": "tax_withholding", "name": "rete_ica", "amount": 4926.00 } ] } ``` --- ## 4. Implementación en WordPress: Comando de Conciliación Automática (WP-CLI) Para procesar grandes volúmenes de transacciones sin sufrir limitaciones de tiempo de ejecución de PHP en el navegador (`max_execution_time`), la mejor práctica en WordPress es implementar un comando **WP-CLI** o un worker que se invoque desde un cron del sistema operativo Linux (`crontab`). A continuación presentamos la implementación del motor de conciliación para VikBooking: ```php ] * : Número de días hacia atrás a conciliar (por defecto 1). * * ## EJEMPLO * wp doneapi reconcile-payments --days=2 */ public function __invoke($args, $assoc_args) { $days = isset($assoc_args['days']) ? intval($assoc_args['days']) : 1; WP_CLI::line("Iniciando conciliación financiera para los últimos {$days} días..."); $access_token = defined('MERCADOPAGO_ACCESS_TOKEN') ? MERCADOPAGO_ACCESS_TOKEN : get_option('doneapi_mp_access_token'); if (!$access_token) { WP_CLI::error("Access Token de Mercado Pago no configurado."); return; } $begin_date = gmdate('Y-m-d\TH:i:s\Z', strtotime("-{$days} days")); $end_date = gmdate('Y-m-d\TH:i:s\Z'); $url = add_query_arg([ 'begin_date' => $begin_date, 'end_date' => $end_date, 'status' => 'approved', ], 'https://api.mercadopago.com/v1/payments/search'); $response = wp_remote_get($url, [ 'headers' => [ 'Authorization' => "Bearer {$access_token}", 'Content-Type' => 'application/json', ], 'timeout' => 30, ]); if (is_wp_error($response)) { WP_CLI::error("Fallo al conectar con la API de Mercado Pago: " . $response->get_error_message()); return; } $body = json_decode(wp_remote_retrieve_body($response), true); $results = $body['results'] ?? []; WP_CLI::line("Se encontraron " . count($results) . " transacciones aprobadas en el periodo."); global $wpdb; $reconciled_count = 0; foreach ($results as $payment) { $external_ref = $payment['external_reference'] ?? null; if (!$external_ref || strpos($external_ref, 'VB-') !== 0) { continue; // No pertenece a VikBooking } $booking_id = intval(str_replace('VB-', '', $external_ref)); $gross_amount = floatval($payment['transaction_amount']); $net_amount = floatval($payment['net_received_amount'] ?? 0); $mp_fee = 0.0; $taxes = 0.0; if (isset($payment['fee_details'])) { foreach ($payment['fee_details'] as $fee) { $mp_fee += floatval($fee['amount']); } } if (isset($payment['charges_details'])) { foreach ($payment['charges_details'] as $charge) { if ($charge['type'] === 'tax_withholding') { $taxes += floatval($charge['amount']); } } } // Actualizar tabla contable de auditoría $table_reconcile = $wpdb->prefix . 'doneapi_hotel_reconciled_ledger'; $wpdb->replace($table_reconcile, [ 'booking_id' => $booking_id, 'payment_id' => $payment['id'], 'gross_amount' => $gross_amount, 'gateway_fee' => $mp_fee, 'tax_withheld' => $taxes, 'net_amount' => $net_amount, 'reconciled_at' => current_time('mysql'), 'payment_method' => $payment['payment_method_id'] ?? 'unknown', 'status' => 'RECONCILED' ], ['%d', '%s', '%f', '%f', '%f', '%f', '%s', '%s', '%s']); // Añadir nota de auditoría interna en VikBooking if (class_exists('VikBooking')) { $audit_note = sprintf( "Conciliado con éxito. Bruto: $%.2f | Comisión MP: -$%.2f | Retenciones: -$%.2f | Neto Banco: $%.2f", $gross_amount, $mp_fee, $taxes, $net_amount ); VikBooking::addPaymentLog($booking_id, [ 'gateway' => 'DoneAPI Reconciler', 'transaction_id' => $payment['id'], 'amount' => $net_amount, 'status' => 'RECONCILED', 'notes' => $audit_note ]); } $reconciled_count++; } WP_CLI::success("Conciliación finalizada. {$reconciled_count} reservas sincronizadas en los libros contables."); } } ``` --- ## 5. Tabla de Auditoría Contable para WordPress Para mantener la integridad contable sin tocar las tablas centrales del core de WordPress, implementamos una tabla con motor InnoDB y precisión decimal para cálculos financieros: ```sql CREATE TABLE `wp_doneapi_hotel_reconciled_ledger` ( `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT, `booking_id` int(11) unsigned NOT NULL, `payment_id` varchar(64) NOT NULL, `gross_amount` decimal(12,2) NOT NULL, `gateway_fee` decimal(12,2) NOT NULL DEFAULT '0.00', `tax_withheld` decimal(12,2) NOT NULL DEFAULT '0.00', `net_amount` decimal(12,2) NOT NULL, `payment_method` varchar(32) NOT NULL, `status` enum('PENDING','RECONCILED','DISCREPANCY','REFUNDED') NOT NULL DEFAULT 'PENDING', `reconciled_at` datetime NOT NULL, PRIMARY KEY (`id`), UNIQUE KEY `unique_payment` (`payment_id`), KEY `idx_booking_date` (`booking_id`, `reconciled_at`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; ``` --- ## 6. Manejo de Devoluciones y Reembolsos Parciales (*Refunds*) En el sector hotelero, las cancelaciones por fuerza mayor o modificaciones de fechas son frecuentes. Cuando un cliente solicita un reembolso: 1. **Reembolso Total**: Mercado Pago devuelve la comisión porcentual cobrada, pero no reintegra el costo fijo de procesamiento en ciertas jurisdicciones. El script conciliador detecta el estado `refunded`, actualiza el registro en `wp_doneapi_hotel_reconciled_ledger` a `REFUNDED` y calcula el impacto neto negativo en caja. 2. **Reembolsos Parciales (Cobro de Penalidad por No-Show)**: Si la política del hotel retiene el 50% de la primera noche por cancelación tardía, el sistema debe registrar el débito parcial manteniendo el saldo a favor en la cuenta bancaria del hotel. --- ## 7. Plugin DoneAPI VikBooking Mercado Pago ($7 USD) y Asesoría Contable La integración manual de pasarelas de pago y sistemas de conciliación para hoteles suele demandar meses de pruebas de integración y miles de dólares en honorarios de desarrollo. En **DoneAPI** hemos empaquetado esta tecnología para ponerla al alcance de cualquier establecimiento turístico: - **Plugin VikBooking Mercado Pago Oficial ($7 USD)**: Listo para instalar en WordPress, con soporte para pagos con tarjeta, PSE, Pix y OXXO, validación criptográfica HMAC y generación de identificadores `external_reference` preparados para conciliación automática. - **Sin Comisiones Recurrentes**: Pago único de $7 USD con licencia directa de código para tu dominio. - **Módulos de Exportación ERP**: Conectores personalizados para sincronizar las transacciones conciliadas de VikBooking con softwares contables líderes como Siigo, QuickBooks, SAP Business One y Alegra. > 💬 **¿Quieres adquirir el plugin de VikBooking Mercado Pago por $7 USD o necesitas automatizar la conciliación contable de tu cadena hotelera?** > Escríbenos directamente por WhatsApp y nuestro equipo de ingenieros te asistirá de inmediato.

Instala el Plugin VikBooking Mercado Pago ($7 USD) o Automatiza tu Conciliación

Elimina las hojas de cálculo manuales, audita tus comisiones y retenciones impositivas y cuadra la caja de tu hotel al centavo.

Hablar con un Especialista en Finanzas Dev por WhatsApp
--- ## 8. Conclusión La conciliación automática de pagos no es un lujo administrativo, sino un pilar fundamental para la salud financiera y fiscal de cualquier negocio hotelero moderno. Al integrar **VikBooking con los endpoints de liquidación de Mercado Pago**, las empresas turísticas eliminan la incertidumbre contable, deducen con precisión matemática las retenciones impositivas y garantizan que cada peso recaudado quede perfectamente auditado y justificado en sus libros contables.