Acepta pagos por Direct Debit en México

Direct Debit en México (domiciliación bancaria) te permite cobrar automáticamente las cuentas bancarias y tarjetas de débito de tus clientes. El cliente autoriza un mandato una sola vez. Después de que Fintoc aprueba el mandato, puedes cobrar la cuenta de forma recurrente o on-demand sin más acciones por parte del cliente. A diferencia de otros métodos de pago, Direct Debit tiene un paso de aprobación asíncrono: después de la enrolación, el mandato queda en revisión durante aproximadamente un día hábil. El payment_method se puede cobrar solo cuando el mandato es aprobado. Puedes enrolar un payment method de dos maneras:

Por API (merchant-hosted): recolectas los datos de la cuenta y los documentos de consentimiento de tu cliente en tu propia UI y los envías a Fintoc en una única request.
A través del checkout hosteado por Fintoc: creas un Checkout Session y rediriges a tu cliente, y Fintoc se encarga del flujo completo de enrolación, incluyendo la validación de identidad y el documento de mandato.

Aceptar pagos por Direct Debit toma cuatro pasos:

Crear un Customer, usando tu Secret Key
Enrolar el payment method, por API o a través de un Checkout Session
Manejar los eventos de aprobación del mandato a través de webhooks
Cobrar la cuenta enrolada, con invoices de suscripción o charges on-demand

Antes de empezar

Direct Debit está disponible para organizaciones que operan en México. Antes de integrar, asegúrate de tener:

Una cuenta Fintoc con Direct Debit México habilitado
Una Secret Key y Public Key
Un endpoint de webhooks para recibir los eventos de mandato y pagos

Todas las operaciones de Direct Debit usan MXN.

Cómo funciona el mandato

Cada enrolación crea un mandato: la autorización del cliente para que cobres su cuenta. El mandato define:

Concepto	Descripción
`max_amount`	El monto máximo que puedes cobrar por período de facturación, en centavos MXN. Esto es lo que el cliente autoriza.
`interval`	El período de facturación de la autorización: `week`, `month` o `year`.
`status`	`pending` (esperando aprobación), `active` (cobrable), `rejected` (el banco rechazó el mandato), `expired` (no llegó confirmación a tiempo) o `canceled` (revocado).

Fintoc valida el límite del mandato en cada cobro. Si un cobro excedería el max_amount del período actual, Fintoc rechaza el cobro con limit_exceeded antes de que llegue al banco del cliente.

Paso 1: Crear un Customer

Cada payment method de Direct Debit pertenece a un Customer. Para Direct Debit, el customer necesita un nombre completo, un email y un tax ID mexicano (mx_rfc).

curl --request POST "https://api.fintoc.com/v2/customers" \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Felipe Castro",
    "email": "felipe@example.com",
    "tax_id": {
      "type": "mx_rfc",
      "value": "AAAA010101AAA"
    },
    "metadata": {}
  }'

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_KEY');

