MercadoPago - Cobro de cuotas online

MercadoPago es un medio de cobro online que se integra a Plenario para que los clientes puedan pagar las cuotas de sus créditos con tarjeta, dinero en cuenta o efectivo (Pago Fácil / Rapipago), usando el checkout de MercadoPago (Checkout Pro).

Funciona de forma complementaria al proveedor de cobro base (Pago360 / Mobbex): no lo reemplaza, se suma como una opción más. El circuito es el mismo que ya conocés de Pago360, pero sobre la plataforma de MercadoPago.

Se puede usar de dos maneras:

• Desde la web de clientes (MisCreditos): el cliente entra, ve sus créditos y cuotas, elige las que quiere pagar y paga con MercadoPago.
• Desde el Back Office (Detalle de Crédito): un operador genera un link de pago para una o varias cuotas y se lo envía al cliente por correo o WhatsApp.

Cuando el cliente paga, el cobro se imputa automáticamente (asiento contable + cuenta corriente + cuota marcada como cobrada), sin intervención manual. Este manual explica cómo configurarlo y cómo usarlo desde cero.

MercadoPago no es una pantalla propia: se usa desde los lugares donde ya cobrás cuotas.

1. Detalle de Crédito (Back Office) — Préstamos → Créditos → abrí un crédito → botón Operaciones. Ahí están las acciones de MercadoPago (crear link, verificar cobro) y en Ver el log de MercadoPago.
2. Grilla de Solicitudes (Back Office) — en el ribbon hay un botón Log → MercadoPago para ver los movimientos del crédito seleccionado.
3. MisCreditos (web de clientes) — el cliente ingresa a su portal, abre un crédito, selecciona cuotas y llega a la pantalla "Confirmar Pago" con la botonera de medios de pago:

Importante: para generar links de pago desde el Back Office necesitás el permiso de operaciones de solicitud de pago. Ver la sección Permisos al final.

En el Detalle de Crédito, el menú Operaciones agrupa las acciones de cobro. Además de las de Pago360 y Mobbex, vas a encontrar las de MercadoPago:

• MercadoPago: Crear link de pago y enviar por correo al cliente
• MercadoPago: Crear link de pago (copiar para WhatsApp)
• MercadoPago: Verificar cobro / Conciliar

El menú Ver incluye Log MercadoPago (crédito) y Log MercadoPago (cuota seleccionada). Todas estas opciones están también en el menú contextual (clic derecho sobre la grilla de cuotas), en el mismo orden.

Toda la configuración de MercadoPago vive en parámetros del sistema. El principal es un parámetro con un JSON (patrón config-en-parámetro, no una tabla).

Parámetro de credenciales (JSON)

Parámetros del cobro desde el Back Office

Parámetros de MisCreditos (web de clientes) y del webhook

Configuración en el panel de MercadoPago

1. Credenciales — en el panel de MercadoPago, sección Credenciales, copiá el Access Token al parámetro JSON (campo Test o productivo según corresponda).
2. Webhook — en la sección Webhooks / Notificaciones, cargá la URL (…/MercadoPago/WebHooks) y copiá la Clave secreta al parámetro JSON. Ojo: el panel tiene Modo de prueba y Modo productivo, cada uno con su propia clave secreta; usá la que corresponda al entorno de tus pagos.

Importante: si el token es de producción, los pagos salen reales (live_mode:true) y MercadoPago firma con la clave secreta productiva. Para probar sin plata real, usá credenciales de test + un usuario de prueba comprador (así los pagos son live_mode:false).

Medios de pago y cuotas del checkout

Cuatro parámetros definen qué le ofrece MercadoPago al cliente en cada link. Aplican a todos los links (los de la web MisCreditos, los que manda el Back Office y los que genera la API) y sólo tienen efecto en los links que se generan después del cambio.

Con los valores por defecto el checkout ofrece todos los medios de pago, pero la tarjeta de crédito paga en un solo pago.

Cuotas máximas — sólo afecta a la tarjeta de crédito (débito, prepaga, dinero en cuenta y efectivo siempre van en un pago):

El interés de las cuotas lo define la cuenta de MercadoPago, no Plenario: la cuota del crédito se imputa siempre por el importe del link, sin el interés de la tarjeta.

Tipos de pago excluidos — códigos separados por coma (ej. ticket,digital_currency); excluir un tipo saca todas sus marcas:

Marcas excluidas — códigos separados por coma (ej. amex,diners); excluir una marca deja disponible el resto de su tipo:

