Glosario de pagos

Terminología de la industria y específica de Migo.

Actores

Acquirer (Adquirente) — El banco o institución financiera que procesa transacciones con tarjeta en representación de un comercio. Migo opera como payfac, ubicándose entre comercios y adquirentes.

Application — Identidad de un caller backend en Migo. Cada application tiene su propio par applicationId + secret y su propio conjunto de operaciones permitidas.

Cardholder (Tarjetahabiente) — Una persona que posee una tarjeta emitida vía Migo. Los tarjetahabientes se crean desde el CMS o vía el endpoint POST /users del Wallet Gateway.

Issuer (Emisor) — El banco que emite la tarjeta al tarjetahabiente. Distinto del adquirente.

Merchant (Comercio) — Un negocio que acepta pagos. En la data de Migo un comercio se modela como un Business con una o más Branches (sucursales) y una o más Terminals (terminales).

Partner — Cliente de Migo que opera su propia sub-tenancy — típicamente un neobanco, fintech o empresa que usa las APIs de Migo para servir a sus propios comercios / tarjetahabientes downstream.

Processor (Procesador) — El servicio técnico que se comunica con las redes de tarjetas y los adquirentes. Migo integra múltiples procesadores detrás de sus APIs y enruta cada transacción al adecuado; el procesador específico es un detalle interno que tú no seleccionas ni ves en el contrato público.

Entidades

Branch (Sucursal) — Una ubicación física de un Business. Tiene su propio código identificador usado en liquidaciones.

Business (Negocio) — La entidad de comercio. Se crea a partir de un Lead aprobado, posee sucursales y terminales.

Card (Tarjeta) — Una tarjeta tokenizada física emitida vía Migo. Identificada por cardId. Nunca expongas el PAN directamente.

Lead — Un comercio prospecto en proceso de onboarding. Captura datos de KYC y documentos de soporte. Se convierte en Business una vez aprobado.

Plan — Configuración de precios de suscripción (monto, intervalo, prueba). Se define una vez y se reutiliza entre suscripciones.

Settlement (Liquidación) — El estado maduro y compensado de una transacción — el dinero ha sido movido desde el banco del tarjetahabiente al comercio (menos la comisión de Migo).

Subscription (Suscripción) — Una relación continua que genera cobros según un calendario o bajo demanda. Respaldada por un método de pago (tarjeta).

Terminal — Un dispositivo POS físico o virtual ligado a una Branch. Cada terminal se aprovisiona contra uno o más procesadores.

Transaction (Transacción) — Cualquier movimiento de dinero: cobro, reembolso, transferencia, payout.

Flujos

3-D Secure (3DS) — Protocolo de autenticación de las redes de tarjetas. El tarjetahabiente es redireccionado al ACS de su banco para completar un challenge (biométrico, OTP, etc.). Migo soporta 3DS1 y 3DS2.

Auth + Capture (Dos pasos) — Reservar fondos ahora (autorización) y capturar (liquidar) después. Común en marketplaces, hospitalidad, renta de autos.

Conciliation (Conciliación) — Reconciliar el ledger de transacciones de Migo contra tu ledger interno o el archivo de liquidación del adquirente. Los partners payfac suben archivos de conciliación diarios.

One-step payment (Pago en un paso) — Autorización + captura en un solo request. El default para retail.

Payfac (Payment Facilitator) — Modelo de negocio en el que Migo mantiene un acuerdo de master merchant y los sub-comercios (tus comercios) operan bajo ese acuerdo. Permite onboarding rápido sin que cada comercio firme directamente con un adquirente.

Tokenization (Tokenización) — Reemplazar el PAN con una referencia no sensible (cardId). Migo guarda el PAN en la bóveda con alcance PCI-DSS; tú almacenas el token.

Webhook — Callback HTTP de Migo a tu servidor ante cambios de estado. Protege tu receptor con lista de IPs permitidas; el esquema de firma Ed25519 es un estándar objetivo documentado pero aún no se aplica de extremo a extremo. Consulta Salida a producción → Webhooks.

Dinero y precisión

Decimal — Los montos monetarios se almacenan con precisión Decimal(20,4) (hasta 20 dígitos, 4 decimales). En los bodies de las solicitudes y en la mayoría de las respuestas son números decimales (p. ej. 150.5). Solo algunas respuestas de reportes del CMS serializan los montos como strings — revisa el schema de cada endpoint. No existe una representación de "unidades menores" / centavos enteros; los montos son valores decimales.

Identificadores

applicationId — El identificador de tu aplicación móvil (p. ej. com.migo.ali). Usado por el flujo de integridad del dispositivo vía el header HTTP applicationid. Nota: el POST /auth/login del Wallet Gateway no se autentica con este header — usa un identificador merchant más una signature Ed25519.

cardId — Identificador interno numérico de una tarjeta tokenizada (entero, p. ej. 12345).

cardholderId — Identificador interno numérico de un tarjetahabiente (entero, gestionado por CMS).

commerceId / businessId — Identificador interno numérico de un Business (entero).

authUserId — Identificador interno numérico de un usuario final (usuario de la app wallet). Distinto del usuario CMS.

cmsUserId — Identificador interno numérico de un operador CMS (empleado de Migo o del partner).

partnerId / clientId — Slugs string del CMS (p. ej. partner-123), no numéricos.

externalId — Tu propia referencia para una transacción o entidad. Migo te la devuelve en webhooks y reportes.