const customer = await fintoc.v2.customers.create({
  name: 'Felipe Castro',
  email: 'felipe@example.com',
  tax_id: {
    type: 'mx_rfc',
    value: 'AAAA010101AAA',
  },
  metadata: {},
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_KEY')

customer = client.v2.customers.create(
    name='Felipe Castro',
    email='felipe@example.com',
    tax_id={
        'type': 'mx_rfc',
        'value': 'AAAA010101AAA',
    },
    metadata={},
)

{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  "created_at": "2026-08-10T15:22:11.474Z",
  "mode": "test",
  "name": "Felipe Castro",
  "email": "felipe@example.com",
  "tax_id": {
    "type": "mx_rfc",
    "value": "AAAA010101AAA"
  },
  "metadata": {}
}

Fintoc devuelve el Customer creado. Guarda su id para enrolar un payment_method para él en el siguiente paso.

Paso 2, Opción 1: Enrolar por API (merchant-hosted)

Usa esta opción cuando recolectas los datos de la cuenta y los documentos de consentimiento en tu propia UI. Envía los datos de la cuenta, el límite autorizado del mandato y cuatro documentos de consentimiento como archivos en una única request multipart/form-data:

curl --request POST "https://api.fintoc.com/v2/payment_methods" \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --form "type=mx_direct_debit" \
  --form "customer=cus_NffrFeUfNV2Hib" \
  --form "mx_direct_debit[account_type]=clabe" \
  --form "mx_direct_debit[account_number]=000000000000000000" \
  --form "mx_direct_debit[max_amount]=35000" \
  --form "mx_direct_debit[interval]=month" \
  --form "mx_direct_debit[consent_documents][contract]=@signed_contract.pdf" \
  --form "mx_direct_debit[consent_documents][selfie]=@selfie.jpg" \
  --form "mx_direct_debit[consent_documents][id_front]=@ine_front.jpg" \
  --form "mx_direct_debit[consent_documents][id_back]=@ine_back.jpg"

const fs = require('fs');

const paymentMethod = await fintoc.v2.paymentMethods.create({
  type: 'mx_direct_debit',
  customer: 'cus_NffrFeUfNV2Hib',
  mx_direct_debit: {
    account_type: 'clabe',
    account_number: '000000000000000000',
    max_amount: 35000,
    interval: 'month',
    consent_documents: {
      contract: fs.createReadStream('signed_contract.pdf'),
      selfie: fs.createReadStream('selfie.jpg'),
      id_front: fs.createReadStream('ine_front.jpg'),
      id_back: fs.createReadStream('ine_back.jpg'),
    },
  },
});

with open('signed_contract.pdf', 'rb') as contract, \
     open('selfie.jpg', 'rb') as selfie, \
     open('ine_front.jpg', 'rb') as id_front, \
     open('ine_back.jpg', 'rb') as id_back:
    payment_method = client.v2.payment_methods.create(
        type='mx_direct_debit',
        customer='cus_NffrFeUfNV2Hib',
        mx_direct_debit={
            'account_type': 'clabe',
            'account_number': '000000000000000000',
            'max_amount': 35000,
            'interval': 'month',
            'consent_documents': {
                'contract': contract,
                'selfie': selfie,
                'id_front': id_front,
                'id_back': id_back,
            },
        },
    )

{
  "id": "pm_NffrFeUfNV2Hib",
  "object": "payment_method",
  "created_at": "2026-08-10T15:22:11.474Z",
  "customer": "cus_NffrFeUfNV2Hib",
  "mode": "test",
  "mx_direct_debit": {
    "account_type": "clabe",
    "institution_id": "mx_banco_santander",
    "interval": "month",
    "last_four_digits": "0000",
    "max_amount_cents": 35000,
    "max_amount_currency": "MXN",
    "status": "pending"
  },
  "type": "mx_direct_debit"
}

La request de enrolación merchant-hosted acepta estos parámetros:

Parámetro	Tipo	Requerido	Descripción
`type`	string	Sí	`mx_direct_debit`.
`customer`	string	Sí	ID del `Customer`. Debe tener un nombre completo, un `tax_id` de tipo `mx_rfc` y un `email`.
`mx_direct_debit.account_type`	string	Sí	`clabe` o `debit_card`.
`mx_direct_debit.account_number`	string	Sí	Para `clabe`, los 18 dígitos del número de cuenta bancaria mexicana estandarizado (CLABE). Para `debit_card`, los 16 dígitos del número de la tarjeta, que debe pasar la validación de Luhn.
`mx_direct_debit.institution_id`	string	Condicional	Institución que emitió la cuenta. Requerido cuando `account_type` es `debit_card`. Se ignora para `clabe`, donde los primeros tres dígitos del número de cuenta identifican al banco.
`mx_direct_debit.max_amount`	integer	Sí	Monto máximo por período de facturación, en centavos MXN. Debe coincidir con el monto autorizado en el contrato firmado.
`mx_direct_debit.interval`	string	Sí	Período de facturación de la autorización: `week`, `month` o `year`.
`mx_direct_debit.consent_documents.contract`	string	Sí	Contrato de autorización firmado, siguiendo el formato oficial del mandato. Archivo binario (`multipart/form-data`): JPEG, PNG o PDF, entre 100 bytes y 10 MB.
`mx_direct_debit.consent_documents.selfie`	string	Sí	Selfie del cliente, idealmente sosteniendo su credencial del Instituto Nacional Electoral (INE). Archivo binario (`multipart/form-data`): JPEG, PNG o PDF, entre 100 bytes y 10 MB.
`mx_direct_debit.consent_documents.id_front` / `id_back`	string	Sí	Anverso y reverso de la INE del cliente. Archivo binario (`multipart/form-data`): JPEG, PNG o PDF, entre 100 bytes y 10 MB.
`metadata`	object	No	Objeto llave-valor para datos del merchant.

Fintoc devuelve el payment_method creado con el mandato ya en revisión. Revisa la referencia de Crear un payment method para ver todos los parámetros y errores del endpoint. La request es atómica. Si falta un documento o un archivo tiene un formato o tamaño inválido, Fintoc devuelve 422 Unprocessable Entity y no crea ningún payment_method.

Un payment_method no se puede editar después de creado. Si los documentos de consentimiento son rechazados o están incompletos, Fintoc cancela el método (payment_method.canceled) y debes crear un nuevo payment_method con los documentos corregidos.

Paso 2, Opción 2: Enrolar a través del checkout hosteado por Fintoc

Usa esta opción para dejar que Fintoc maneje el flujo completo de enrolación. Tu cliente completa sus datos personales, ingresa su CLABE o tarjeta de débito, autoriza el mandato y completa la validación de identidad en la página hosteada por Fintoc. Fintoc genera el documento de mandato firmado por ti. El checkout hosteado admite dos flujos:

flow: subscription enrola el payment method y empieza una suscripción recurrente en un solo paso. Fintoc programa y cobra los invoices de cada ciclo de facturación automáticamente.
flow: setup solo enrola el payment method, sin cobros programados. Úsalo cuando quieras guardar la cuenta y decidir después cuándo y cuánto cobrar (invoices on-demand, ver Paso 4).

Crea un Checkout Session con flow: subscription para enrolar y empezar una suscripción recurrente en un solo paso:

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "flow": "subscription",
    "amount": 35000,
    "currency": "MXN",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/cancel",
    "payment_method_types": ["mx_direct_debit"],
    "customer_data": {
      "tax_id": {
        "type": "mx_rfc",
        "value": "AAAA010101AAA"
      },
      "name": "Felipe Castro",
      "email": "felipe@example.com",
      "metadata": {}
    },
    "line_items": [
      {
        "price_data": {
          "currency": "MXN",
          "unit_amount": 35000,
          "product_data": {
            "name": "Plan 1"
          },
          "recurring": {
            "interval": "month",
            "interval_count": 1
          }
        },
        "quantity": 1
      }
    ],
    "metadata": {}
  }'

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'subscription',
  amount: 35000,
  currency: 'MXN',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  payment_method_types: ['mx_direct_debit'],
  customer_data: {
    tax_id: { type: 'mx_rfc', value: 'AAAA010101AAA' },
    name: 'Felipe Castro',
    email: 'felipe@example.com',
    metadata: {},
  },
  line_items: [
    {
      price_data: {
        currency: 'MXN',
        unit_amount: 35000,
        product_data: { name: 'Plan 1' },
        recurring: { interval: 'month', interval_count: 1 },
      },
      quantity: 1,
    },
  ],
  metadata: {},
});

