Onboarding de una entidad por API

Usa la API para crear una Entity y completar su onboarding. Una vez aprobada, la entidad puede ser titular de objetos Account sin que uses el Dashboard. Este flujo es para plataformas que crean una Entity por cada cliente, como marketplaces o billeteras que mantienen saldos bajo la razón social de cada cliente. Para crear objetos Account bajo tu propia Entity raíz, revisa Crea más cuentas.

DisponibilidadEl onboarding por API admite objetos Entity mexicanos. En Chile no puedes abrir una Entity para un cliente, ni por API ni desde el Dashboard. Toda Account chilena pertenece a tu propia Entity raíz. Revisa Crea más cuentas.

Completa el flujo a través de la APIUn onboarding que creas a través de la API lleva source en api y permanece en ese canal. No puedes continuar ese onboarding desde el Dashboard: subir los documentos, enviarlo a revisión y seguir el resultado ocurren a través de la API.

Antes de comenzar

Necesitas una clave secreta del Dashboard, en Developers → API Keys. La clave que envías selecciona el modo: sk_test_... opera en test y sk_live_... opera en live. Usa el modo test para construir y verificar tu integración. Usa el modo live para hacer el onboarding de cada cliente real. Son actividades distintas, no dos etapas de un mismo flujo. Un onboarding en test es un objeto distinto de uno en live y nunca se convierte en un onboarding en live. Hacer el onboarding de un cliente en test no avanza el onboarding en live de ese cliente. Los ejemplos de esta página usan una clave de prueba. Tu organización también necesita su propia Entity raíz (con is_root en true) en el mismo modo que la clave que envías. Fintoc verifica este requisito cuando creas una Entity para un cliente. Para hacer el onboarding de clientes en live, tu organización necesita una Entity raíz en live. Para construir en test, tu organización necesita una Entity raíz en test.

Paso 1: Crear la entidad

Una Entity es la persona jurídica titular de la cuenta. Crea una para tu cliente con su razón social y su RFC (identificador fiscal mexicano). Configura country_code con mx y holder_id con el RFC del cliente.

curl --request POST \
     --url https://api.fintoc.com/v2/entities \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country_code": "mx",
  "holder_name": "Test Entity 1",
  "holder_id": "AAA010101AAA"
}
'

{
  "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "object": "entity",
  "country_code": "mx",
  "holder_id": "AAA010101AAA",
  "holder_name": "Test Entity 1",
  "is_root": false,
  "mode": "test",
  "status": "waiting_initialization"
}

Guarda el ID de la Entity (ent_...), porque cada llamada del onboarding usa este valor. Revisa El objeto Entity para ver la lista completa de atributos. Si tu organización no tiene una Entity raíz en el modo de tu clave de API, Fintoc rechaza la solicitud con 422 Unprocessable Entity, type en invalid_request_error y code en organization_without_operational_root_entity:

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "organization_without_operational_root_entity",
    "message": "The organization does not have an operational root entity",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

Verifica que estás usando la clave del modo correcto. Si tu organización no tiene una Entity raíz en ese modo, contacta al soporte de Fintoc antes de crear objetos Entity para clientes.

Paso 2: Crear el onboarding

