Skip to main content
Inscribe la cuenta bancaria o tarjeta de débito mexicana de tu cliente y usa el medio de pago resultante para suscripciones o cargos bajo demanda.
La domiciliación mexicana (mx_direct_debit) está disponible en modo test. Sandbox simula la verificación de identidad, la verificación de cuenta, la aprobación del mandato y los cargos. No verifica documentos de identidad reales ni mueve dinero. Esta guía describe la integración en sandbox.
Elige cómo tu cliente autoriza el medio de pago: Ambos caminos requieren la aprobación asíncrona del mandato antes de poder cobrar el medio de pago. Completar el checkout es distinto de recibir la aprobación.

1. Prepara tu integración

Usa una clave secreta de prueba en tu servidor y configura webhooks para recibir los resultados de inscripción y pago. Las Checkout Sessions con este medio de pago requieren una organización configurada para México y moneda mxn. Envía Fintoc-Version: 2026-02-01 en las solicitudes a la API. Los ejemplos de Node usan el SDK oficial fintoc y los de Python usan el paquete oficial fintoc. El SDK de Node usa la versión de API predeterminada de tu organización, que debe ser 2026-02-01 o posterior para estos ejemplos. Consulta Autenticación para seleccionar la versión de API. Cada medio de pago pertenece a un Customer. Para el camino por API, crea un cliente primero y usa su id. Para Checkout Sessions, envía un ID de customer existente o customer_data para crear uno junto con la sesión. Los ejemplos siguientes usan customer_data. Para sesiones posteriores del mismo cliente de facturación, envía su ID de customer en vez de crearlo nuevamente. Repetir un identificador fiscal en customer_data devuelve un conflicto. La identidad del titular de la cuenta es distinta de los datos del cliente de facturación. El titular entrega su Registro Federal de Contribuyentes (RFC), el identificador fiscal mexicano. Para una cuenta bancaria, usa su Clave Bancaria Estandarizada (CLABE), el número de cuenta mexicano de 18 dígitos. Las tarjetas de débito usan un número de 16 dígitos.

2. Inscribe un medio de pago por API

Usa este camino cuando recopilas los datos del titular y su consentimiento en tu propia interfaz. Si tu cliente autorizará en el checkout de Fintoc, continúa en Crea una Checkout Session. Envía una sola solicitud multipart/form-data a Crear un medio de pago. Reemplaza cus_000000001 por el ID de tu cliente y las cuatro rutas de archivos por tus archivos locales. El número de cuenta del ejemplo es un dato de prueba publicado para sandbox. Servidor
El endpoint devuelve 201 Created con un medio de pago cuyo mandato está pending. Guarda el id del medio de pago y espera el evento de aprobación antes de cobrarlo. La solicitud de inscripción acepta estos parámetros: Entrega el mandato firmado como contract, una foto del titular con su documento de identidad como selfie y el frente y reverso del documento como id_front e id_back. Cada archivo debe ser PDF, JPEG o PNG, de al menos 100 bytes y menor a 10 MiB (10.485.760 bytes). Fintoc verifica el contenido del archivo en lugar de basarse solo en su extensión. Un documento inválido devuelve 422 y no crea un mandato ni un medio de pago.
Los SDK oficiales de Node y Python no permiten crear medios de pago con archivos. Usa el endpoint HTTP para este paso. No envías consent_source; Fintoc lo asigna según el camino de inscripción.

3. Crea una Checkout Session

Usa este camino cuando tu cliente completará la inscripción en el checkout de Fintoc. Configura payment_method_types explícitamente como ['mx_direct_debit'] o incluye card para ofrecer ambos. La domiciliación está disponible para sesiones setup y subscription en modo test con moneda mxn. No es un medio de pago para sesiones de flujo payment.

Guarda el medio de pago para cargos futuros