checkout_session = client.v2.checkout_sessions.create(
    flow='subscription',
    amount=35000,
    currency='MXN',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    payment_method_types=['mx_direct_debit'],
    customer_data={
        'tax_id': {'type': 'mx_rfc', 'value': 'AAAA010101AAA'},
        'name': 'Felipe Castro',
        'email': 'felipe@example.com',
        'metadata': {},
    },
    line_items=[
        {
            'price_data': {
                'currency': 'MXN',
                'unit_amount': 35000,
                'product_data': {'name': 'Plan 1'},
                'recurring': {'interval': 'month', 'interval_count': 1},
            },
            'quantity': 1,
        },
    ],
    metadata={},
)

{
  "id": "cs_JiFtR3vBhK5nQm7",
  "object": "checkout_session",
  "flow": "subscription",
  "amount": 35000,
  "currency": "MXN",
  "status": "created",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_JiFtR3vBhK5nQm7",
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "payment_method_types": ["mx_direct_debit"],
  "customer": "cus_NffrFeUfNV2Hib",
  "subscription": "sub_L2pXm4KnQ7bYwR9",
  "payment_method": null,
  "metadata": {}
}

Fintoc devuelve el Checkout Session creado. Usa su redirect_url para enviar a tu cliente al checkout hosteado. Con flow configurado como subscription, Fintoc deriva el max_amount y el interval del mandato a partir de line_items: unit_amount multiplicado por quantity, y recurring.interval. Para crear el payment method sin cobros programados, configura flow como setup. Las sesiones setup no tienen line_items para definir el monto máximo, pero puedes enviar el límite del mandato en payment_method_options. Si omites payment_method_options, Fintoc crea el mandato con un límite predeterminado de MXN 10.000 por mes (max_amount: 1000000, interval: "month").

