Aceptar pagos con split

Split Payments permite a las plataformas y marketplaces distribuir los fondos de un único pago entre varios destinatarios. Cuando un cliente paga a través de un Checkout Session, Fintoc divide la liquidación según las reglas que definas y transfiere cada parte a la cuenta bancaria del destinatario — sin transferencias manuales ni conciliaciones de tu lado. Cada destinatario es una Entity: el titular legal que recibe una parte del pago. Una Entity declara la cuenta donde recibe el pago como parte de su onboarding, así que no hay un recurso de cuenta separado que gestionar. Hay tres pasos para aceptar pagos con split:

Crear una Entity para cada destinatario
Hacer el onboarding de la Entity, incluyendo la cuenta donde recibirá el pago
Crear un Checkout Session con un arreglo split y enviar al cliente a su redirect_url

Antes de comenzar

Una cuenta de Fintoc con Collects habilitado
Tu clave secreta y clave pública
Información bancaria y de negocio de cada Entity que necesites onboardear

Paso 1: Crear una Entity

Una Entity representa al titular legal que recibe una parte del pago: un vendedor, un socio, un profesional, una unidad de negocio.

curl --request POST "https://api.fintoc.com/v2/entities" \
--header 'Authorization: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "country_code": "CL",
  "holder_name": "Test Merchant 1 SpA",
  "holder_id": "111111111"
}'

Parámetro	Tipo	Requerido	Descripción
`country_code`	string	Sí	Código de país ISO 3166-1 alpha-2. `CL` o `MX`.
`holder_name`	string	Sí	Razón social del titular de la entidad.
`holder_id`	string	Sí	Identificador fiscal sin formato. Identificador fiscal chileno (RUT) en Chile, identificador fiscal mexicano (RFC) en México. Debe ser único dentro de tu organización.

{
  "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "object": "entity",
  "country_code": "cl",
  "holder_id": "111111111",
  "holder_name": "Test Merchant 1 SpA",
  "is_root": false,
  "mode": "live",
  "status": "waiting_initialization",
  "capabilities": {
    "settlement_recipient": {
      "status": "waiting_initialization"
    },
    "account_holder": {
      "status": "waiting_initialization"
    }
  }
}

La capability settlement_recipient de una Entity nueva comienza en waiting_initialization. No puede recibir un split hasta que capabilities.settlement_recipient.status llegue a operational. Fintoc establece este estado después de aprobar el onboarding. El status de primer nivel refleja la capability más avanzada de la Entity. Usa el estado de la capability para determinar si la Entity está disponible para Split Payments.

Si el destinatario ya existe como Entity en tu organización, reutiliza su id. Crear una segunda Entity con el mismo holder_id devuelve 409 entity_holder_id_already_exists_for_organization.

Lista y recupera entities con GET /v2/entities — que acepta filtros holder_id, status y is_root — y GET /v2/entities/{id}.

Paso 2: Hacer el onboarding de la Entity

Durante el onboarding, la Entity declara quién es y la cuenta bancaria donde Fintoc paga los fondos del split. Fintoc revisa el onboarding. Después de aprobarlo, la capability settlement_recipient de la Entity pasa a operational. El onboarding se completa a través de la API, tanto en Chile como en México.

Crear el onboarding

curl --request POST "https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings" \
--header 'Authorization: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "settlement_recipient",
  "data": {
    "company_information": {
      "business_activity": "Servicios de arquitectura",
      "business_address": "Av. Apoquindo 100, Santiago, Region Metropolitana, 7550000, Chile",
      "phone": "+56 9 1111 1111",
      "settlement_account": {
        "institution_id": "cl_banco_de_chile",
        "account_number": "123456789",
        "account_type": "checking_account"
      }
    },
    "legal_representatives": [
      {
        "first_name": "Test",
        "last_name": "Customer 1",
        "email": "test@mail.com",
        "nationality": "CL",
        "identification_number": "111111111",
        "position": "Representante legal"
      }
    ]
  }
}'

Tipo de onboarding

type es requerido al crear el onboarding. Declara qué hará la Entity con Fintoc, no se puede cambiar después y determina cuánta información pide el onboarding. settlement_recipient — la Entity solo recibe dinero. Su parte de cada split se transfiere a la cuenta bancaria que declara en settlement_account, y nada más: no mantiene balance en Fintoc, no puede recibir transferencias de terceros y no puede enviar dinero. Como solo recibe pagos, el onboarding pide lo mínimo necesario para identificar a quién se le paga. Este es el valor a usar para Split Payments. account_holder — la Entity opera una cuenta en Fintoc. Puede recibir transferencias entrantes, enviar salientes y mantener balance. Esa capacidad conlleva un perfil de riesgo más alto, por lo que el onboarding requiere el conjunto completo de información: perfil transaccional, estructura de propiedad y documentos de respaldo.