Crea una sesión con flow: 'setup'. Inscribe el medio de pago sin crear una suscripción ni cobrarle al cliente. Configura las condiciones del mandato en payment_method_options.mx_direct_debit. Si las omites, max_amount usa 1000000 centavos ($10,000.00 MXN) e interval usa month. Los intervalos admitidos son week, month y year. El ejemplo autoriza hasta $350.00 MXN al mes. Servidor
El endpoint devuelve 201 Created. payment_method es null hasta que el cliente completa la inscripción. Usa redirect_url para abrir el checkout; session_token es null en la respuesta pública de este flujo.

Crea una suscripción con el medio de pago

Crea una sesión con flow: 'subscription'. Fintoc obtiene el límite del mandato de la suma de unit_amount × quantity de cada ítem y el período del mandato de recurring.interval. El ejemplo autoriza $350.00 MXN mensuales. Todos los ítems deben usar el mismo intervalo e interval_count debe ser 1 cuando la domiciliación esté disponible, incluso en sesiones que también ofrecen tarjetas. Usa week, month o year. No envíes condiciones de mandato en payment_method_options para una suscripción. Servidor
El endpoint devuelve 201 Created. payment_method y subscription son null hasta completar la inscripción. customer_data crea el cliente de facturación; no reemplaza los datos del titular que tu cliente ingresa durante el checkout.

4. Redirige a tu cliente al checkout

Entrega redirect_url desde tu backend y redirige el navegador del cliente a esa URL. Mantén tu clave secreta en el servidor.
Client
Tu cliente completa estos pasos en desktop o mobile:
  1. Ingresa el nombre, apellido, correo y RFC del titular.
  2. Continúa por la verificación de identidad, con imágenes del frente y reverso de una credencial del Instituto Nacional Electoral (INE) y una selfie. Sandbox usa documentos simulados.
  3. Ingresa una CLABE o tarjeta de débito y, para tarjeta de débito, selecciona el banco.
  4. Confirma la cuenta y las condiciones del mandato y autoriza la domiciliación.
  5. Ve la confirmación y puede descargar el documento del mandato.
Ten en cuenta estas reglas de la inscripción:
  • Corregir una cuenta que falla la verificación conserva la aprobación de identidad.
  • Una identidad rechazada no crea un mandato ni un medio de pago.
  • La inscripción vence una hora después de que el cliente envía los datos del titular. Avanzar entre pantallas no extiende el plazo, y es distinto del expires_at público de la Checkout Session.
  • Después del vencimiento, el cliente no puede retomar la domiciliación en esa sesión. Puede volver a tu sitio o elegir otro medio de pago si la sesión aún lo permite.
  • Esta entrega no permite repetir la verificación de identidad dentro de la misma sesión.

5. Maneja los eventos de inscripción y mandato

Procesa los webhooks en tu backend en vez de tratar la redirección a success_url como prueba de que puedes cobrar el medio de pago. Los eventos pueden llegar fuera de orden; usa los IDs de los recursos para conciliar el estado guardado. Sigue la guía de verificación y entrega de webhooks. Usa Obtener un medio de pago para conciliar su estado actual. Los valores de mx_direct_debit.status son pending, active, rejected, expired y canceled. Solo active permite cargos. Para suscripciones, sigue Administrar facturas para facturación y cobro. La activación del mandato no confirma por sí sola el pago de la primera factura ni cambia las fechas de facturación de la suscripción.

6. Cobra el medio de pago inscrito

Después de payment_method.activated, usa el ID del medio de pago para crear un cargo bajo demanda o crear una suscripción por API. Una suscripción creada por checkout ya tiene el medio de pago asociado. Los cargos deben usar MXN, estar entre 100 y 99999900 centavos ($1.00 a $999,999.00 MXN) y respetar el límite autorizado restante para el período del mandato. Crear un cargo que excede el límite disponible devuelve limit_exceeded. Un cargo que falla la verificación del límite durante la liquidación informa amount_limit_reached. Crear un cargo y liquidarlo son pasos distintos; procesa los webhooks de resultado del cargo o factura antes de marcar un pedido como pagado.

