Manage your Account Numbers

As your integration grows, you may accumulate Account Numbers that no longer receive payments. This guide shows you how to check your Account Number usage, find inactive Account Numbers, and delete the ones you no longer need to free quota.

Check your Account Number usage

Each organization has a quota of 1,000,000 Account Numbers by default. In Mexico, an Account Number is a standardized Mexican bank account number (CLABE). Every active Account Number occupies one slot, whether it receives payments or not. Deleting an Account Number frees its slot immediately.

Find inactive Account Numbers

Every Account Number tracks the timestamp of its last inbound transfer in the last_transfer_at field. An Account Number that has never received a transfer has last_transfer_at set to null.

Use the no_transfers_since filter on GET /v2/account_numbers to find Account Numbers with no transfer activity since a given date. The filter returns every Account Number that either never received a transfer or whose last transfer was before the given date.

curl --request GET \
     --url 'https://api.fintoc.com/v2/account_numbers?no_transfers_since=2025-12-01' \
     --header 'Authorization: sk_test_jKaHdEa3mfmP0D105H' \
     --header 'accept: application/json'

const accountNumbers = await fintoc.v2.accountNumbers.list({
  no_transfers_since: "2025-12-01",
});

account_numbers = client.v2.account_numbers.list(
  no_transfers_since="2025-12-01"
)

{
  "data": [
    {
      "id": "acno_test_a1b2c3d4e5f6",
      "object": "account_number",
      "number": "000000000000000000",
      "is_root": false,
      "last_transfer_at": null
    }
  ]
}

Delete an Account Number

When an Account Number is no longer needed, you can permanently delete it with DELETE /v2/account_numbers/{id}. Unlike disabling, deletion cannot be undone.

After deletion, an Account Number enters a cooldown period during which it cannot be used or reassigned. After the cooldown period, the Account Number becomes available again and may be reassigned to a different organization when that organization creates a new Account Number.

Root Account Numbers (is_root: true) and blocked Account Numbers cannot be deleted.

curl --request DELETE \
     --url https://api.fintoc.com/v2/account_numbers/acno_test_a1b2c3d4e5f6 \
     --header 'Authorization: sk_test_jKaHdEa3mfmP0D105H' \
     --header 'accept: application/json'

await fintoc.v2.accountNumbers.delete("acno_test_a1b2c3d4e5f6");

client.v2.account_numbers.delete("acno_test_a1b2c3d4e5f6")

{
  "id": "acno_test_a1b2c3d4e5f6",
  "object": "account_number",
  "number": "000000000000000000",
  "is_root": false,
  "status": "deleted"
}

What happens after deletion

Deleting an Account Number triggers four changes:

1. Fintoc rejects inbound transfers. Fintoc returns payments sent to the deleted Account Number to the sender. This applies to Mexico's Sistema de Pagos Electrónicos Interbancarios (SPEI) rail and Chile's Transferencia Electrónica de Fondos (TEF) rail.
2. Quota is freed. Your organization's Account Number count decreases, so you can create new Account Numbers.
3. The Account Number is recycled. After a cooldown period, the Account Number enters a pool and may be reassigned to any account, including accounts that belong to other organizations.
4. A webhook fires. Fintoc sends the account_number.deleted event to your configured webhook endpoints.

Disable vs delete

Both actions stop inbound transfers, but they differ in whether you can reverse them and whether they free the Account Number and its quota:

To temporarily stop receiving transfers on a particular Account Number, disable the Account Number instead.

Test the integration

Confirm the full flow in test mode before deleting any Account Number in live mode:

1. Create a test Account Number, or pick an existing one with last_transfer_at set to null.
2. Send the DELETE /v2/account_numbers/{id} request with your sk_test_ key and confirm the response returns the Account Number with "status": "deleted".
3. Confirm the account_number.deleted event arrives at your configured webhook endpoint.