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 de clientes en Chile y México. Esta guía cubre el tipo account_holder, que abre una empresa como titular de cuenta. Una Entity que solo recibe su parte de los pagos divididos usa el tipo settlement_recipient. Revisa Aceptar pagos divididos.

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.

El flujo es el mismo en ambos países. Las pestañas de cada paso muestran lo que cambia entre Chile y México: el identificador fiscal, los campos de data, los slots de documentos y el formato del número de cuenta. Los onboardings chilenos no tienen documentos de accionistas, así que se saltan el paso 5.

Antes de comenzar

Necesitas una secret key del Dashboard, en Developers → API keys. La secret key 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 identificador fiscal. El tipo account_holder solo admite empresas, así que holder_id debe identificar a una empresa.

Chile
México

Configura country_code con cl y holder_id con el Rol Único Tributario (RUT) de la empresa. holder_id es obligatorio y debe ser un RUT válido, con o sin puntos y guion. Un RUT inválido devuelve 400 Bad Request con el código invalid_holder_id.

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": "cl",
  "holder_name": "Test Entity 1",
  "holder_id": "77.777.777-7"
}
'

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

Fintoc guarda el RUT sin puntos ni guion. Un RUT de persona natural crea la Entity, pero crear su onboarding account_holder devuelve 422 Unprocessable Entity con el código holder_type_not_supported.

Configura country_code con mx y holder_id con el Registro Federal de Contribuyentes (RFC) de la empresa.

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

Un RFC de 13 caracteres corresponde a una persona física. Esa Entity se crea, pero crear su onboarding account_holder devuelve 422 Unprocessable Entity con el código holder_type_not_supported.

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 cubre la empresa, sus representantes legales, su perfil transaccional y sus accionistas. Crea un onboarding por Entity. El cuerpo de la solicitud tiene dos campos de primer nivel, ambos obligatorios. Envía type en account_holder, el tipo que cubre esta guía. El otro valor aceptado, settlement_recipient, tiene su propio flujo en Aceptar pagos divididos. Envía los datos de la revisión en data. Las claves de data dependen del país de la Entity, y todas son obligatorias. Revisa Onboarding de account holder para ver cada campo, valor de enum y regla de validación. 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.

Chile
México

Un onboarding chileno envía siete claves en data: company_basics, company_information, senior_management, legal_representatives, shareholders, transactional_profile y plaft.

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_basics": {
      "incorporation_type": "traditional",
      "fantasy_name": "Test Company"
    },
    "company_information": {
      "activities_start_date": "2019-03-01",
      "business_activity_code": "620200",
      "company_type": "spa",
      "business_address": "Av. Apoquindo 100, Santiago",
      "fiscal_address": "Av. Apoquindo 100, Santiago"
    },
    "senior_management": {
      "senior_management": [
        {
          "name": "Test Customer 1",
          "nationality": "cl",
          "identification_number": "11.111.111-1",
          "position": "Gerente General"
        }
      ]
    },
    "legal_representatives": [
      {
        "first_name": "Test Customer 1",
        "last_name": "Customer",
        "email": "jon@snow.com",
        "nationality": "cl",
        "identification_number": "11.111.111-1",
        "position": "Representante legal",
        "phone": "+56911111111"
      }
    ],
    "shareholders": [
      {
        "type": "natural_person",
        "name": "Test Customer 1",
        "last_name": "Customer",
        "holder_id": "11.111.111-1",
        "nationality": "cl",
        "percentage": 60,
        "address": "Av. Apoquindo 100, Santiago",
        "fiscal_address": "Av. Apoquindo 100, Santiago",
        "effective_controller": true
      },
      {
        "type": "legal_entity",
        "name": "Test Entity 2",
        "holder_id": "88.888.888-8",
        "nationality": "cl",
        "percentage": 40,
        "address": "Av. Apoquindo 100, Santiago",
        "fiscal_address": "Av. Apoquindo 100, Santiago",
        "effective_controller": false,
        "children": [
          {
            "type": "natural_person",
            "name": "Test Customer 2",
            "last_name": "Customer",
            "holder_id": "22.222.222-2",
            "nationality": "cl",
            "percentage": 100,
            "address": "Av. Apoquindo 100, Santiago",
            "fiscal_address": "Av. Apoquindo 100, Santiago",
            "effective_controller": false
          }
        ]
      }
    ],
    "transactional_profile": {
      "equity_origins": ["capital_contributions"],
      "business_relationship_purposes": ["customer_collections", "supplier_payments"],
      "resource_origins": ["operating_income"]
    },
    "plaft": {
      "uaf_obligated": false
    }
  }
}
'

