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.
- Prepara tu integración
Usa una secret key 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.
Para el camino por API, el cliente debe tener email y phone. Si le falta alguno, la inscripción devuelve 422 Unprocessable Entity con customer_contact_required. La API no actualiza clientes, así que si un cliente existente no tiene alguno de esos campos, crea un cliente nuevo con ambos y usa su ID. Si el cliente existente tiene identificador fiscal, omite tax_id en el cliente nuevo para evitar el conflicto y envía el RFC del titular en mx_direct_debit.account_holder.rfc.
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.
Prepara la inscripción en live
Contacta a Fintoc para habilitar la domiciliación mexicana en tu organización antes de usar una secret key de live. Fintoc habilita la inscripción live y los cargos live de tu organización, y puede habilitarlos en momentos distintos. Mientras cada uno no esté habilitado, sus solicitudes live devuelven 400 Bad Request con not_supported_mode.
La inscripción live acepta solo una CLABE de un banco compatible. Una tarjeta de débito, o una cuenta de un banco no compatible, devuelve 422 con invalid_account_for_direct_debit. Los ejemplos de esta guía usan claves de test y datos de prueba de sandbox; en live, envía la CLABE autorizada de tu cliente y sus documentos de consentimiento.
- 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 en sandbox.
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 y el RFC del ejemplo son datos de prueba publicados para sandbox.
Servidor
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.
En modo live, Fintoc rechaza la inscripción cuando el RFC del titular o la cuenta está bloqueado para domiciliación. La solicitud devuelve 422 con el código de error account_blocked_for_direct_debit y no crea un mandato ni un medio de pago. Fintoc no hace esta verificación en modo test.
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.
- Crea una Checkout Session en sandbox
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 conflow: '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
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 conflow: '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
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.
- Redirige a tu cliente al checkout
Entrega redirect_url desde tu backend y redirige el navegador del cliente a esa URL. Mantén tu secret key en el servidor.
Client
- Ingresa el nombre, apellido, correo y RFC del titular.
- 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.
- Ingresa una CLABE o tarjeta de débito y, para tarjeta de débito, selecciona el banco.
- Confirma la cuenta y las condiciones del mandato y autoriza la domiciliación.
- Ve la confirmación y puede descargar el documento del mandato.
- 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_atpú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.
- 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.
Espera la verificación del mandato live
Un mandato live permanece pending mientras Fintoc lo verifica. Crear el medio de pago no aprueba el mandato. Fintoc hace tres verificaciones:
- Cuenta: Fintoc envía una transferencia de verificación a la CLABE y compara el RFC y el nombre del comprobante de la transferencia con el titular declarado.
- Identidad: Fintoc revisa el documento de identidad y la selfie contra el titular declarado.
- Contrato: Fintoc revisa que el mandato esté firmado y coincida con el titular y los términos del mandato de tu solicitud.
active y Fintoc envía payment_method.activated. Si una verificación falla, el mandato pasa a rejected. Si la verificación no termina antes del plazo de aprobación, el mandato pasa a expired con verification_expired. En ambos casos Fintoc envía payment_method.canceled; consulta la causa en mx_direct_debit.error_reason, según los motivos de error de MX Direct Debit. La verificación live no tiene una duración fija.
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.
- 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 y respetar el límite autorizado restante del mandato para el período actual. Fintoc rechaza un cargo al crearlo con 422 Unprocessable Entity y uno de estos códigos:
Crear un cargo y obtener su resultado son pasos distintos. Procesa los webhooks de resultado del pago o la factura antes de marcar un pedido como pagado. Si el banco rechaza un cargo por exceder un límite, el cargo falla con
amount_limit_reached.
Espera el resultado del cargo live
Una respuesta exitosa al crear el cargo significa que Fintoc lo aceptó, no que el banco debitó la cuenta. Fintoc envía los cargos live al banco una vez cada día hábil a las 14:00, hora de Ciudad de México. Los cargos creados desde las 14:00 esperan el envío del siguiente día hábil. El banco suele devolver el resultado el día hábil posterior al envío, y puede tardar más.
Fintoc hace fallar un cargo antes del envío si su mandato ya no está active o si Fintoc suspendió la domiciliación de tu organización. Algunas fallas del banco, como una cuenta cerrada o un mandato revocado, también cancelan el mandato y disparan payment_method.canceled. Fintoc no reintenta automáticamente un cargo de domiciliación fallido, tampoco los cargos de facturas de suscripción. Crea otro cargo o sigue Administrar facturas para cobrar una factura fallida.
Maneja los contracargos live
Los contracargos de domiciliación no tienen proceso de defensa. Fintoc crea el Dispute como perdido, envía solo dispute.lost y no solicita documentos de respaldo. El objeto Dispute tiene payment_method_type con valor mx_direct_debit y documentation_upload_deadline con valor null. Usa Obtener una disputa para conciliar el reverso.
Un contracargo bloquea el RFC del titular y la cuenta para la domiciliación live con todos los comercios. Fintoc cancela los mandatos live pending y active que coincidan y envía payment_method.canceled con mx_direct_debit.error_reason igual a chargeback a cada comercio afectado. Las nuevas inscripciones con ese RFC o esa cuenta devuelven account_blocked_for_direct_debit.
Fintoc monitorea la tasa de contracargos de tu organización. Si la tasa supera el umbral que Fintoc definió para tu organización, Fintoc suspende la domiciliación: los nuevos mandatos y cargos live devuelven direct_debit_suspended, y los cargos que aún no se envían al banco fallan con el mismo motivo.
- Descarga el documento del mandato
Llama a Obtener el documento del mandato de un medio de pago con tu secret key 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.
- Prueba la integración
Sandbox y live comparten el flujo de API, pero difieren en la verificación y la liquidación:
Usa tu secret key de
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 fecha y dígito verificador válidos. 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 CLABE012180000000083333 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íamx_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 Fintoc rechace con mandate_limit_exceeded un cargo que exceda el límite autorizado restante del mandato. Cobrar un mandato pending, rejected o expired devuelve payment_method_inactive, y cobrar un mandato canceled devuelve payment_method_canceled.