El Onboarding contiene la revisión de conocimiento del cliente de una Entity. La revisión incluye la información de la empresa, los representantes legales, el perfil transaccional y los accionistas. Crea un onboarding por Entity. El cuerpo de la solicitud tiene dos campos de primer nivel, ambos obligatorios. Envía en type el tipo de onboarding que quieres crear. El único valor aceptado es account_holder. Envía los datos de la revisión en data, que contiene company_information, legal_representatives, transactional_profile y shareholders. Las cuatro claves son obligatorias. La estructura de data depende de type. Revisa Onboarding de account holder para ver cada campo, valor de enum y regla de validación del tipo account_holder. Omitir type o data devuelve 400 Bad Request con el código missing_parameter. Un type que no esté entre los valores aceptados devuelve 400 Bad Request con el código invalid_enum. El mensaje de error indica los valores aceptados. Una Entity mantiene como máximo un onboarding por modo, así que la misma Entity puede mantener un onboarding live y uno test al mismo tiempo. Un segundo onboarding en el mismo modo devuelve 409 Conflict, incluso cuando el primero ya está rejected.

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "account_holder",
  "data": {
    "company_information": {
      "business_activity": "Servicios financieros",
      "business_address": "Av. Insurgentes 456, CDMX",
      "fiscal_address": "Av. Reforma 123, CDMX",
      "incorporation_date": "2020-01-15",
      "phone": "+521111111111",
      "settlement_account": "646969000000000000"
    },
    "legal_representatives": [
      {
        "first_name": "Test Customer 1",
        "last_name": "Customer",
        "email": "rep@example.com",
        "nationality": "mx",
        "identification_number": "AAAA010101HDFAAA01",
        "position": "Director General"
      }
    ],
    "transactional_profile": {
      "resource_origins": ["trusts", "investments"],
      "monthly_amount_range": "1_500000",
      "monthly_operations_range": "1_15000"
    },
    "shareholders": [
      {
        "type": "natural_person",
        "name": "Test Customer 2",
        "last_name": "Customer",
        "holder_id": "AAAA010101AAA",
        "nationality": "mx",
        "percentage": 60
      },
      {
        "type": "legal_entity",
        "name": "Test Entity 2",
        "holder_id": "AAA010101AAA",
        "nationality": "mx",
        "percentage": 40,
        "children": [
          {
            "type": "natural_person",
            "name": "Test Customer 3",
            "last_name": "Customer",
            "holder_id": "AAAA010101AAA",
            "nationality": "mx",
            "percentage": 80
          }
        ]
      }
    ]
  }
}
'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "in_progress",
  "source": "api",
  "submittable": false,
  "submitted_at": null,
  "reviewed_at": null,
  "legal_representatives": [
    {
      "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_legal_representative",
      "documents": [
        { "slot_key": "identification", "status": "missing" },
        { "slot_key": "power_of_attorney", "status": "missing" }
      ]
    }
  ],
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": null,
      "document": { "slot_key": "identification", "status": "missing" }
    },
    {
      "id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "object": "onboarding_shareholder",
      "type": "legal_entity",
      "parent_id": null,
      "document": { "slot_key": "articles_of_incorporation", "status": "missing" }
    },
    {
      "id": "onbsh_9bnCxhAlucAI7zezIb7Un1fN",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "document": { "slot_key": "identification", "status": "missing" }
    }
  ],
  "documents": [
    { "slot_key": "tax_registration_certificate", "status": "missing" },
    { "slot_key": "settlement_bank_statement", "status": "missing" },
    { "slot_key": "proof_of_address", "status": "missing" },
    { "slot_key": "shareholder_structure", "status": "missing" },
    { "slot_key": "articles_of_incorporation", "status": "missing" }
  ]
}

Un bloque etiquetado como Response (abridged) muestra solo los campos que cambian en ese paso, no el objeto completo. La respuesta completa también devuelve data, que repite el company_information y el transactional_profile que enviaste. Cada representante legal y accionista también incluye los campos de identidad de la solicitud. Revisa El objeto Onboarding para ver la estructura completa. Cuatro detalles a tener en cuenta en la respuesta:

submittable es false hasta que cada campo y documento obligatorio esté completo.
documents lista cada slot de documento de la empresa y su status, ya sea missing o uploaded. Lee este arreglo para identificar los documentos pendientes.
Cada representante legal tiene su propio arreglo documents con dos slots.
Cada accionista tiene un único slot document. Un accionista de tipo legal_entity puede incluir children anidados.

Cada onboarding abre cinco slots de la empresa, dos slots por representante legal y un slot por accionista. El onboarding anterior declara un representante legal y tres accionistas, así que abre diez slots en total. Los pasos 3, 4 y 5 los completan. Algunos campos usan identificadores específicos de México. El identification_number del representante legal es una CURP (Clave Única de Registro de Población). El settlement_account es una CLABE (Clave Bancaria Estandarizada) de 18 dígitos. El settlement_account de arriba es un valor de prueba documentado que no corresponde a ninguna cuenta real. Fintoc lo acepta porque su código de banco y su dígito de control son válidos. Una CLABE de puros ceros devuelve 400 Bad Request, porque 000 no es un código de banco soportado. Revisa El objeto Onboarding para ver todos los campos.

Paso 3: Subir los documentos de la empresa