{
  "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_front", "status": "missing" },
        { "slot_key": "identification_back", "status": "missing" }
      ]
    }
  ],
  "shareholders": [
    {
      "id": "onbsh_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": null,
      "effective_controller": true,
      "document": null
    },
    {
      "id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "object": "onboarding_shareholder",
      "type": "legal_entity",
      "parent_id": null,
      "effective_controller": false,
      "document": null
    },
    {
      "id": "onbsh_9bnCxhAlucAI7zezIb7Un1fN",
      "object": "onboarding_shareholder",
      "type": "natural_person",
      "parent_id": "onbsh_8anBwgZktbZH6ydyHa6Tm0eM",
      "effective_controller": false,
      "document": null
    }
  ],
  "documents": [
    { "slot_key": "e_rut", "status": "missing" },
    { "slot_key": "activities_start_certificate", "status": "missing" },
    { "slot_key": "good_standing_certificate", "status": "missing" },
    { "slot_key": "power_of_attorney", "status": "missing" },
    { "slot_key": "incorporation_deed", "status": "missing" },
    { "slot_key": "incorporation_amendments", "status": "missing" },
    { "slot_key": "uaf_registration_certificate", "status": "missing" },
    { "slot_key": "plaft_manual_and_policies", "status": "missing" }
  ]
}

Cuatro detalles a tener en cuenta en la respuesta chilena:

documents depende de company_basics.incorporation_type. Una empresa traditional abre los slots de arriba. Una one_day_company (Empresa en un Día) abre current_shareholders_certificate en lugar de activities_start_certificate y good_standing_certificate.
documents siempre lista uaf_registration_certificate y plaft_manual_and_policies. Solo los subes cuando plaft.uaf_obligated es true.
Cada representante legal tiene su propio arreglo documents con dos slots: el anverso y el reverso del documento de identidad.
Cada accionista tiene document en null, porque Chile no exige un documento por accionista.

El identification_number del representante legal y el holder_id de los accionistas llevan un RUT cuando nationality es cl. Un representante legal extranjero usa su número de pasaporte.

Un onboarding mexicano envía cuatro claves en data: company_information, legal_representatives, transactional_profile y shareholders.

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",
      "sector": "ecommerce",
      "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_2000000",
      "monthly_operations_range": "1_15000",
      "account_purpose": "own_sales_collection"
    },
    "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" }
  ]
}

Cada onboarding mexicano 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.Algunos campos usan identificadores específicos de México. El identification_number del representante legal es una Clave Única de Registro de Población (CURP). El settlement_account es una Clave Bancaria Estandarizada (CLABE) 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.transactional_profile.account_purpose es obligatorio. Cuando lo envías en other, envía también account_purpose_details con una descripción de cómo usa la cuenta la empresa.

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 los datos de cada paso que enviaste, salvo legal_representatives y shareholders. Cada representante legal y accionista también incluye los campos de identidad de la solicitud. Revisa El objeto Onboarding para ver la estructura completa. Tres detalles aplican en ambos países:

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.
Un accionista de tipo legal_entity puede incluir children anidados.

Los pasos 3, 4 y 5 completan los slots.

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. 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.

Chile
México

Cada slot de la empresa chilena acepta solo application/pdf. Los slots que debes completar dependen de los datos que enviaste en el paso 2:

`slot_key`	Se abre cuando	Obligatorio para enviar	Archivos
`e_rut`	Siempre	Sí	Uno
`activities_start_certificate`	`incorporation_type` es `traditional`	Sí	Uno
`good_standing_certificate`	`incorporation_type` es `traditional`	Sí	Uno
`current_shareholders_certificate`	`incorporation_type` es `one_day_company`	Sí	Uno
`power_of_attorney`	Siempre	No	Uno
`incorporation_deed`	Siempre	Sí	Uno
`incorporation_amendments`	Siempre	No	Varios
`uaf_registration_certificate`	Siempre	Si `uaf_obligated` es `true`	Uno
`plaft_manual_and_policies`	Siempre	Si `uaf_obligated` es `true`	Varios

