Payins on dedicated CLABEs

What it is

You need to receive bank transfers from many customers and know, in real time, which payment belongs to which customer or order. Instead of asking your customers to write a reference in the transfer comment (which they often get wrong), you assign each customer — or each order — its own Account Number (a CLABE in Mexico). When a transfer arrives at that CLABE, you know exactly who paid, for what, and how much.

Best for

Lending companies collecting installments, insurance premiums, SaaS invoicing, marketplaces billing vendors, and any company that receives recurring transfers from identifiable customers.

How the money flows

sequenceDiagram
    autonumber
    participant You as Your backend
    participant Fintoc
    participant Customer

    You->>Fintoc: Create Account Number (with metadata.customer_id)
    Fintoc-->>You: CLABE 738969…
    You-->>Customer: Show this CLABE on the invoice
    Customer->>Fintoc: SPEI to that CLABE
    Fintoc->>You: transfer.inbound.succeeded (includes your metadata)
    You->>You: Mark invoice paid

How to configure it

1. Create an Account Number per customer or per order

Use the Create Account Number endpoint. Attach whatever identifier you need under metadata — your internal customer ID, order ID, invoice ID, etc. When the inbound transfer webhook arrives, that metadata travels with it so you can reconcile in one lookup.

curl --request POST \
     --url https://api.fintoc.com/v2/account_numbers \
     --header 'Authorization: sk_test_...' \
     --header 'content-type: application/json' \
     --data '{
       "account_id": "acc_Lq7dP901xZgA2B",
       "metadata": { "customer_id": "12343212", "invoice_id": "INV-00187" }
     }'

The response contains the CLABE under number. Store the account_number.id (e.g. acno_...) against your customer record so you can reuse it.

2. Decide: one CLABE per customer, or one CLABE per order?

Both are valid patterns, and you can mix them:

• One CLABE per customer: simplest, and fine if you're happy matching by customer and then figuring out which invoice was paid based on the amount. Reuse the CLABE for every future payment.
• One CLABE per order — strongest reconciliation. You know exactly which order was paid and can auto-disable the CLABE after it's paid to prevent accidental double payments. See Add logic to CLABEs.

3. Listen for the inbound webhook

The webhook payload includes the full Transfer object, the originating CLABE under account_number, the sender under counterparty, and your metadata. See a full example on the Receiving transfers page.

4. Harden the CLABE with business rules (optional)

When you create or update the Account Number, you can restrict which transfers it accepts:

• Set options.min_amount / options.max_amount to reject over- or under-payments automatically. Setting both to the same value accepts only an exact amount — perfect for per-order CLABEs.
• Disable the CLABE once the order is paid (status: "disabled") so any stray payment is automatically returned.

Rejected transfers don't show up on your statement and don't incur fees. Full reference in Add logic to CLABEs.

Keep your CLABEs quota clean

You can have up to 1,000,000 CLABEs. If you've created CLABEs you no longer use — churned users, cancelled orders, one-off destinations — disable or delete them. Stale CLABEs keep accepting transfers, which can pollute your reconciliation and statements. See Manage your CLABEs for how to list, disable, and delete them.