CIT vs. MIT
Toda relación de credencial almacenada comienza con una Customer Initiated Transaction (CIT), durante la cual el cliente está presente y autoriza explícitamente los cobros futuros.CIT — cliente presente
El cliente está completando activamente el checkout. Recolectas la tarjeta vía un nonce fresco (o número de tarjeta sin procesar) y estableces
cardOnFile.usage: "first". La respuesta devuelve card.networkTransactionId y card.networkReferenceId — guarda ambos valores en tu base de datos. Los necesitarás para cada MIT posterior.MIT — iniciada por el comercio
El cliente no está presente. Pasas el vault token guardado más los campos de credencial almacenada, incluidos el
networkTransactionId y el networkReferenceId de la CIT original. Las redes de tarjetas usan estas referencias para enlazar el cobro con el mandato autorizado.El objeto cardOnFile
Agrega un bloque cardOnFile dentro del objeto card tanto en la CIT como en cada MIT. cardOnFile en sí es opcional (Therius deriva un valor predeterminado según el contexto — un tokenize nuevo frente a una reutilización de tokenData — cuando se omite), pero una vez que lo envías, usage, initiatedBy y type son los tres campos que juntos clasifican el cobro ante las redes de tarjetas.
initiatedBy usa "cardholder", no "customer" — respeta el valor exacto del enum.exceptionReason es opcional y se sitúa en un eje propio, independiente de type — no reemplaza a type, añade una etiqueta de excepción de negocio encima. La mayoría de los cobros MIT posteriores nunca lo envían; establécelo solo cuando el cobro específico caiga en una de estas categorías definidas por la bandera:
Ejemplo de CIT inicial
Recolecta la tarjeta de forma normal (usando un nonce del SDK o datos de tarjeta sin procesar en un servidor que cumple PCI), tokenízala estableciendotokenize: true, e incluye el bloque cardOnFile.
Guardar una tarjeta sin conocer el patrón de cobro futuro
Si estás guardando en el vault una tarjeta y aún no sabes si se convertirá en una suscripción recurrente, un plan de cuotas o un cargo único no programado, decláralo como"type": "unscheduled" — la categoría que las redes de tarjetas destinan a “uso futuro autorizado por el titular, patrón aún no determinado”. Guarda igualmente el networkTransactionId/networkReferenceId devueltos; los necesitarás para cualquier MIT que termines enviando.
Si la tarjeta solo se reutilizará en un futuro checkout con el cliente presente — el cliente la elige entre sus métodos guardados y confirma el cobro él mismo, nunca cobrada sin presencia por ti — no necesitas ningún bloque
cardOnFile. Solo envía tokenize: true con shopper.id. cardOnFile solo importa cuando ocurrirá una MIT.Ejemplo de MIT posterior — renovación recurrente
En cada cobro posterior — una renovación, una cuota, un cargo adicional no programado — pasa el vault token más los campos de credencial almacenada y las referencias de red de la CIT original. Este ejemplo muestra una renovación recurrente (estilo suscripción); cambiatype por installment o unscheduled para que coincida con el mandato que estableciste en la CIT.
El motor de suscripciones de Therius administra las credenciales almacenadas internamente para todas las renovaciones de suscripción. Nunca necesitas suministrar
cardOnFile ni campos de referencia de red al usar la API de suscripciones — esta guía solo es relevante si estás construyendo tu propia lógica de facturación fuera del motor de suscripciones.Tipos de credencial
Recurrente
Usa
"type": "recurring" para cobros de monto fijo que se repiten en un calendario predecible — cuotas mensuales de SaaS, renovaciones anuales, cuotas de membresía.Cuota
Usa
"type": "installment" cuando un cliente autoriza un pago dividido en una cantidad fija de cobros — por ejemplo, tres pagos mensuales por una sola compra.No programada
Usa
"type": "unscheduled" para cobros que se autorizan por adelantado pero se disparan por un evento definido por el comercio — facturación por uso, recargas de cuenta, tarifas de conveniencia, o una tarjeta guardada para uso futuro antes de conocer su patrón definitivo.exceptionReason — un eje separado y opcional de type, usado solo cuando una MIT específica cae en una categoría de excepción definida por la bandera.