Accept direct debit payments in Mexico

Enroll your customer’s Mexican bank account or debit card, then use the resulting payment method for subscriptions or on-demand charges.

Mexican direct debit (mx_direct_debit) is available in test mode. Sandbox simulates identity verification, account verification, mandate approval, and charges. It does not verify real identity documents or move money. This guide describes the sandbox integration.

Choose how your customer authorizes the payment method:

Responsibility	By API	By Checkout Session
Customer interaction	You collect the account details and consent documents in your own interface.	Your customer completes enrollment at Fintoc’s checkout.
Your backend	Sends `POST /v2/payment_methods` with the details and four files.	Sends `POST /v2/checkout_sessions` and returns `redirect_url` to your frontend.
Identity and consent	You provide the account holder’s details and evidence of consent.	Fintoc handles the identity steps and generates the mandate document.
Result	A `PaymentMethod` with a `pending` mandate.	A `finished` Checkout Session with a payment method, and a subscription when `flow` is `subscription`. The mandate starts as `pending`.
Consent source	Fintoc sets `mx_direct_debit.consent_source` to `api`.	Fintoc sets `mx_direct_debit.consent_source` to `checkout`.

Both paths require asynchronous mandate approval before you can charge the payment method. Completing checkout is different from receiving approval.

1. Prepare your integration

Use a test secret API key on your server and configure webhooks to receive enrollment and payment results. Checkout Sessions for this payment method require an organization configured for Mexico and currency mxn. Send Fintoc-Version: 2026-02-01 on API requests. The Node examples use the official fintoc SDK, and the Python examples use the official fintoc package. The Node SDK uses your organization’s default API version, which must be 2026-02-01 or later for these examples. See Authentication for API version selection. Every payment method belongs to a Customer. For the API path, create a customer first and use its id. For Checkout Sessions, send an existing customer ID or customer_data to create one during session creation. The examples below use customer_data. For later sessions with the same billing customer, send its customer ID instead of creating it again. Repeating a tax ID in customer_data returns a conflict. The account holder’s identity is separate from the billing customer’s details. The holder provides a Mexican tax ID (RFC). For a bank account, use its 18-digit standardized Mexican bank account number (CLABE). Debit cards use a 16-digit number.

2. Enroll a payment method by API

Use this path when you collect the holder’s details and consent in your own interface. If your customer will authorize in Fintoc’s checkout, skip to Create a Checkout Session. Send one multipart/form-data request to Create a payment method. Replace cus_000000001 with your customer’s ID and the four file paths with your local files. The account number in this example is a published sandbox fixture. Server

curl --request POST "https://api.fintoc.com/v2/payment_methods" \
  --header "Authorization: YOUR_TEST_SECRET_KEY" \
  --header "Fintoc-Version: 2026-02-01" \
  --form "type=mx_direct_debit" \
  --form "customer=cus_000000001" \
  --form "mx_direct_debit[account_number]=012180000000000015" \
  --form "mx_direct_debit[account_type]=clabe" \
  --form "mx_direct_debit[interval]=month" \
  --form "mx_direct_debit[max_amount]=35000" \
  --form "mx_direct_debit[account_holder][name]=Test Customer 1" \
  --form "mx_direct_debit[account_holder][email]=test.customer.1@example.com" \
  --form "mx_direct_debit[account_holder][rfc]=AAAA010101AAA" \
  --form "mx_direct_debit[consent_documents][contract]=@contract.pdf" \
  --form "mx_direct_debit[consent_documents][selfie]=@selfie.jpg" \
  --form "mx_direct_debit[consent_documents][id_front]=@id_front.jpg" \
  --form "mx_direct_debit[consent_documents][id_back]=@id_back.jpg"

{
  "id": "pm_000000001",
  "object": "payment_method",
  "created_at": "2026-10-08T12:00:00Z",
  "customer": "cus_000000001",
  "mode": "test",
  "mx_direct_debit": {
    "account_holder_id": "AAAA010101AAA",
    "account_number_last4": "0015",
    "account_type": "clabe",
    "consent_source": "api",
    "institution": {
      "id": "mx_banco_bbva",
      "country": "mx",
      "name": "Banco BBVA"
    },
    "interval": "month",
    "max_amount": 35000,
    "status": "pending"
  },
  "type": "mx_direct_debit"
}