{
  "flow": "setup",
  "currency": "MXN",
  "payment_method_types": ["mx_direct_debit"],
  "payment_method_options": {
    "mx_direct_debit": {
      "max_amount": 500000,
      "interval": "month"
    }
  }
}

Redirige a tu cliente al redirect_url de la sesión. En la página hosteada, el cliente completa cinco pasos:

Datos personales: nombre, número del Registro Federal de Contribuyentes (RFC) y email, precargados desde customer_data.
Enrolación de la cuenta: CLABE o tarjeta de débito.
Autorización del mandato: documento completo del mandato.
Validación de identidad: selfie e INE.
Confirmación.

Después de que el checkout termina, la enrolación no está completa: el mandato queda en revisión y mx_direct_debit.status sigue en pending. No actives el servicio de tu cliente hasta recibir payment_method.activated.

Paso 3: Manejar los eventos de aprobación del mandato

Fintoc revisa el mandato de forma asíncrona y envía la aprobación aproximadamente un día hábil después de la enrolación. Usa siempre webhooks para monitorear el resultado:

Evento	Cuándo	Acción recomendada
`checkout_session.finished`	El checkout hosteado terminó. Incluye el `payment_method` con `mx_direct_debit.status` en `pending` y, para `subscription`, la suscripción (`incomplete`).	Guarda los IDs. No actives el servicio aún.
`checkout_session.expired`	La sesión expiró antes de completarse.	Ofrece al cliente un nuevo intento.
`payment_method.activated`	El mandato fue aprobado. `mx_direct_debit.status` ahora está en `active` y el método es cobrable.	Activa el servicio y empieza a cobrar.
`payment_method.canceled`	El mandato fue rechazado, los documentos estaban incompletos, el mandato expiró sin confirmación o el método fue revocado.	Enrola de nuevo al cliente con un nuevo `payment_method`.

Cuando el mandato es aprobado para un flujo subscription, la suscripción pasa a active y Fintoc genera y cobra el primer invoice automáticamente.

Paso 4: Cobrar la cuenta enrolada

Con mx_direct_debit.status en active, puedes cobrar el payment_method de dos maneras:

Suscripción: Fintoc genera un invoice por cada ciclo de facturación y cobra el invoice automáticamente contra la cuenta enrolada. Maneja los eventos invoice.payment_succeeded e invoice.payment_failed.
On-demand: creas un invoice puntual asociado al payment method.

curl --request POST "https://api.fintoc.com/v2/invoices" \
  --header 'Authorization: YOUR_TEST_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": "cus_NffrFeUfNV2Hib",
    "default_payment_method": "pm_NffrFeUfNV2Hib",
    "lines": [
      {
        "amount": 15000,
        "currency": "MXN",
        "name": "Monthly service",
        "quantity": 1
      }
    ],
    "metadata": {
      "order_id": "order_98765"
    }
  }'

const invoice = await fintoc.v2.invoices.create({
  customer: 'cus_NffrFeUfNV2Hib',
  default_payment_method: 'pm_NffrFeUfNV2Hib',
  lines: [
    {
      amount: 15000,
      currency: 'MXN',
      name: 'Monthly service',
      quantity: 1,
    },
  ],
  metadata: { order_id: 'order_98765' },
});

invoice = client.v2.invoices.create(
    customer='cus_NffrFeUfNV2Hib',
    default_payment_method='pm_NffrFeUfNV2Hib',
    lines=[
        {
            'amount': 15000,
            'currency': 'MXN',
            'name': 'Monthly service',
            'quantity': 1,
        },
    ],
    metadata={'order_id': 'order_98765'},
)

{
  "id": "inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe",
  "object": "invoice",
  "attempt_count": 0,
  "collection_method": "charge_automatically",
  "created_at": "2026-08-10T15:22:11.474Z",
  "currency": "MXN",
  "customer": "cus_NffrFeUfNV2Hib",
  "default_payment_method": "pm_NffrFeUfNV2Hib",
  "external_payment": false,
  "hosted_invoice_url": null,
  "lines": [
    {
      "id": "il_2bVdX0PqJs6RhNu9FmZlTo2EyKq",
      "object": "line_item",
      "name": "Monthly service",
      "description": null,
      "amount": 15000,
      "currency": "MXN",
      "period_end": null,
      "period_start": null,
      "quantity": 1
    }
  ],
  "metadata": { "order_id": "order_98765" },
  "mode": "test",
  "next_payment_attempt_at": null,
  "payments": [],
  "status": "draft",
  "subscription": null,
  "total": 15000
}

