Administra tus Account Numbers

A medida que tu integración crece, puedes acumular Account Numbers que ya no reciben pagos. Esta guía te muestra cómo revisar el uso de tus Account Numbers, encontrar los inactivos y eliminar los que ya no necesitas para liberar cuota.

Revisa el uso de tus Account Numbers

Cada organización tiene una cuota de 1,000,000 de Account Numbers por defecto. En México, un Account Number es una Clave Bancaria Estandarizada (CLABE). Cada Account Number activo ocupa un espacio, reciba pagos o no. Eliminar un Account Number libera su espacio de inmediato.

Encuentra Account Numbers inactivos

Cada Account Number registra la marca de tiempo de su última transferencia entrante en el campo last_transfer_at. Un Account Number que nunca ha recibido una transferencia tiene last_transfer_at en null. Usa el filtro no_transfers_since en GET /v2/account_numbers para encontrar Account Numbers sin actividad de transferencias desde una fecha determinada. El filtro devuelve cada Account Number que nunca recibió una transferencia o cuya última transferencia fue anterior a la fecha indicada.

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
    }
  ]
}

Elimina un Account Number

Cuando un Account Number ya no se necesita, puedes eliminarlo de manera permanente con DELETE /v2/account_numbers/{id}. A diferencia de deshabilitarlo, la eliminación no se puede deshacer. Después de la eliminación, un Account Number entra en un período de enfriamiento durante el cual no puede usarse ni reasignarse. Pasado ese período, el Account Number vuelve a estar disponible y puede ser reasignado a otra organización cuando esta cree un nuevo Account Number. Los Account Numbers raíz (is_root: true) y los Account Numbers bloqueados no se pueden eliminar.

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"
}

Qué sucede después de eliminar

Eliminar un Account Number desencadena cuatro cambios:

Fintoc rechaza las transferencias entrantes. Fintoc devuelve al remitente los pagos enviados al Account Number eliminado. Esto aplica al riel del Sistema de Pagos Electrónicos Interbancarios (SPEI) en México y al riel de Transferencia Electrónica de Fondos (TEF) en Chile.
Se libera cuota. El conteo de Account Numbers de tu organización disminuye, por lo que puedes crear nuevos Account Numbers.
El Account Number se recicla. Después de un período de enfriamiento, el Account Number entra a un pool y puede ser reasignado a cualquier cuenta, incluidas las cuentas que pertenecen a otras organizaciones.
Se dispara un webhook. Fintoc envía el evento account_number.deleted a los endpoints de webhook que tengas configurados.

Deshabilitar vs. eliminar

Ambas acciones detienen las transferencias entrantes, pero difieren en si puedes revertirlas y en si liberan el Account Number y su cuota:

Comportamiento	Deshabilitar	Eliminar
Reversible	Sí	No
Transferencias entrantes	Rechazadas	Rechazadas
Libera el Account Number para reuso	No, el Account Number sigue reservado	Sí
Libera la cuota del Account Number	No	Sí

Para detener temporalmente la recepción de transferencias en un Account Number en particular, deshabilita el Account Number en su lugar.

Prueba la integración

Confirma el flujo completo en modo test antes de eliminar cualquier Account Number en modo live:

Crea un Account Number de prueba o elige uno existente con last_transfer_at en null.
Envía la solicitud DELETE /v2/account_numbers/{id} con tu clave sk_test_ y confirma que la respuesta devuelve el Account Number con "status": "deleted".
Confirma que el evento account_number.deleted llega a tu endpoint de webhook configurado.

Inicio

Recursos

Pagos

Transferencias

Movimientos

Administra tus Account Numbers

Revisa el uso de tus Account Numbers

Encuentra Account Numbers inactivos

Elimina un Account Number

Qué sucede después de eliminar

Deshabilitar vs. eliminar

Prueba la integración

​Revisa el uso de tus Account Numbers

​Encuentra Account Numbers inactivos

​Elimina un Account Number

​Qué sucede después de eliminar

​Deshabilitar vs. eliminar

​Prueba la integración

Revisa el uso de tus Account Numbers

Encuentra Account Numbers inactivos

Elimina un Account Number

Qué sucede después de eliminar

Deshabilitar vs. eliminar

Prueba la integración