The endpoint returns 201 Created with a payment method whose mandate is pending. Save the payment method id and wait for the approval event before charging it. The enrollment request accepts these parameters:

Parameter	Requirement	Description
`customer`	Required	Customer ID in the same organization and API key mode.
`mx_direct_debit.account_number`	Required	CLABE with 18 digits and a valid checksum, or debit card number with 16 digits and a valid Luhn checksum.
`mx_direct_debit.account_type`	Required	`clabe` or `debit_card`.
`mx_direct_debit.institution_id`	Required if `account_type` is `debit_card`	Supported issuing bank ID. Fintoc derives the bank from a CLABE and ignores this field for `clabe`.
`mx_direct_debit.interval`	Required	Authorization period: `week`, `month`, or `year`.
`mx_direct_debit.max_amount`	Required	Authorized limit in MXN cents. Must be a positive integer. `35000` means $350.00 MXN.
`mx_direct_debit.account_holder`	Optional	Holder’s `name`, `email`, and `rfc`. Each omitted field uses the matching Customer field. The RFC defaults from the Customer only when its tax ID type is `mx_rfc`.
`mx_direct_debit.consent_documents`	Required	Four files: `contract`, `selfie`, `id_front`, and `id_back`.

Provide the signed mandate as contract, a photo of the holder with their identity document as selfie, and the front and back of that document as id_front and id_back. Each file must be a PDF, JPEG, or PNG, at least 100 bytes and smaller than 10 MiB (10,485,760 bytes). Fintoc checks the file content instead of relying only on the extension. An invalid document returns 422 and creates neither a mandate nor a payment method.

The official Node and Python SDKs do not expose payment method creation with file uploads. Use the HTTP endpoint for this step. You do not send consent_source; Fintoc assigns it from the enrollment path.

3. Create a Checkout Session

Use this path when your customer will complete enrollment in Fintoc’s checkout. Set payment_method_types explicitly to ['mx_direct_debit'], or include card to offer both. Direct debit is available for setup and subscription sessions in test mode with mxn currency. It is not a payment method for payment flow sessions.

Save the payment method for future charges

Create a session with flow: 'setup'. This enrolls the payment method without creating a subscription or charging the customer. Set the mandate terms in payment_method_options.mx_direct_debit. If you omit them, max_amount defaults to 1000000 cents ($10,000.00 MXN) and interval defaults to month. Supported intervals are week, month, and year. The example authorizes up to $350.00 MXN per month. Server

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_KEY" \
  --header "Fintoc-Version: 2026-02-01" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "flow": "setup",
  "currency": "mxn",
  "payment_method_types": [
    "mx_direct_debit"
  ],
  "customer_data": {
    "name": "Test Customer 1",
    "email": "test.customer.1@example.com"
  },
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "payment_method_options": {
    "mx_direct_debit": {
      "max_amount": 35000,
      "interval": "month"
    }
  }
}'

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