Fintoc devuelve el invoice creado en su estado inicial draft. Una vez que finalizas el invoice, Fintoc lo cobra automáticamente contra default_payment_method. Monitorea el resultado con invoice.payment_succeeded o invoice.payment_failed (enviados junto con payment_intent.succeeded o payment_intent.failed).

Validación del límite del mandato. Antes de que Fintoc ejecute un cobro, Fintoc suma el monto del cobro con cualquier monto ya cobrado o en curso del período actual. Luego Fintoc compara ese total contra el max_amount del mandato. Fintoc rechaza los cobros que exceden el límite con 422 limit_exceeded antes de que el cobro llegue al banco del cliente. Los cobros fallidos no consumen el límite. El uso se resetea al inicio de cada período.

Reglas y validaciones

Usa estos errores de validación para manejar fallas específicas de Direct Debit:

Código	Significado
`payment_method_inactive`	`mx_direct_debit.status` está en `pending`, `rejected`, `expired` o `canceled`. Solo un mandato `active` se puede cobrar.
`limit_exceeded`	El cobro excedería el `max_amount` del mandato para el período actual.
`422` al crear la sesión	`mx_direct_debit` con una moneda distinta de `MXN`, o la organización no tiene Direct Debit habilitado.
`422` al crear el método	Falta un documento de consentimiento o tiene un formato o tamaño inválido. La request es atómica: no se crea nada.

Prueba tu integración

Usando tu Secret Key en modo test, puedes simular el flujo completo de Direct Debit sin mover dinero. En modo test, Fintoc aprueba o rechaza el mandato en aproximadamente 1 minuto en lugar de un día hábil. Un mandato creado con una CLABE terminada en 8888 nunca recibe confirmación del banco, y Fintoc expira el mandato a los 7 días. CLABE (18 dígitos). Solo los últimos cuatro dígitos actúan como gatillo. Los ejemplos usan Santander, y cualquier banco soportado se comporta de la misma manera:

CLABE	Resultado
`014180000000041111`	Mandato rechazado: Fintoc envía `payment_method.canceled` y `mx_direct_debit.status` pasa a `rejected` ~1 minuto después de la enrolación.
`014180000000082222`	Falla dentro del flujo con reintento (solo en el checkout hosteado): la validación de identidad falla en el primer intento y permite que tu cliente reintente.
`014180000000028888`	Mandato pendiente y luego expirado: `mx_direct_debit.status` queda en `pending` mientras no llega ninguna confirmación del banco. A los 7 días, Fintoc expira el mandato, envía `payment_method.canceled` y `mx_direct_debit.status` pasa a `expired`.

Para obtener un mandato aprobado, usa cualquier CLABE que no termine en uno de esos gatillos, como 014180000000014821. Tarjeta de débito (16 dígitos). El número de tarjeta controla el resultado del mandato:

Número de tarjeta	Resultado
`4111111111111111`	Mandato aprobado: `mx_direct_debit.status` pasa a `active` ~1 minuto después de la enrolación.
`4574441215190335`	Mandato rechazado: Fintoc envía `payment_method.canceled` y `mx_direct_debit.status` pasa a `rejected` ~1 minuto después de la enrolación.

Charges. El monto controla el resultado, y el resultado llega por webhook 5 a 15 minutos después del cobro:

Monto (centavos MXN)	Resultado
`>= 500`	`succeeded`
`< 500`	`failed`

En modo live la validación de identidad es real y puede rechazar a tu cliente. Asegúrate de que tu integración maneje el estado pending y el evento payment_method.canceled antes de pasar a producción.

​Antes de empezar

​Cómo funciona el mandato

​Paso 1: Crear un Customer

​Paso 2, Opción 1: Enrolar por API (merchant-hosted)

​Paso 2, Opción 2: Enrolar a través del checkout hosteado por Fintoc

​Paso 3: Manejar los eventos de aprobación del mandato

​Paso 4: Cobrar la cuenta enrolada

​Reglas y validaciones

​Prueba tu integración

Antes de empezar

Cómo funciona el mandato

Paso 1: Crear un Customer

Paso 2, Opción 1: Enrolar por API (merchant-hosted)

Paso 2, Opción 2: Enrolar a través del checkout hosteado por Fintoc

Paso 3: Manejar los eventos de aprobación del mandato

Paso 4: Cobrar la cuenta enrolada

Reglas y validaciones

Prueba tu integración