Sube un archivo a cada slot de documento de la empresa del arreglo documents con PUT .../documents/{slot_key}. Envía el archivo como multipart/form-data en el campo file. El tamaño máximo del archivo es 20 MB. Un slot acepta un archivo o múltiples archivos. Cada slot de la empresa de un onboarding account_holder mexicano acepta un solo archivo. En un slot de un solo archivo, PUT reemplaza el archivo existente. En un slot multiarchivo, PUT agrega un archivo y conserva los que ya subiste. Revisa Administrar los archivos de un slot. Cada slot acepta sus propios tipos de contenido:

`slot_key`	Tipos de contenido aceptados
`tax_registration_certificate`	`application/pdf`
`settlement_bank_statement`	`application/pdf`
`proof_of_address`	`application/pdf`, `image/jpeg`, `image/png`
`shareholder_structure`	`application/pdf`
`articles_of_incorporation`	`application/pdf`

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/tax_registration_certificate \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@tax_registration_certificate.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    {
      "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
      "slot_key": "tax_registration_certificate",
      "status": "uploaded",
      "filename": "tax_registration_certificate.pdf",
      "uploaded_at": "2026-01-15T14:30:00Z"
    }
  ]
}

Repite el proceso para cada slot restante: settlement_bank_statement, proof_of_address, shareholder_structure y articles_of_incorporation. Un archivo cuyo tipo de contenido el slot no acepta devuelve 422 Unprocessable Entity con el código unsupported_content_type. El mensaje de error lista los tipos de contenido que acepta el slot.

Administrar los archivos de un slot

El arreglo documents devuelve una entrada por cada archivo subido. Cada entrada subida lleva su propio id. Un slot multiarchivo con tres archivos aparece tres veces en documents, una vez por archivo, con el mismo slot_key. Un slot sin archivos aparece una vez, con status en missing y sin id. Para agregar un archivo a un slot multiarchivo, llama a POST .../documents/{slot_key} con el mismo cuerpo multipart/form-data que PUT. El ejemplo usa incorporation_amendments, un slot multiarchivo que acepta solo application/pdf. Un onboarding account_holder mexicano no tiene slots multiarchivo, así que POST aplica solo a onboardings que abren uno:

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/incorporation_amendments \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@incorporation_amendment_2025.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    {
      "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
      "slot_key": "incorporation_amendments",
      "status": "uploaded",
      "filename": "incorporation_amendment_2024.pdf",
      "uploaded_at": "2026-01-15T14:30:00Z"
    },
    {
      "id": "onbdoc_4dqEzjCnweCK9b1bKd9Wp3hP",
      "slot_key": "incorporation_amendments",
      "status": "uploaded",
      "filename": "incorporation_amendment_2025.pdf",
      "uploaded_at": "2026-01-15T14:32:00Z"
    }
  ]
}

POST en un slot de un solo archivo devuelve 422 Unprocessable Entity con el código single_file_document_slot. Usa PUT para reemplazar el archivo de un slot de un solo archivo. Para eliminar un archivo, llama a DELETE .../documents/{slot_key}/{document_id} con el id del archivo del arreglo documents:

curl --request DELETE \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/tax_registration_certificate/onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "documents": [
    { "slot_key": "tax_registration_certificate", "status": "missing" }
  ]
}

Las llamadas POST y DELETE devuelven el onboarding actualizado. Un id que no pertenece a ese slot devuelve 404 Not Found con el código missing_resource. Una vez que envías el onboarding, ya no puedes agregar ni eliminar archivos. Para reemplazar un archivo de un slot multiarchivo, llama a DELETE para ese archivo y luego a POST con el archivo nuevo.

Paso 4: Subir los documentos de cada representante legal

Cada representante legal necesita dos documentos. Usa el id del representante legal (onblr_...) de la respuesta del paso 2 y envía el slot como último segmento de la ruta. El slot identification acepta application/pdf, image/jpeg e image/png. El slot power_of_attorney acepta solo application/pdf.

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/legal_representatives/onblr_0ujsswThIGTUYm2K8FjOOfXtY1K/documents/identification \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@identification.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "legal_representatives": [
    {
      "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_legal_representative",
      "documents": [
        {
          "slot_key": "identification",
          "status": "uploaded",
          "filename": "identification.pdf",
          "uploaded_at": "2026-01-15T14:30:00Z"
        },
        { "slot_key": "power_of_attorney", "status": "missing" }
      ]
    }
  ]
}