const fintoc = new Fintoc('YOUR_TEST_SECRET_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'setup',
  currency: 'mxn',
  payment_method_types: ['mx_direct_debit'],
  customer_data: {
    name: 'Test Customer 1',
    email: 'test.customer.1@example.com',
  },
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  payment_method_options: {
    mx_direct_debit: {
      max_amount: 35000,
      interval: 'month',
    },
  },
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_KEY', api_version='2026-02-01')

checkout_session = client.v2.checkout_sessions.create(
    flow="setup",
    currency="mxn",
    payment_method_types=[
        "mx_direct_debit"
    ],
    customer_data={
        "name": "Test Customer 1",
        "email": "test.customer.1@example.com"
    },
    success_url="https://example.com/success",
    cancel_url="https://example.com/cancel",
    payment_method_options={
        "mx_direct_debit": {
            "max_amount": 35000,
            "interval": "month"
        }
    },
)

{
  "id": "cs_000000001",
  "object": "checkout_session",
  "amount": null,
  "business_profile": null,
  "cancel_url": "https://example.com/cancel",
  "created_at": "2026-10-08T12:00:00Z",
  "currency": "MXN",
  "customer": {
    "id": "cus_000000001",
    "object": "customer",
    "address": null,
    "created_at": "2026-10-08T12:00:00Z",
    "email": "test.customer.1@example.com",
    "metadata": {},
    "mode": "test",
    "name": "Test Customer 1",
    "phone": null,
    "tax_id": null
  },
  "customer_email": null,
  "customer_phone": null,
  "expires_at": "2026-10-09T12:00:00Z",
  "flow": "setup",
  "line_items": null,
  "metadata": {},
  "mode": "test",
  "payment_method": null,
  "payment_method_options": {
    "mx_direct_debit": {
      "max_amount": 35000,
      "interval": "month"
    }
  },
  "payment_method_types": [
    "mx_direct_debit"
  ],
  "payment_resource": null,
  "redirect_url": "https://checkout.fintoc.com/cs_000000001",
  "session_token": null,
  "setup_intent": null,
  "split": null,
  "split_applied": null,
  "status": "created",
  "subscription": null,
  "success_url": "https://example.com/success"
}

The endpoint returns 201 Created. payment_method is null until the customer completes enrollment. Use redirect_url to open checkout; the public response’s session_token is null for this flow.

Create a subscription with the payment method

Create a session with flow: 'subscription'. Fintoc derives the mandate limit from the sum of each line item’s unit_amount × quantity, and derives the mandate period from recurring.interval. The example authorizes $350.00 MXN monthly. All line items must use the same interval, and interval_count must be 1 when direct debit is available, including sessions that also offer cards. Use week, month, or year. Do not send direct debit mandate terms in payment_method_options for a subscription. Server

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_KEY" \
  --header "Fintoc-Version: 2026-02-01" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "flow": "subscription",
  "currency": "mxn",
  "payment_method_types": [
    "mx_direct_debit"
  ],
  "customer_data": {
    "name": "Test Customer 1",
    "email": "test.customer.1@example.com"
  },
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "line_items": [
    {
      "price_data": {
        "currency": "mxn",
        "unit_amount": 35000,
        "product_data": {
          "name": "Test monthly plan"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ]
}'

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

const fintoc = new Fintoc('YOUR_TEST_SECRET_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'subscription',
  currency: 'mxn',
  payment_method_types: ['mx_direct_debit'],
  customer_data: {
    name: 'Test Customer 1',
    email: 'test.customer.1@example.com',
  },
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price_data: {
        currency: 'mxn',
        unit_amount: 35000,
        product_data: {
          name: 'Test monthly plan',
        },
        recurring: {
          interval: 'month',
          interval_count: 1,
        },
      },
      quantity: 1,
    }
  ],
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_KEY', api_version='2026-02-01')

checkout_session = client.v2.checkout_sessions.create(
    flow="subscription",
    currency="mxn",
    payment_method_types=[
        "mx_direct_debit"
    ],
    customer_data={
        "name": "Test Customer 1",
        "email": "test.customer.1@example.com"
    },
    success_url="https://example.com/success",
    cancel_url="https://example.com/cancel",
    line_items=[
        {
            "price_data": {
                "currency": "mxn",
                "unit_amount": 35000,
                "product_data": {
                    "name": "Test monthly plan"
                },
                "recurring": {
                    "interval": "month",
                    "interval_count": 1
                }
            },
            "quantity": 1
        }
    ],
)

{
  "id": "cs_000000001",
  "object": "checkout_session",
  "amount": null,
  "business_profile": null,
  "cancel_url": "https://example.com/cancel",
  "created_at": "2026-10-08T12:00:00Z",
  "currency": "MXN",
  "customer": {
    "id": "cus_000000001",
    "object": "customer",
    "address": null,
    "created_at": "2026-10-08T12:00:00Z",
    "email": "test.customer.1@example.com",
    "metadata": {},
    "mode": "test",
    "name": "Test Customer 1",
    "phone": null,
    "tax_id": null
  },
  "customer_email": null,
  "customer_phone": null,
  "expires_at": "2026-10-09T12:00:00Z",
  "flow": "subscription",
  "line_items": [
    {
      "quantity": 1,
      "price": {
        "currency": "MXN",
        "product": {
          "description": null,
          "image_url": null,
          "metadata": {},
          "name": "Test monthly plan"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "unit_amount": 35000
      }
    }
  ],
  "metadata": {},
  "mode": "test",
  "payment_method": null,
  "payment_method_options": {
    "mx_direct_debit": {}
  },
  "payment_method_types": [
    "mx_direct_debit"
  ],
  "payment_resource": null,
  "redirect_url": "https://checkout.fintoc.com/cs_000000001",
  "session_token": null,
  "setup_intent": null,
  "split": null,
  "split_applied": null,
  "status": "created",
  "subscription": null,
  "success_url": "https://example.com/success",
  "billing_cycle_anchor": null,
  "trial_end": null
}

The endpoint returns 201 Created. Both payment_method and subscription are null until enrollment completes. customer_data creates the billing customer; it does not replace the holder details your customer enters during checkout.

4. Redirect your customer to checkout

Return redirect_url from your backend and redirect the customer’s browser to it. Keep your secret key on the server.

Client

window.location.assign(REDIRECT_URL_FROM_YOUR_BACKEND);

Your customer completes these steps on desktop or mobile:

Enters the holder’s first name, last name, email, and RFC.
Continues through identity verification, with front and back images of an Instituto Nacional Electoral (INE) voter ID and a selfie. Sandbox uses simulated documents.
Enters a CLABE or debit card and, for a debit card, selects the bank.
Confirms the account and mandate terms, then authorizes the direct debit.
Sees the confirmation and can download the mandate document.

Keep these enrollment rules in mind:

Correcting an account that fails verification keeps the identity approval.
A rejected identity does not create a mandate or payment method.
Enrollment expires one hour after the customer submits the holder details. Advancing through screens does not extend the deadline, and it is independent of the Checkout Session’s public expires_at.
After enrollment expires, the customer cannot resume direct debit in that session. The customer can return to your site or choose another payment method if the session still allows it.
Starting identity verification again within the same session is not supported in this release.

5. Handle enrollment and mandate events

Handle webhooks on your backend rather than treating the redirect to success_url as proof that you can charge the payment method. Events can arrive out of order, so use the resource IDs to reconcile your stored state. Follow the webhook verification and delivery guide.

Event	Path	What it means
`checkout_session.finished`	Checkout Session	Enrollment completed. The session contains `payment_method` and, for `subscription`, `subscription`. It does not confirm mandate approval or a successful charge.
`payment_method.activated`	Both	The mandate is `active` and the payment method can be charged.
`payment_method.canceled`	Both	The mandate was rejected, expired without approval, or canceled. Inspect `mx_direct_debit.status` to distinguish the outcome. Stop using the payment method for new charges.
`invoice.paid`, `invoice.payment_failed`	Subscription billing	An invoice was paid or its collection failed. Enrollment and mandate approval are separate from invoice payment.

Use Get a payment method to reconcile its current state. The mx_direct_debit.status values are pending, active, rejected, expired, and canceled. Only active permits charges. For subscriptions, follow Manage invoices for billing and collection. Mandate activation does not itself confirm payment of the first invoice or change the subscription’s billing dates.

6. Charge the enrolled payment method

After payment_method.activated, use the payment method ID to create an on-demand charge or create a subscription by API. A subscription created through checkout already has its payment method attached. Charges must use MXN, be between 100 and 99999900 cents ($1.00 to $999,999.00 MXN), and stay within the remaining authorized limit for the mandate period. Creating a charge that exceeds the available limit returns limit_exceeded. A charge that fails the limit check during settlement reports amount_limit_reached. Charge creation and charge settlement are separate; handle the charge or invoice result webhooks before marking an order as paid.

7. Download the mandate document

Call Get a payment method mandate document with your secret key to obtain a temporary download URL. This works for both enrollment paths once the contract is stored, including while the mandate is pending. Server

curl --request GET "https://api.fintoc.com/v2/payment_methods/pm_000000001/mandate_document" \
  --header "Authorization: YOUR_TEST_SECRET_KEY" \
  --header "Fintoc-Version: 2026-02-01"

{
  "download_url": "https://storage.example.com/mandates/contract.pdf?signature=EXAMPLE",
  "expires_at": "2026-10-08T12:05:00Z",
  "filename": "contract.pdf"
}

download_url expires after five minutes. expires_at is an ISO 8601 datetime in UTC, and filename is the stored file’s name. Request a fresh URL when needed; do not store the URL as a permanent document link. This endpoint is not exposed by the official Node or Python SDKs. A missing payment method, wrong organization, or wrong API key mode returns 404 with missing_resource. A payment method without a downloadable native direct debit contract returns 422 with invalid_payment_method_state, including legacy Belvo payment methods. For checkout enrollment, Fintoc sends a confirmation email to the Checkout Session’s resolved customer email when enrollment completes, unless receipt emails are suppressed by your branding configuration. The holder email entered in the widget does not replace that recipient. The confirmation email is not proof that the mandate is active. The widget also offers document download; it does not offer a manual email-send action.

8. Test the integration

Use your test secret key and the fixtures below. Run API enrollment with local sample files, or create a Checkout Session and complete it on desktop and mobile. Verify the returned resources and received webhooks as well as the confirmation screen.

Simulate identity verification in checkout

These RFCs apply to the Checkout Session path. API enrollment accepts the consent documents you supply and does not run the checkout identity simulator.

RFC	Expected result
`AAAA010101AAA`	Identity approved. Continue to account entry and authorization.
`AAAA010101111`	Identity rejected with `identity_not_approved`. No mandate or payment method is created.
`AAAA010101222`	The first identity validation in the session fails with `identity_simulation_failed`. No mandate or payment method is created.

The last three characters select the scenario. Use a structurally valid individual RFC with 13 characters. Retrying identity verification within the same Checkout Session is not part of this release.

Simulate account verification in checkout

Use CLABE 012180000000083333 to return account_not_validated before a mandate is created. Correct the account to 012180000000000015 and continue without repeating identity verification. Account numbers with invalid format or checksum, and unsupported banks, are rejected before enrollment. The 3333 suffix applies to account verification in checkout. It is not a mandate-rejection scenario for API enrollment.

Simulate mandate outcomes in either path

Use the following published sandbox account numbers. For a debit card, select or send mx_banco_bbva as the issuing bank. Mandates first return pending, then resolve asynchronously. The sandbox resolution delay defaults to five seconds; allow additional time for webhook delivery.

Account type	Test number	Expected mandate status	Expected event
`clabe`	`012180000000000015`	`active`	`payment_method.activated`
`clabe`	`012180000000001111`	`rejected`	`payment_method.canceled`
`clabe`	`012180000000088888`	`expired`	`payment_method.canceled`
`debit_card`	`4111111111111111`	`active`	`payment_method.activated`
`debit_card`	`4111111111050335`	`rejected`	`payment_method.canceled`

CLABEs ending in 1111 simulate rejection; CLABEs ending in 8888 simulate no bank response and expiry. Debit cards ending in 0335 simulate rejection. Other valid accounts approve, except for checkout account-verification failures. A debit card ending in 1111 approves; it does not use the CLABE rejection rule.

Simulate charges

After the payment method becomes active, create a charge within the mandate limit. Valid amounts of at least 500 MXN cents ($5.00 MXN) succeed; amounts from 100 to 499 simulate insufficient_funds. Resolution is asynchronous and defaults to five seconds in sandbox. Verify the charge result instead of only the create response. Also verify that a charge exceeding the mandate’s remaining authorized limit is rejected with limit_exceeded, and that a pending, rejected, expired, or canceled mandate cannot be charged.

Home

Resources

Payments

Business Accounts

Movements

Skeleton group medium 9

Accept direct debit payments in Mexico

1. Prepare your integration

2. Enroll a payment method by API

3. Create a Checkout Session

Save the payment method for future charges

Create a subscription with the payment method

4. Redirect your customer to checkout

5. Handle enrollment and mandate events

6. Charge the enrolled payment method

7. Download the mandate document

8. Test the integration

Simulate identity verification in checkout

Simulate account verification in checkout

Simulate mandate outcomes in either path

Simulate charges

What’s next

Home

Resources

Payments

Business Accounts

Movements

Skeleton group medium 9

​1. Prepare your integration

​2. Enroll a payment method by API

​3. Create a Checkout Session

​Save the payment method for future charges

​Create a subscription with the payment method

​4. Redirect your customer to checkout

​5. Handle enrollment and mandate events

​6. Charge the enrolled payment method

​7. Download the mandate document

​8. Test the integration

​Simulate identity verification in checkout

​Simulate account verification in checkout

​Simulate mandate outcomes in either path

​Simulate charges

​What’s next

1. Prepare your integration

2. Enroll a payment method by API

3. Create a Checkout Session

Save the payment method for future charges

Create a subscription with the payment method

4. Redirect your customer to checkout

5. Handle enrollment and mandate events

6. Charge the enrolled payment method

7. Download the mandate document

8. Test the integration

Simulate identity verification in checkout

Simulate account verification in checkout

Simulate mandate outcomes in either path

Simulate charges

What’s next