La cuenta de liquidación

data.company_information.settlement_account es la cuenta donde se transfiere la parte de cada destinatario en cada split. Es el único campo que Split Payments agrega al onboarding. Los campos requeridos de settlement_account dependen del country_code del destinatario.

Chile

Parámetro	Tipo	Requerido	Descripción
`institution_id`	string	Sí	Identificador del banco. Consulta Códigos de instituciones de Chile.
`account_number`	string	Sí	Número de cuenta.
`account_type`	string	Sí	Uno de `checking_account` o `sight_account`.

México

Parámetro	Tipo	Requerido	Descripción
`account_number`	string	Sí	Clave Bancaria Estandarizada (CLABE) válida de 18 dígitos. Fintoc obtiene el identificador del banco desde la CLABE. No envíes `institution_id` ni `account_type`.

El campo settlement_account no lleva campos de titular. El titular de la cuenta es la Entity que está completando el onboarding, así que el identificador fiscal ya se conoce.

Una Entity tiene exactamente una cuenta de liquidación. Para cambiarla, crea un nuevo onboarding — ver Cambiar la cuenta de liquidación.

Campos del onboarding

Bloque	Requerido	Qué declara
`type`	Sí	Se envía al crear el onboarding. `settlement_recipient` o `account_holder`. Usa `settlement_recipient` para Split Payments.
`data`	Sí	Envuelve todos los demás bloques del onboarding.
`data.company_information`	Sí	Información de negocio de la Entity.
`data.company_information.settlement_account`	Sí	Cuenta que recibe los fondos de los splits de la Entity. Requerida para Entities de persona natural y de empresa.
`data.company_information.business_activity`	Requerido para empresas de México. Opcional para empresas de Chile.	Actividad comercial de la Entity.
`data.company_information.business_address`	Requerido para empresas de México. Opcional para empresas de Chile.	Dirección comercial de la Entity.
`data.company_information.phone`	Requerido para empresas de México. Opcional para empresas de Chile.	Número de teléfono de contacto de la Entity.
`data.legal_representatives[]`	No	Nombre, email, nacionalidad, identificación y cargo de cada representante legal. Solo se procesa para Entities de empresa.
`data.transactional_profile`	No	Volumen mensual esperado, número de operaciones y origen de los fondos. Solo se procesa para Entities de empresa.
`data.shareholders[]`	No	Estructura de propiedad, con el identificador fiscal y porcentaje de participación de cada accionista. Solo se procesa para Entities de empresa.
Documentos	No	Archivos de respaldo, subidos por slot con `PUT`. Hasta 20 MB cada uno; volver a subir un slot reemplaza el archivo.

Para Entities de empresa en Chile, business_activity, business_address y phone son opcionales. Puedes omitirlos del ejemplo anterior. Las Entities de empresa en México deben seguir enviando los tres.

Enviar el onboarding

Una vez completa la información, envíala a revisión:

curl --request POST "https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_9kQ2mZpLtR4vXn/submit" \
--header 'Authorization: YOUR_SECRET_KEY'

Validación automática de la cuenta de liquidación. Al enviar el onboarding, Fintoc valida la settlement_account enviando un micro-depósito — 1 CLP para Entities chilenas o 0,01 MXN para Entities mexicanas — para confirmar que la cuenta está activa y que su titular coincide con el holder_id de la Entity. Esto ocurre automáticamente en cada envío de un onboarding de tipo settlement_recipient; no necesitas dispararlo por separado.

El onboarding pasa por estos estados:

Estado	Significado
`pending`	Creado, aún no se ha enviado nada.
`in_progress`	Siendo completado. Los campos y documentos aún se pueden editar.
`submitted`	Bajo revisión de Fintoc. Sin más ediciones.
`approved`	Revisión aprobada. La capability `settlement_recipient` de la Entity ahora es `operational` y puede recibir splits.
`rejected`	Revisión rechazada. Crea un nuevo onboarding para reintentar.

Dos webhooks te avisan del resultado:

entity.onboarding.approved — la Entity está lista para recibir splits
entity.onboarding.rejected — la revisión falló

La revisión de compliance típicamente toma uno a dos días hábiles. Diseña tu flujo para que el destinatario pueda crearse y mostrarse como pendiente mientras corre la revisión.

Cambiar la cuenta de liquidación

Crea un nuevo onboarding para la misma Entity con la nueva cuenta. Mientras está bajo revisión, la cuenta anterior sigue vigente y la Entity sigue recibiendo splits. Cuando el nuevo onboarding se aprueba, la nueva cuenta reemplaza a la anterior. Si se rechaza, no cambia nada.

