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 el payout 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
Al menos una Entity en estado operational (ver los pasos 1 y 2)

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": "Estudio Rojas SpA",
  "holder_id": "761234567"
}'

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. RUT en Chile, RFC en México. Debe ser único dentro de tu organización.

{
  "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "object": "entity",
  "country_code": "cl",
  "holder_id": "761234567",
  "holder_name": "Estudio Rojas SpA",
  "is_root": false,
  "mode": "live",
  "status": "waiting_initialization"
}

Una Entity nueva comienza en waiting_initialization. No puede recibir un split hasta que llegue a operational, lo que sucede cuando se aprueba su onboarding.

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

El onboarding es donde la Entity declara quién es y, lo más importante para Split Payments, la cuenta bancaria donde recibirá el pago. Fintoc lo revisa, y cuando se aprueba, 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": "Camila",
        "last_name": "Rojas",
        "email": "test@mail.com",
        "nationality": "CL",
        "identification_number": "15123456K",
        "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 esta Entity en cada split. Es el único campo que Split Payments agrega al onboarding.

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

No lleva campos de titular: el titular de la cuenta es la empresa que se está onboardeando, 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. Para Entities de persona natural, `settlement_account` es el único subcampo requerido — los demás (`business_activity`, `business_address`, `phone`) son opcionales. Para Entities de empresa, los cuatro subcampos son requeridos.
`data.legal_representatives[]`	No	Nombre, email, nacionalidad, identificación y cargo de cada representante legal.
`data.transactional_profile`	No	Volumen mensual esperado, número de operaciones y origen de los fondos.
`data.shareholders[]`	No	Estructura de propiedad, con el identificador fiscal y porcentaje de participación de cada accionista.
Documentos	No	Archivos de respaldo, subidos por slot con `PUT`. Hasta 20 MB cada uno; volver a subir un slot reemplaza el archivo.

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'

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 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% del payout va a ti. Entre 1 y 10 entradas.
`split[].entity_id`	string	Sí	ID de una Entity `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.

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

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ó un payout hacia un destinatario para el ciclo de liquidación.
`payout.succeeded`	El payout llegó a la cuenta del destinatario.
`payout.canceled`	El payout fue cancelado y no se enviará.
`payout.returned`	Un payout exitoso fue devuelto 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

Los payouts siguen el calendario de liquidación 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 un payout con GET /v1/payouts/{id}, lístalos 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. Los payouts se liquidan contra balances reales, por lo que el modo test no los emite.

Reglas y validaciones

La solicitud falla con 400 invalid_request_error si se viola alguna regla. Por entrada

entity_id debe referenciar una Entity en estado 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

​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

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