Onboarding de account holder

account_holder es el tipo de onboarding para abrir una Entity mexicana como titular de cuenta. Una vez que Fintoc aprueba la revisión, la Entity puede ser titular de objetos Account. Esta página documenta el esquema que envías en data al crear un onboarding account_holder y los slots de documentos que abre el onboarding. Para el flujo completo, desde crear la Entity hasta enviarla a revisión, sigue Onboarding de una entidad por API. Esta página cubre solo lo que es específico del tipo account_holder.

Disponibilidadaccount_holder admite objetos Entity mexicanos. Crear un onboarding account_holder para una Entity de otro país devuelve 422 Unprocessable Entity con el código country_not_supported.

La estructura de la solicitud

Envía type y data en el primer nivel de la solicitud de creación:

{
  "type": "account_holder",
  "data": {
    "company_information": { },
    "legal_representatives": [ ],
    "transactional_profile": { },
    "shareholders": [ ]
  }
}

El objeto data contiene cuatro claves, todas obligatorias. Las secciones siguientes documentan cada una. La referencia de la API describe data como un objeto de forma libre, porque su estructura depende de type; esta página es el esquema de account_holder. legal_representatives y shareholders reportan sus errores de forma independiente, así que una respuesta puede traer errores de ambos bloques. company_information y transactional_profile son la excepción. Fintoc los valida en ese orden y se detiene en el primer bloque que falla. Una solicitud con errores en ambos bloques reporta solo company_information.

company_information

La identidad de la empresa y sus datos de liquidación. Todos los campos son obligatorios:

Campo	Tipo	Obligatorio	Descripción
`business_activity`	string	Obligatorio	Actividad económica principal de la empresa.
`business_address`	string	Obligatorio	Dirección física donde opera la empresa.
`fiscal_address`	string	Obligatorio	Dirección registrada ante la autoridad fiscal mexicana.
`incorporation_date`	string	Obligatorio	Fecha de constitución de la empresa, como fecha ISO 8601. La respuesta devuelve este valor como fecha y hora en UTC (ISO 8601).
`phone`	string	Obligatorio	Teléfono de contacto en formato E.164: un `+` inicial seguido de entre 8 y 15 dígitos, y el primero no puede ser `0`.
`settlement_account`	string	Obligatorio	Cuenta que recibe las liquidaciones, como CLABE (Clave Bancaria Estandarizada) de 18 dígitos.

La validación de la CLABE cambia según el modosettlement_account debe tener 18 dígitos. Fintoc acepta el valor cuando los primeros tres dígitos corresponden a una institución mexicana soportada y el dígito de control de la CLABE es correcto. Fintoc también acepta sus propias CLABEs y en esos casos omite el dígito de control. En modo test, esto aplica a los códigos de banco de sandbox. En modo live, aplica al código de banco propio de Fintoc. Una CLABE de una institución mexicana soportada se comporta igual en ambos modos. Una CLABE de sandbox que funciona en test devuelve un error en live. Un valor inválido devuelve 400 Bad Request con el código invalid_clabe y param en company_information.settlement_account.

legal_representatives

Las personas autorizadas para actuar en nombre de la empresa. Declara al menos una. Fintoc no impone un máximo, y todos los campos son obligatorios en cada entrada:

Campo	Tipo	Obligatorio	Descripción
`email`	string	Obligatorio	Correo electrónico del representante legal.
`first_name`	string	Obligatorio	Nombre de pila del representante legal.
`identification_number`	string	Obligatorio	Clave Única de Registro de Población (CURP) del representante legal.
`last_name`	string	Obligatorio	Apellido del representante legal.
`nationality`	string	Obligatorio	Código de país ISO 3166-1 alfa-2 de dos letras de la nacionalidad del representante. Fintoc acepta mayúsculas y minúsculas. La respuesta devuelve el valor tal como lo enviaste.
`position`	string	Obligatorio	Cargo que ocupa el representante legal en la empresa, por ejemplo `Director General`.

Un arreglo vacío devuelve 400 Bad Request con el código legal_representatives_required. Los errores de este bloque se acumulan entre entradas, y param incluye el índice de la entrada que falla, por ejemplo legal_representatives.0.email.

transactional_profile

El volumen y el origen del dinero que la Entity espera mover. Todos los campos son obligatorios:

Campo	Tipo	Obligatorio	Descripción
`monthly_amount_range`	string	Obligatorio	Monto mensual esperado, en pesos mexicanos. Uno de `1_500000` para 1 a 500.000, `500001_1000000` para 500.001 a 1.000.000, o `gt_1000000` para más de 1.000.000.
`monthly_operations_range`	string	Obligatorio	Cantidad mensual esperada de operaciones. Uno de `1_15000` para 1 a 15.000, `15001_50000` para 15.001 a 50.000, o `gte_50001` para 50.001 o más.
`resource_origins`	arreglo de string	Obligatorio	De dónde proviene el dinero que mueve la `Entity`. Envía al menos un valor de la lista siguiente.