Ojo con las prepagas: usan el mismo código que la tarjeta de crédito de su marca (visa, master, cabal). Excluir visa saca la Visa de crédito y la Visa prepaga, pero no la Visa Débito (que es debvisa).

Modo binario — en 1 el pago se aprueba o rechaza al instante (lo que hubiera quedado pendiente o en revisión se rechaza) y, como un cupón siempre nace pendiente, el sistema además saca el efectivo del checkout. Ventaja: no quedan pagos pendientes que bloqueen un nuevo link. Desventaja: baja el porcentaje de pagos aprobados.

Configuraciones típicas:

Importante: MercadoPago no avisa si un código está mal escrito (simplemente no excluye nada). El sistema valida los tipos y deja lo descartado en el log; se toleran mayúsculas, espacios, ; y repetidos. El dinero en cuenta no se puede excluir (no existe un checkout "solo tarjetas") y CuotasMaximas no limita las Cuotas sin Tarjeta (para sacarlas, excluí el tipo digital_currency). Después de cambiar cualquiera de estos parámetros hay que reciclar el AppPool de la web y de la API (y reiniciar el Back Office en las demás PC) y conviene abrir un link de prueba para ver qué ofrece el checkout.

El cobro se imputa por dos vías complementarias, con doble red de seguridad:

Importante: el cobro está garantizado por la conciliación aunque el webhook falle. Ningún pago se pierde: si el webhook no lo imputó, la tarea automática lo levanta en pocos minutos.

Cómo generar y enviar un link de pago

1. Abrí el crédito — Préstamos → Créditos → abrí el crédito del cliente.
2. Seleccioná las cuotas — marcá en la grilla las cuotas a cobrar (deben ser impagas y consecutivas desde la primera pendiente).
3. Operaciones — hacé clic en Operaciones y elegí Crear link y enviar por correo o Crear link (copiar para WhatsApp).
4. Enviá — si es por correo, se manda solo; si es WhatsApp, pegá el link (ya está en el portapapeles) en el chat del cliente.

Importante: si ya existe un pago activo (aprobado o en curso) para esas cuotas, el sistema no genera un link nuevo y avisa, para evitar el doble pago.

Cómo verificar un cobro manualmente

1. Abrí el crédito y hacé clic en Operaciones → Verificar cobro / Conciliar.
2. Resultado — el sistema consulta MercadoPago e imputa lo que falte. Muestra cuántas cuotas imputó.

Querés cobrarle a un cliente la cuota 3 de su crédito mandándole el link por WhatsApp:

1. Abrí el crédito en Préstamos → Créditos.
2. Seleccioná la cuota 3 en la grilla.
3. Operaciones → MercadoPago: Crear link de pago (copiar para WhatsApp).
4. Pegá el link (ya copiado) en el chat de WhatsApp del cliente.
5. Esperá el pago — cuando el cliente pague, la cuota se marca cobrada sola (webhook) o, si tarda, hacés Verificar cobro para imputarla al toque.

El link tiene vencimiento (por defecto 7 días desde que lo emitís): si el cliente no paga en ese plazo, generá uno nuevo. La vigencia se controla por parámetro según el origen: BO.MercadoPago.Link.DiasVigencia para los links del Back Office y Web.MisCreditos.MercadoPago.Link.DiasVigencia para los de la web de clientes (0 = sin vencimiento).

Si el cliente dice que pagó pero la cuota figura impaga, usá Verificar cobro / Conciliar antes de preocuparte: en pocos minutos la tarea automática también la levanta.

No hace falta esperar el webhook: la conciliación es la red de seguridad y cobra igual.

Para pagos de prueba, usá un usuario de prueba comprador de MercadoPago y una tarjeta de test con titular APRO (fuerza la aprobación).

Ver el log de MercadoPago no requiere permiso adicional. El endpoint de conciliación se protege con el token interno BO.MercadoPago.Conciliar.Token, no con permisos de usuario.

Sección de referencia para soporte/desarrollo. Basada en la implementación real de la v14 (changesets 23190–23329; medios de pago y cuotas del checkout en 23613).

Componentes principales

Tablas de base de datos principales

Se imputa el bruto al cliente; MP deposita el neto (bruto − comisión). Ambos quedan guardados (Data_Payment_Total vs Neto_Acreditado), lo que permite conciliar contra el depósito bancario. Toda columna/tabla nueva debe estar en el proyecto SSDT VPNET_Database o el publish del DACPAC la borra.

Relación con otros módulos / manuales

