Skip to main content
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. También puedes dividir un Payment Intent que creas por API. Revisa Dividir un Payment Intent creado por API. 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:
  1. Crear una Entity para cada destinatario
  2. Hacer el onboarding de la Entity, incluyendo la cuenta donde recibirá el pago
  3. 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 secret key y public key
  • 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.
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

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

México

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

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:
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: Dos webhooks te avisan del resultado:
  • entity.onboarding.approved — la Entity está lista para recibir splits
  • entity.onboarding.rejected — la revisión falló
Cada evento lleva el onboarding completo, incluida la settlement_account que declaraste, así que puedes leer los datos revisados sin llamar a la API. Revisa el payload de settlement recipient.
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.
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 pagan la comisión). Al crear la sesión, metadata sigue siendo opcional. Solo necesitas enviar charge_processing_fee en las entradas que pagan la comisión. Quién paga la comisión de procesamiento. Depende de si tu organización tiene activo el descuento automático de comisiones:
  • Con descuento automático de comisiones: Al menos una entrada debe tener charge_processing_fee en true. Cuando más de una entrada lo tiene, Fintoc divide la comisión de procesamiento entre esas entradas en proporción a su parte del monto del pago. Fintoc redondea cada parte hacia abajo a la unidad más pequeña de la moneda y suma el residuo del redondeo a la primera entrada que paga la comisión. Fintoc descuenta cada parte de la dispersión de ese destinatario. Los montos del split no cambian.
  • Sin descuento automático de comisiones: Ninguna entrada puede tener charge_processing_fee en true, así que omítelo o envía false en todas las entradas. Tu organización paga la comisión de procesamiento, que Fintoc cobra en tu factura de fin de período. Cada destinatario recibe su monto de split completo.
Los ejemplos de esta guía tienen charge_processing_fee en true en una entrada, como lo hace una organización con descuento automático de comisiones.

Dividir un Payment Intent creado por API

El split en Payment Intents funciona en modo test y en modo live. En modo live, tu organización debe estar habilitada para split payments, igual que con una Checkout Session. Si no lo está, Fintoc rechaza un Payment Intent que incluye un arreglo split con el estado 400 Bad Request y el código split_not_available.
Para dividir un pago sin un Checkout Session, envía el mismo arreglo split al crear un Payment Intent con POST /v2/payment_intents o POST /v1/payment_intents. Las entradas usan los mismos campos y reglas que en un Checkout Session, y los montos del split deben sumar el amount del Payment Intent.
La respuesta es el objeto PaymentIntent completo. Incluye el arreglo split con cada entrada completa y un arreglo split_applied con el monto calculado para cada destinatario:

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.
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 las mismas entradas y montos, así que puedes leer cualquiera de los dos. La copia anidada en el PaymentIntent también incluye redirected, redirected_to_entity_id y redirection_reason. En una Checkout Session de pago único, redirected siempre es false. 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:

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.

Reembolsar un pago con split

Solo puedes reembolsar un pago con split por el monto total. Crea un reembolso sin amount, o con amount igual al monto total del pago. Fintoc rechaza los reembolsos parciales de pagos con split. Cada destinatario financia su parte original del pago. Los destinatarios con charge_processing_fee: true también pagan la comisión del reembolso, dividida de la misma forma que la comisión de procesamiento. Si ninguna entrada tiene charge_processing_fee: true, tu organización paga la comisión del reembolso. Si algún destinatario no tiene saldo suficiente para financiar su parte, el reembolso queda pendiente mientras Fintoc lo reintenta durante un máximo de 5 días hábiles. Para conocer los estados del reembolso y los eventos de webhook, consulta Reembolsar pagos.

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 primera entrada con charge_processing_fee: true, o a la primera entrada cuando ninguna paga la comisión.

Errores