resource_origins acepta estos valores:

Valor de `resource_origins`	Origen de los fondos
`asset_sales`	Producto de la venta de activos.
`budget_allocations`	Presupuesto asignado por otra organización.
`donations`	Donaciones recibidas.
`investments`	Rendimientos de inversiones.
`profits`	Utilidades operativas de la empresa.
`royalties`	Pagos por regalías.
`trusts`	Distribuciones de un fideicomiso.

La respuesta repite transactional_profile con declaration_accepted en true, que Fintoc agrega al crear el onboarding. No envíes declaration_accepted; la API lo ignora.

shareholders

El árbol de propiedad de la empresa. Declara al menos un accionista; un arreglo vacío devuelve 400 Bad Request con el código shareholders_required. Cada nodo del árbol, en la raíz y a cualquier profundidad, acepta estos campos:

Campo	Tipo	Obligatorio	Descripción
`children`	arreglo de accionistas	Opcional, solo `legal_entity`	Accionistas que son dueños de este accionista. Envía esto solo cuando `type` es `legal_entity`.
`holder_id`	string	Obligatorio	RFC (identificador fiscal mexicano) del accionista.
`last_name`	string	Opcional, solo `natural_person`	Apellido del accionista. Envía esto solo cuando `type` es `natural_person`. Enviarlo para un `legal_entity` devuelve `400 Bad Request` con el código `invalid_name`.
`name`	string	Obligatorio	Nombre de pila cuando `type` es `natural_person`, o razón social cuando `type` es `legal_entity`.
`nationality`	string	Obligatorio	Código de país ISO 3166-1 alfa-2 de dos letras de la nacionalidad del accionista. Fintoc acepta mayúsculas o minúsculas y devuelve el valor tal como lo enviaste.
`percentage`	number	Obligatorio	Participación que tiene el accionista, de `0` a `100`. Envía un número JSON; la API rechaza un número como string.
`type`	string	Obligatorio	Tipo de accionista. Uno de `natural_person` o `legal_entity`.

Dos reglas restringen el árbol:

Cada nivel suma entre 76 y 100. Los porcentajes de la raíz deben sumar al menos 76 y como máximo 100. Cada arreglo children debe cumplir el mismo rango. Un nivel por debajo de 76 devuelve el código participation_below_threshold. Un nivel por encima de 100 devuelve el código shareholder_participation_exceeded.
Solo un legal_entity anida. Un natural_person que lleve children devuelve el código only_legal_entity_can_nest. Un legal_entity sin children es válido, y Fintoc no revisa la suma de un nivel que no existe. Fintoc no impone un límite de profundidad de anidamiento.

A diferencia de legal_representatives, este bloque reporta un error a la vez. Corrige el nodo reportado y reenvía.

Slots de documentos

Crear el onboarding abre todos los slots que el tipo requiere, y cada uno reporta missing hasta que subes un archivo. Todos los slots son obligatorios antes de que puedas enviar el onboarding. El tamaño máximo es 20 MB en todos los slots. En los slots de la empresa y en los documentos de los accionistas, Fintoc lee el tipo de contenido a partir de los bytes del archivo. El tipo de contenido que declara tu carga no importa. Los dos slots del representante legal revisan ambos valores. Envía el Content-Type de la parte como uno de los tipos aceptados de ese slot, porque Fintoc rechaza la carga antes de inspeccionar los bytes. El onboarding abre cinco slots de la empresa, listados en el arreglo documents del primer nivel:

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

Cada representante legal tiene su propio arreglo documents con dos slots:

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

Cada accionista tiene un único objeto document en lugar de un arreglo, porque un accionista tiene exactamente un documento. Fintoc elige el slot a partir del type del accionista, así que la ruta de carga no lleva slot_key:

`type` del accionista	`slot_key`	Tipos de contenido aceptados
`legal_entity`	`articles_of_incorporation`	`application/pdf`, `image/jpeg`, `image/png`
`natural_person`	`identification`	`application/pdf`, `image/jpeg`, `image/png`

Una empresa con un representante legal y tres accionistas abre entonces diez slots: cinco de la empresa, dos del representante y uno por accionista.

Un ejemplo completo

Este payload declara un representante legal y dos accionistas raíz. Uno de los accionistas raíz anida un tercer accionista. Todos los valores son datos de prueba que no corresponden a ninguna empresa ni persona real. El settlement_account es una CLABE de prueba documentada. Fintoc la 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.

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

Qué sigue

Onboarding de una entidad por API para el flujo completo, incluidas las cargas, el envío y la revisión.
Requisitos de KYC para México para los documentos que revisa el equipo de cumplimiento de Fintoc.
El objeto Onboarding para los atributos de la respuesta.

​La estructura de la solicitud

​company_information

​legal_representatives

​transactional_profile

​shareholders

​Slots de documentos

​Un ejemplo completo

​Qué sigue

La estructura de la solicitud

company_information

legal_representatives

transactional_profile

shareholders

Slots de documentos

Un ejemplo completo

Qué sigue