Un PUT a un slot que el onboarding no abre, como current_shareholders_certificate en una empresa traditional, devuelve 422 Unprocessable Entity con el código unknown_document_slot.

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

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

Repite el proceso para cada slot obligatorio restante. Agrega los archivos de incorporation_amendments y plaft_manual_and_policies de a uno, como muestra Administrar los archivos de un slot.

Cada slot de la empresa mexicana acepta un solo archivo y es obligatorio para enviar. 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 de un onboarding chileno que acepta solo application/pdf. Un onboarding account_holder mexicano no tiene slots multiarchivo:

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. Los dos slots dependen del país:

Chile
México

`slot_key`	Tipos de contenido aceptados
`identification_front`	`application/pdf`, `image/jpeg`, `image/png`
`identification_back`	`application/pdf`, `image/jpeg`, `image/png`

Sube el anverso y el reverso del documento de identidad como dos archivos. En Chile, la personería no es un slot del representante legal. Súbela al slot de la empresa power_of_attorney en el paso 3.

`slot_key`	Tipos de contenido aceptados
`identification`	`application/pdf`, `image/jpeg`, `image/png`
`power_of_attorney`	`application/pdf`

Un slot que no corresponde al país del onboarding devuelve 422 Unprocessable Entity con el código unknown_document_slot. El ejemplo sube el slot mexicano identification. Un onboarding chileno usa la misma ruta con identification_front o identification_back.

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 segundo slot y para cada representante legal que hayas declarado.

Paso 5: Subir el documento de cada accionista

Solo los onboardings mexicanos exigen un documento por accionista. Un onboarding chileno se salta este paso: cada accionista chileno tiene document en null, y subir un archivo a ese accionista devuelve 422 Unprocessable Entity con el código shareholder_document_not_required. En México, 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"
  }
}

Un onboarding chileno hace dos verificaciones más cuando lo envías:

Estado de Empresa en un Día. Cuando incorporation_type es one_day_company, Fintoc verifica que el RUT de la empresa esté registrado como Empresa en un Día. Si la empresa no lo está, o Fintoc no puede confirmarlo, la llamada devuelve el código not_one_day_company con param en incorporation_type. Si el registro rechaza el RUT de la Entity por inválido, la llamada devuelve el código invalid_rut con param en rut.
Controlador efectivo. Al menos un accionista debe tener effective_controller en true. Si no, la llamada devuelve el código effective_controller_required con param en shareholders.

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 de ese cliente. El formato del número de cuenta y la moneda dependen del país:

Chile
México

Una Account principal chilena mantiene CLP, y su root_account_number es un número de cuenta bancaria chileno.

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": "000000001",
    "root_account_number_id": "acno_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "available_balance": 0,
    "currency": "CLP",
    "entity": {
      "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
      "holder_id": "777777777",
      "holder_name": "Test Entity 1",
      "is_root": false
    }
  }
]

Una Account principal mexicana mantiene MXN, y su root_account_number es una CLABE de 18 dígitos.

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 obligatorio y envía el onboarding. Confirma que submittable pasa a true solo después de que cada slot obligatorio 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.

Para un onboarding chileno en test, envía incorporation_type en traditional. Una one_day_company activa la verificación de Empresa en un Día del paso 6 sobre el RUT de la Entity, también en modo test, así que un RUT de prueba puede bloquear el envío.

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 un valor mágico de los datos que enviaste. Este mecanismo funciona como un número de tarjeta de prueba: un valor mágico fuerza un resultado específico. El campo que lleva el valor depende del país:

Chile
México

`company_basics.fantasy_name`	`status` resultante	Evento de webhook
`illegal`	`rejected`	`entity.onboarding.rejected`
`suspicious`	`submitted`	Ningún evento
Cualquier otro valor, o sin `fantasy_name`	`approved`	`entity.onboarding.approved`

`company_information.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 muestra un onboarding mexicano y 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, en Chile y México.
Requisitos de KYC en Chile y Requisitos de KYC en México para los documentos que revisa el equipo de cumplimiento de Fintoc.
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