Paso 3: Crear un Checkout Session con split

Agrega un arreglo split al Checkout Session. Cada entrada nombra a una Entity y su parte.

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
--header 'Authorization: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 150000,
  "currency": "CLP",
  "customer_email": "buyer@example.com",
  "success_url": "https://merchant.example/success",
  "cancel_url": "https://merchant.example/cancel",
  "metadata": { "order_id": "ORD-1234" },
  "split": [
    { "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N", "type": "flat", "amount": 50000 },
    { "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q", "type": "flat", "amount": 45000 },
    { "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T", "type": "flat", "amount": 30000 },
    { "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R", "type": "flat", "amount": 25000,
      "charge_processing_fee": true }
  ]
}'

Campo	Tipo	Requerido	Descripción
`split`	array	No	Reglas que se usan para dividir el pago. Omítelo y el 100% de la liquidación va a ti. Entre 1 y 10 entradas.
`split[].entity_id`	string	Sí	ID de una Entity cuya capability `settlement_recipient` está `operational`.
`split[].type`	string	Sí	`flat` o `percentage`. Todas las entradas deben usar el mismo tipo.
`split[].amount`	integer	Sí	Para `flat`, el monto en la unidad menor de la moneda. Para `percentage`, puntos base donde `10000` = 100%.
`split[].charge_processing_fee`	boolean	Sí, en exactamente una entrada	El destinatario que absorbe la comisión de procesamiento del pago.
`split[].metadata`	object	No	Datos clave-valor adjuntos a esta regla. Se devuelven en los webhooks.

Las reglas del split deben sumar exactamente el monto del pago. No hay residuo: si te quedas con parte del pago, declara tu propia entity raíz como otra entrada, como en el ejemplo de arriba. Recupérala con GET /v2/entities?is_root=true.

Los porcentajes se expresan en puntos base. 10000 = 100%, 1000 = 10%, 1 = 0.01%. Para asignar el 90%, envía 9000.

La respuesta hace eco del arreglo split tal como lo enviaste, junto con el redirect_url de la página de pago. Envía al cliente allí para completar el pago. En la vuelta, en los webhooks (ver Paso 4), cada entrada del split viene completa: todas incluyen metadata (aunque venga vacío) y un charge_processing_fee explícito (false en las entradas que no absorben la comisión). Al crear la sesión estos campos siguen siendo opcionales: no necesitas enviar metadata, y charge_processing_fee solo se envía en la entrada que absorbe la comisión.

Paso 4: Manejar los eventos posteriores al pago

Cuando el pago llega a un estado final, checkout_session.finished y payment_intent.succeeded incluyen un arreglo split_applied con el monto resuelto para cada destinatario.

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "object": "checkout_session",
    "amount": 150000,
    "currency": "CLP",
    "status": "finished",
    "metadata": { "order_id": "ORD-1234" },
    "split": [
      { "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N", "type": "flat", "amount": 50000, "charge_processing_fee": false, "metadata": {} },
      { "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q", "type": "flat", "amount": 45000, "charge_processing_fee": false, "metadata": {} },
      { "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T", "type": "flat", "amount": 30000, "charge_processing_fee": false, "metadata": {} },
      { "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R", "type": "flat", "amount": 25000, "charge_processing_fee": true, "metadata": {} }
    ],
    "split_applied": [
      {
        "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N",
        "calculated_amount": 50000,
        "charge_processing_fee": false
      },
      {
        "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q",
        "calculated_amount": 45000,
        "charge_processing_fee": false
      },
      {
        "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T",
        "calculated_amount": 30000,
        "charge_processing_fee": false
      },
      {
        "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R",
        "calculated_amount": 25000,
        "charge_processing_fee": true
      }
    ],
    "payment_resource": {
      "payment_intent": {
        "id": "pi_38DNJo3rbvGUzKFvCGZ6dxR1Kxx",
        "object": "payment_intent",
        "status": "succeeded",
        "split_applied": [
          {
            "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N",
            "calculated_amount": 50000,
            "charge_processing_fee": false
          },
          {
            "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q",
            "calculated_amount": 45000,
            "charge_processing_fee": false
          },
          {
            "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T",
            "calculated_amount": 30000,
            "charge_processing_fee": false
          },
          {
            "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R",
            "calculated_amount": 25000,
            "charge_processing_fee": true
          }
        ]
      }
    }
  }
}

