Add logic to Account Numbers

You can use a Fintoc Account Number, called a standardized Mexican bank account number (CLABE) in Mexico, in different ways. You can assign an Account Number to a specific user's payments or create a single-use Account Number for a specific payment order. By the end of this guide, you can disable an Account Number and set minimum and maximum amount limits. These controls let Fintoc reject unwanted inbound transfers.

Disable an Account Number

When you disable an Account Number, Fintoc automatically rejects every inbound transfer directed to that Account Number and returns it to the sender. If an Account Number should no longer receive payments, disable it so you avoid handling stray inbound transfers.

Example use cases

• Your company assigns one Account Number per user, and a user has completed offboarding from your app. Disable that user's Account Number so payments made for the user are automatically returned and don't waste your operational resources.
• Your company assigns one Account Number per order, and a customer bought a product at your store. Disable that order's Account Number once the customer has paid to avoid receiving a double payment. If the customer misses the payment confirmation notice and pays twice, Fintoc returns the money automatically.

Disable an Account Number with the API

curl --request PATCH \
     --url https://api.fintoc.com/v2/account_numbers/acno_test_a1b2c3d4e5f6 \
     --header 'Authorization: sk_test_jKaHdEa3mfmP0D105H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "status": "disabled"
}
'

const accountNumber = await fintoc.v2.accountNumbers.update(
  "acno_test_a1b2c3d4e5f6",
  { status: "disabled" }
);

account_number = client.v2.account_numbers.update(
  "acno_test_a1b2c3d4e5f6",
  status="disabled"
)

The API returns the updated Account Number with its status set to disabled:

{
  "id": "acno_test_a1b2c3d4e5f6",
  "object": "account_number",
  "account_id": "acc_test_b2c3d4e5f6g7",
  "created_at": "2026-06-22T12:00:00.000Z",
  "deleted_at": null,
  "description": "My payins",
  "is_root": false,
  "last_transfer_at": null,
  "metadata": {},
  "mode": "test",
  "number": "000000000000000000",
  "options": null,
  "status": "disabled",
  "updated_at": "2026-06-22T12:00:00.000Z"
}

Set inbound transfer amount limits

You can restrict which inbound transfers an Account Number accepts. If a transfer does not meet the criteria you set, Fintoc rejects it. Rejected transfers do not appear on your account statements and do not incur fees. Set min_amount and max_amount in the smallest currency unit. For example, 30000 is 300.00 MXN. Fintoc supports three kinds of amount limits:

Set limits with the API

curl --request POST \
     --url https://api.fintoc.com/v2/account_numbers \
     --header 'Authorization: sk_test_jKaHdEa3mfmP0D105H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_id": "acc_test_b2c3d4e5f6g7",
  "options": {
    "min_amount": 30000,
    "max_amount": 40000
  }
}
'

const accountNumber = await fintoc.v2.accountNumbers.create({
  account_id: "acc_test_b2c3d4e5f6g7",
  options: {
    min_amount: 30000,
    max_amount: 40000,
  },
});

account_number = client.v2.account_numbers.create(
  account_id="acc_test_b2c3d4e5f6g7",
  options={
    "min_amount": 30000,
    "max_amount": 40000,
  },
)

The API returns the new Account Number with the amount limits under options:

{
  "id": "acno_test_a1b2c3d4e5f6",
  "object": "account_number",
  "account_id": "acc_test_b2c3d4e5f6g7",
  "created_at": "2026-06-22T12:00:00.000Z",
  "deleted_at": null,
  "description": "My payins",
  "is_root": false,
  "last_transfer_at": null,
  "metadata": {},
  "mode": "test",
  "number": "000000000000000000",
  "options": {
    "max_amount": 40000,
    "min_amount": 30000
  },
  "status": "enabled",
  "updated_at": "2026-06-22T12:00:00.000Z"
}

Test the integration

Confirm the disable and amount-limit behavior in test mode before going live. Use a test secret API key (sk_test_...) and the test Account Number you created above.

To test a disabled Account Number, disable it with the request above, then simulate an inbound transfer to its number. Fintoc rejects the transfer and returns it to the sender. The transfer does not appear on your account statement and incurs no fee.

To test amount limits, create an Account Number with min_amount set to 30000 and max_amount set to 40000, then simulate two inbound transfers:

• A transfer of 35000 (350.00 MXN) falls within the limits, so Fintoc accepts it.
• A transfer of 20000 (200.00 MXN) falls below min_amount, so Fintoc rejects it and returns it to the sender.

You can simulate inbound transfers in test mode from the Simulate receiving a transfer endpoint.