Repite el proceso para el slot power_of_attorney y para cada representante legal que hayas declarado.

Paso 5: Subir el documento de cada accionista

Cada accionista declarado necesita un documento. Usa el id del accionista (onbsh_...) de la respuesta del paso 2. Esta ruta no lleva slot, porque Fintoc lo deriva del type del accionista: identification para un natural_person y articles_of_incorporation para un legal_entity. El slot acepta application/pdf, image/jpeg e image/png.

curl --request PUT \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/shareholders/onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K/document \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --form 'file=@identification.pdf'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "document": {
        "slot_key": "identification",
        "status": "uploaded",
        "filename": "identification.pdf",
        "uploaded_at": "2026-01-15T14:30:00Z"
      }
    }
  ]
}

Paso 6: Enviar a revisión

Una vez que submittable es true, envía el onboarding para que Fintoc lo revise. El onboarding debe estar en in_progress e incluir cada campo y documento obligatorio. Después del envío, el onboarding pasa a submitted y ya no se puede modificar.

curl --request POST \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K/submit \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "submitted",
  "source": "api",
  "submittable": false,
  "submitted_at": "2026-01-15T15:00:00Z",
  "reviewed_at": null
}

submittable pasa a false cuando el onboarding queda en submitted, porque un onboarding enviado ya no acepta cambios. Si falta un campo o documento obligatorio, o el onboarding ya no está en in_progress, la llamada devuelve un error 422 Unprocessable Entity. El campo param indica el slot o campo que bloquea el envío:

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "required_document_missing",
    "message": "A required document is missing.",
    "param": "tax_registration_certificate",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

Paso 7: Seguir la revisión

Un onboarding pasa por pending, in_progress, submitted y luego approved, rejected o cancelled. Fintoc envía uno de estos eventos de webhook cuando aprueba o rechaza el onboarding:

Evento	Resultado del onboarding
`entity.onboarding.approved`	La `Entity` aprobó la revisión y está lista para operar.
`entity.onboarding.rejected`	La revisión falló. Contacta al soporte de Fintoc para revisar el caso.

Suscríbete a estos eventos en el Dashboard, en Developers → Webhooks. Cada evento lleva el onboarding revisado completo, incluidos los datos de cada paso en data, los documents y los legal_representatives y shareholders declarados, así que no necesitas llamar a la API para leer lo que Fintoc revisó. Revisa el payload de onboarding de una Entity. No puedes reintentar un onboarding rechazado con la API. Crear un onboarding nuevo para la misma Entity devuelve 409 Conflict, como explica el paso 2. Fintoc puede volver a revisar un onboarding rechazado y aprobarlo, así que tu handler puede recibir entity.onboarding.approved después de entity.onboarding.rejected para el mismo onboarding. Revisa Reintentar tras un rechazo. Si no usas webhooks, consulta el onboarding directamente:

curl --request GET \
     --url https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

{
  "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "object": "onboarding",
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "type": "account_holder",
  "status": "approved",
  "source": "api",
  "submittable": false,
  "submitted_at": "2026-01-15T15:00:00Z",
  "reviewed_at": "2026-01-16T09:00:00Z"
}

Revisa status para seguir el onboarding. Una vez que status es approved, la Entity está lista para operar.

Paso 8: Obtener la cuenta principal

Cuando el onboarding llega a approved, Fintoc crea la Account principal de la Entity con estado active, junto con su account number raíz. No necesitas crear la Account principal. Antes de la aprobación, la Entity no tiene ninguna Account, así que ninguna Account queda nunca en pending. Ambos modos funcionan igual: un onboarding test aprobado crea una Account principal en test, y un onboarding live aprobado crea una en live. Lista las cuentas de la entidad para obtener la Account principal y guarda el id (acc_...) y el root_account_number (CLABE) de ese cliente.

curl --request GET \
     --url 'https://api.fintoc.com/v2/accounts?entity_id=ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN' \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json'