split_applied aparece dos veces en checkout_session.finished: una en el propio checkout_session y otra dentro de data.payment_resource.payment_intent. Ambos arreglos tienen exactamente el mismo contenido, así que puedes leer cualquiera de los dos. La copia anidada es la misma que entrega el evento payment_intent.succeeded, que se emite junto con checkout_session.finished.

checkout_session.finished puede llegar antes de que el pago haya alcanzado un estado final. Marca la orden como pagada solo cuando data.payment_resource.payment_intent.status sea succeeded.

Eventos a manejar:

Evento	Cuándo
`checkout_session.finished`	La sesión llegó a un estado final. Incluye `split` y `split_applied`.
`checkout_session.expired`	La sesión expiró antes del pago.
`payment_intent.succeeded`	El pago fue exitoso.
`payment_intent.failed`	El pago falló.
`payment_intent.requires_action`	El pago necesita una acción adicional del pagador.
`payout.created`	Se creó una liquidación hacia un destinatario para el ciclo de liquidación.
`payout.succeeded`	La liquidación llegó a la cuenta del destinatario.
`payout.canceled`	La liquidación fue cancelada y no se enviará.
`payout.returned`	Una liquidación exitosa fue devuelta por el banco. Solo México.
`entity.onboarding.approved`	La Entity pasó la revisión y puede recibir splits.
`entity.onboarding.rejected`	La revisión falló.

Cómo y cuándo se paga a los destinatarios

Las liquidaciones siguen el calendario de liquidaciones de tu organización. En cada ciclo, Fintoc agrupa cada parte que se le debe a la misma Entity en una única transferencia a su cuenta de liquidación: un destinatario que aparece en 200 pagos durante un ciclo recibe una única transferencia. Recupera una liquidación con GET /v1/payouts/{id}, lístalas con GET /v1/payouts y obtén los pagos que cubre con GET /v1/payouts/{id}/resources.

Los eventos payout.* solo se emiten en modo live. Las liquidaciones se procesan contra balances reales, por lo que el modo test no los emite.

Reglas y validaciones

La solicitud falla con 400 invalid_request_error si el arreglo split viola alguna regla. Por entrada

entity_id debe referenciar una Entity cuyo capabilities.settlement_recipient.status sea operational
El country_code de la Entity debe coincidir con la moneda del pago
Para flat: 0 < amount <= amount_total
Para percentage: 0 < amount <= 10000

Globales

Entre 1 y 10 entradas
Sin valores entity_id duplicados
Todas las entradas deben usar el mismo type
La suma de todos los montos, después de convertir los porcentajes, debe ser exactamente igual a amount_total
Para percentage, los valores deben sumar exactamente 10000 bps

Redondeo. Los montos en porcentaje se calculan como floor(amount_total * amount / 10000). La diferencia de redondeo acumulada se asigna a la entrada con charge_processing_fee: true.

Errores

Código	Significado
`ENTITY_NOT_FOUND`	El `entity_id` no existe en tu organización.
`ENTITY_NOT_OPERATIONAL`	La Entity no ha completado su onboarding.
`DUPLICATE_ENTITY_IN_SPLIT`	El mismo `entity_id` aparece más de una vez.
`MIXED_SPLIT_TYPES`	El arreglo mezcla `flat` y `percentage`.
`SPLIT_SUM_MISMATCH`	Los montos no suman exactamente `amount`.
`MISSING_CHARGE_PROCESSING_FEE`	Ninguna entrada tiene `charge_processing_fee` en `true`.
`MULTIPLE_CHARGE_PROCESSING_FEE`	Más de una entrada tiene `charge_processing_fee` en `true`.

{
  "error": {
    "type": "invalid_request_error",
    "message": "Split rules must add up to the total amount",
    "code": "SPLIT_SUM_MISMATCH",
    "param": "split"
  }
}

​Antes de comenzar

​Paso 1: Crear una Entity

​Paso 2: Hacer el onboarding de la Entity

​Crear el onboarding

​Tipo de onboarding

​La cuenta de liquidación

​Chile

​México

​Campos del onboarding

​Enviar el onboarding

​Cambiar la cuenta de liquidación

​Paso 3: Crear un Checkout Session con split

​Paso 4: Manejar los eventos posteriores al pago

​Cómo y cuándo se paga a los destinatarios

​Reglas y validaciones

​Errores

Antes de comenzar

Paso 1: Crear una Entity

Paso 2: Hacer el onboarding de la Entity

Crear el onboarding

Tipo de onboarding

La cuenta de liquidación

Chile

México

Campos del onboarding

Enviar el onboarding

Cambiar la cuenta de liquidación

Paso 3: Crear un Checkout Session con split

Paso 4: Manejar los eventos posteriores al pago

Cómo y cuándo se paga a los destinatarios

Reglas y validaciones

Errores