7. Descarga el documento del mandato

Llama a Obtener el documento del mandato de un medio de pago con tu clave secreta para obtener una URL temporal de descarga. Funciona para ambos caminos de inscripción cuando el contrato está guardado, incluso con el mandato pending. Servidor
download_url vence después de cinco minutos. expires_at es una fecha ISO 8601 en UTC y filename es el nombre del archivo guardado. Solicita una URL nueva cuando la necesites; no guardes la URL como enlace permanente al documento. Los SDK oficiales de Node y Python no exponen este endpoint. Un medio de pago inexistente, otra organización u otro modo de clave de API devuelve 404 con missing_resource. Un medio de pago sin contrato nativo de domiciliación descargable devuelve 422 con invalid_payment_method_state, incluidos los medios de pago legacy de Belvo. Para la inscripción por checkout, Fintoc envía un correo de confirmación al correo de cliente resuelto por la Checkout Session al completar la inscripción, salvo que tu configuración de marca suprima los correos de comprobantes. El correo del titular ingresado en el widget no reemplaza ese destinatario. El correo de confirmación no prueba que el mandato esté active. El widget también permite descargar el documento; no ofrece una acción para enviar el correo manualmente.

8. Prueba la integración

Usa tu clave secreta test y los datos de prueba siguientes. Ejecuta la inscripción por API con archivos locales de muestra o crea una Checkout Session y complétala en desktop y mobile. Verifica los recursos devueltos y los webhooks recibidos, además de la pantalla de confirmación.

Simula la verificación de identidad en checkout

Estos RFC aplican al camino por Checkout Session. La inscripción por API acepta los documentos de consentimiento que entregas y no ejecuta el simulador de identidad del checkout. Los últimos tres caracteres seleccionan el caso. Usa un RFC individual de 13 caracteres con formato válido. Esta entrega no permite reintentar la verificación de identidad dentro de la misma Checkout Session.

Simula la verificación de cuenta en checkout

Usa la CLABE 012180000000083333 para obtener account_not_validated antes de crear un mandato. Corrige la cuenta a 012180000000000015 y continúa sin repetir la verificación de identidad. Los números de cuenta con formato o dígito verificador inválidos y los bancos no admitidos se rechazan antes de la inscripción. El sufijo 3333 aplica a la verificación de cuenta en checkout. No es un caso de rechazo de mandato para la inscripción por API.

Simula resultados de mandato en ambos caminos

Usa los siguientes números de cuenta publicados para sandbox. Para tarjeta de débito, selecciona o envía mx_banco_bbva como banco emisor. Los mandatos devuelven primero pending y luego se resuelven de forma asíncrona. El plazo de resolución en sandbox usa cinco segundos por defecto; considera tiempo adicional para la entrega del webhook. Las CLABEs terminadas en 1111 simulan rechazo y las terminadas en 8888 simulan falta de respuesta del banco y vencimiento. Las tarjetas de débito terminadas en 0335 simulan rechazo. Las otras cuentas válidas se aprueban, salvo las fallas de verificación de cuenta en checkout. Una tarjeta de débito terminada en 1111 se aprueba; no usa la regla de rechazo de CLABE.

Simula cargos

Cuando el medio de pago esté active, crea un cargo dentro del límite del mandato. Los montos válidos de al menos 500 centavos de MXN ($5.00 MXN) se aprueban; los montos entre 100 y 499 simulan insufficient_funds. La resolución es asíncrona y usa cinco segundos por defecto en sandbox. Verifica el resultado del cargo en lugar de solo la respuesta de creación. Verifica también que un cargo que exceda el límite autorizado restante del mandato se rechace con limit_exceeded y que no se pueda cobrar un mandato pending, rejected, expired o canceled.

Próximos pasos