[
  {
    "id": "acc_8anBwgZktbZH6ydyHa6Tm0eM",
    "object": "account",
    "mode": "test",
    "status": "active",
    "description": null,
    "is_root": true,
    "root_account_number": "646180111800000004",
    "root_account_number_id": "acno_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "available_balance": 0,
    "currency": "MXN",
    "entity": {
      "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
      "holder_id": "AAA010101AAA",
      "holder_name": "Test Entity 1",
      "is_root": false
    }
  }
]

Crear cuentas adicionales

La Account principal basta para enviar y recibir dinero. Crea más objetos Account bajo la misma Entity cuando el cliente necesite saldos separados, uno por centro de costo. Envía el ID de la Entity en entity_id. Cada Account tiene su propio saldo y su account number raíz. Los comprobantes de las transferencias salientes muestran la razón social del cliente. Revisa Crea más cuentas para ver los detalles de creación de cuentas.

curl --request POST \
     --url https://api.fintoc.com/v2/accounts \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "description": "Client settlement account"
}
'

{
  "id": "acc_9bnCxhAlucAI7zezIb7Un1fN",
  "object": "account",
  "mode": "test",
  "status": "active",
  "description": "Client settlement account",
  "is_root": false,
  "root_account_number": "646180111800000017",
  "root_account_number_id": "acno_2fJkRm7tBvQxNzYpLc5WsHaDfT3",
  "available_balance": 0,
  "currency": "MXN",
  "entity": {
    "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "holder_name": "Test Entity 1",
    "holder_id": "AAA010101AAA"
  }
}

Probar la integración

En modo test, ejecuta toda la secuencia anterior con tu clave sk_test_.... Crea la Entity y el onboarding, sube un archivo de ejemplo a cada slot y envía el onboarding. Confirma que submittable pasa a true solo después de que cada slot indica uploaded. Fintoc selecciona el modo según la clave de API que envías, no según un parámetro de la solicitud. Los cuerpos de solicitud y de respuesta del onboarding no llevan un campo mode. Los onboardings están aislados por modo. Una clave test no puede leer ni operar sobre un onboarding live, y una clave live no puede leer ni operar sobre un onboarding test. Ambos casos devuelven 404 Not Found con el código missing_resource. Fintoc resuelve entity_id en el modo de la clave de API, así que una clave test debe referenciar una Entity que exista en modo test.

Forzar el resultado de la revisión

En modo live, el envío inicia una revisión real de conocimiento del cliente que decide el equipo de cumplimiento de Fintoc. En modo test, el envío dispara una revisión simulada. Usa la revisión simulada para ejercitar los caminos de aprobación y rechazo sin esperar. Fintoc decide la revisión simulada según el valor de business_activity que enviaste en company_information. Este mecanismo funciona como un número de tarjeta de prueba: un valor mágico fuerza un resultado específico. Tres casos determinan la revisión simulada:

`business_activity`	`status` resultante	Evento de webhook
`illegal`	`rejected`	`entity.onboarding.rejected`
`suspicious`	`submitted`	Ningún evento
Cualquier otro valor	`approved`	`entity.onboarding.approved`

El caso suspicious deja reviewed_at en null. Úsalo para modelar un onboarding que sigue en revisión y comprobar cómo se comporta tu integración mientras espera una decisión. Un onboarding test sigue la misma regla de uno por modo, así que después de un rechazo simulado la Entity no puede iniciar un nuevo onboarding test. Para repetir el flujo, crea otra Entity.

Fintoc compara el string completo de forma exacta, incluyendo mayúsculas y espacios. ILLEGAL, Illegal y "illegal " con un espacio al final terminan todos en approved.

Leer el resultado simulado

POST .../submit devuelve 200 OK con status en submitted y reviewed_at en null, en ambos modos. La revisión simulada corre después de la respuesta, así que no tomes la respuesta del envío como el resultado de la revisión. Consulta el onboarding como se muestra en el paso 7, o escucha el evento de webhook. Fintoc entrega entity.onboarding.approved y entity.onboarding.rejected a los endpoints de webhook registrados en modo test, y el evento lleva "mode": "test".

Webhook event (abridged)