Notas para soporte (comportamiento real)

• external_reference: {Id_Solicitud},{Id_Credito},{Id_PCD…} (mismo layout que Pago360). El webhook lo parsea para imputar. Es agnóstico al origen: un link nacido en el BO imputa igual que uno de MisCreditos.
• Idempotencia (3 capas): HookProcesadoConCobros (por payment_id) + cuotas solo Fecha_Cobro == null + transacción IsolationLevel.Snapshot (conflicto de escritura si dos procesos imputan la misma cuota a la vez → el segundo hace rollback).
• Firma del webhook (no bloqueante por defecto): manifiesto id:{queryDataId};request-id:{x-request-id};ts:{ts}; firmado HMAC-SHA256. Los headers se leen de HttpContext.Current.Request (WebOperationContext no los expone bien); se usa el data.id del query string; ValidarFirma prueba las secrets de test y producción. Los pagos reales llegan con live_mode:true y su firma no se pudo reproducir con la clave configurada, así que con Web.MercadoPago.WebHooks.ValidarFirma = 0 (default) la firma NO bloquea: si no valida, se registra el diagnóstico y el proceso continúa. Esto no debilita la seguridad: la notificación nunca es la fuente de verdad — el sistema consulta el pago a MercadoPago con su propio Access Token privado y solo imputa si MP responde approved y el external_reference corresponde a un crédito propio (una notificación falsificada solo lograría consultar un pago inexistente). De hecho, la conciliación imputa esos mismos pagos sin validar ninguna firma. Con = 1 se restaura el modo estricto.
• Vencimiento del link: expires=true + expiration_date_from/to desde el día de emisión, según BO.MercadoPago.Link.DiasVigencia.
• Medios de pago y cuotas del checkout (23613): los 4 parámetros Web.MisCreditos.MercadoPago.Checkout.* se mandan en cada preferencia (payment_methods + binary_mode). Validaciones contra el comportamiento real de la API (probado en sandbox 17/09/2026): account_money no se puede excluir (la API responde 400 account_money cannot be excluded) → se descarta y va al log; código inexistente/mal escrito → 201 sin efecto, se valida contra la lista conocida; marca cargada como tipo (o viceversa) → se mueve a la lista correcta; installments fuera de 1..36 → 0 no se manda, mayor a 36 se toma 36, inválido = 1; con modo binario se excluye ticket (la API no lo saca sola). Si la lectura de la config falla, el link se genera igual con el default (sin cuotas) y el error queda registrado. La config con la que salió cada link queda en MercadoPago_Log.Request (nodos PaymentMethods y BinaryMode).
• Conciliación automática: conviene armar una tarea programada (Programador de tareas de Windows u otro scheduler) en un equipo que quede siempre encendido —un servidor o una PC que no se apague— para que cada pocos minutos (por ejemplo, cada 10) ejecute un script que llame al endpoint MercadoPago/ConciliarPendientes de la API. Así, aunque un webhook no llegue, los pagos aprobados que quedaron sin imputar se levantan solos a los pocos minutos. Conviene que la tarea corra bajo una cuenta con permiso para ejecutarse desatendida.

Esquema del script de conciliación (PowerShell). No incluye credenciales: reemplazá los marcadores <...> por los valores de tu instalación. El token es el valor del parámetro BO.MercadoPago.Conciliar.Token y la URL es la de la API de Plenario (la misma base que el webhook).

# Fuerza TLS 1.2 (requerido para hablar con la API)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

$uri   = "<URL_API>/MercadoPago/ConciliarPendientes"   # misma base que el webhook
$token = "<TOKEN_CONCILIACION>"                         # = parametro BO.MercadoPago.Conciliar.Token
$log   = "<RUTA_DEL_LOG>"                               # archivo donde registrar el resultado
$body  = '{"token":"' + $token + '","dias":15,"max":200}'

try {
    $r = Invoke-WebRequest -Uri $uri -Method Post -Body $body `
         -Headers @{ "Content-Type" = "application/json" } -UseBasicParsing -TimeoutSec 240
    Add-Content $log ("{0} OK {1}"    -f (Get-Date), $r.Content)
} catch {
    Add-Content $log ("{0} ERROR {1}" -f (Get-Date), $_.Exception.Message)
}

En el cuerpo, dias indica cuántos días hacia atrás revisar y max el tope de solicitudes por corrida. El endpoint es idempotente: nunca vuelve a imputar una cuota ya cobrada, así que es seguro correrlo tan seguido como quieras.