{
  "id": "evt_2xK9mP4nQrStUvWxYz1234567",
  "object": "event",
  "type": "entity.onboarding.approved",
  "mode": "test",
  "created_at": "2026-01-16T09:00:00.000Z",
  "data": {
    "object": "onboarding",
    "object_name": "onboarding_process",
    "id": "onbprc_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "entity_id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "entity": {
      "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
      "holder_id": "AAA010101AAA",
      "holder_name": "Test Entity 1",
      "nationality": "mx"
    },
    "type": "account_holder",
    "source": "api",
    "status": "approved",
    "submitted_at": "2026-01-15T15:00:00Z",
    "reviewed_at": "2026-01-16T09:00:00Z",
    "data": {
      "company_information": {
        "business_activity": "Servicios financieros",
        "settlement_account": "646969000000000000"
      }
    },
    "legal_representatives": [
      {
        "id": "onblr_0ujsswThIGTUYm2K8FjOOfXtY1K",
        "object": "onboarding_legal_representative",
        "first_name": "Test Customer 1",
        "last_name": "Customer"
      }
    ],
    "shareholders": [
      {
        "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
        "object": "onboarding_shareholder",
        "type": "natural_person"
      }
    ],
    "documents": [
      {
        "id": "onbdoc_3cpDyiBmvdBJ8a0aJc8Vo2gO",
        "slot_key": "tax_registration_certificate",
        "status": "uploaded"
      }
    ]
  }
}

El data del evento lleva el onboarding revisado con los mismos campos que el objeto Onboarding, salvo submittable. También mantiene object_name y entity por compatibilidad hacia atrás. El ejemplo recorta data, legal_representatives, shareholders y documents. Revisa el payload de onboarding de una Entity para ver el payload completo. El evento de rechazo lleva el mismo payload, con el type del evento en entity.onboarding.rejected y data.status en rejected.

Qué no simula el modo test

En modo test, Fintoc reproduce el resultado de la revisión y el webhook, y nada más del flujo de cumplimiento:

Sin motivo de rechazo. Un onboarding rechazado no expone ningún campo que explique la decisión, ni en la API ni en el payload del webhook.
Sin correos. Fintoc no envía ninguna notificación de envío a los representantes legales en modo test.

Qué sigue

Onboarding de account holder para el esquema de data y los slots de documentos del tipo account_holder.
Crea más cuentas para una Entity aprobada.
Revisa El objeto Onboarding y los endpoints de onboarding en la referencia de la API.

Inicio

Recursos

Pagos

Business Accounts

Movimientos

Skeleton group medium 9

Onboarding de una entidad por API

Antes de comenzar

Paso 1: Crear la entidad

Paso 2: Crear el onboarding

Paso 3: Subir los documentos de la empresa

Administrar los archivos de un slot

Paso 4: Subir los documentos de cada representante legal

Paso 5: Subir el documento de cada accionista

Paso 6: Enviar a revisión

Paso 7: Seguir la revisión

Paso 8: Obtener la cuenta principal

Crear cuentas adicionales

Probar la integración

Forzar el resultado de la revisión

Leer el resultado simulado

Qué no simula el modo test

Qué sigue

Inicio

Recursos

Pagos

Business Accounts

Movimientos

Skeleton group medium 9

​Antes de comenzar

​Paso 1: Crear la entidad

​Paso 2: Crear el onboarding

​Paso 3: Subir los documentos de la empresa

​Administrar los archivos de un slot

​Paso 4: Subir los documentos de cada representante legal

​Paso 5: Subir el documento de cada accionista

​Paso 6: Enviar a revisión

​Paso 7: Seguir la revisión

​Paso 8: Obtener la cuenta principal

​Crear cuentas adicionales

​Probar la integración

​Forzar el resultado de la revisión

​Leer el resultado simulado

​Qué no simula el modo test

​Qué sigue

Antes de comenzar

Paso 1: Crear la entidad

Paso 2: Crear el onboarding

Paso 3: Subir los documentos de la empresa

Administrar los archivos de un slot

Paso 4: Subir los documentos de cada representante legal

Paso 5: Subir el documento de cada accionista

Paso 6: Enviar a revisión

Paso 7: Seguir la revisión

Paso 8: Obtener la cuenta principal

Crear cuentas adicionales

Probar la integración

Forzar el resultado de la revisión

Leer el resultado simulado

Qué no simula el modo test

Qué sigue