Skip to main content
Divide un cobro recurrente entre destinatarios. Declara la regla una vez y Fintoc la aplica en cada ciclo al monto cobrado. Una suscripción emite una factura por ciclo de facturación y cada factura genera un PaymentIntent cuando Fintoc la cobra. La regla de split y el split aplicado son distintos: la regla declara cómo distribuir los cobros y el split aplicado calcula esa distribución para un cobro. La regla queda en el objeto que la declara. El resultado queda en el PaymentIntent. En un pago único, el resultado también queda en el Checkout Session. Si aún no integras pagos con split, comienza con Aceptar pagos con split. El objeto split es el mismo que envías en un Checkout Session de pago único.
Los endpoints v2 de Subscription e Invoice requieren la versión de API 2026-02-01 o posterior. Consulta Versión de la API.

Dónde puedes declarar la regla

Declara una regla de split en cualquiera de estos puntos de entrada:

El objeto split

Cada entrada de split identifica a un destinatario y su parte:
Los porcentajes usan puntos base: 10000 es 100%, 8500 es 85% y 50 es 0.5%. Una regla de porcentajes debe sumar exactamente 10000.
Una regla siempre debe sumar el monto cobrado. Las reglas de porcentajes se adaptan a los cambios en el monto del cobro. Con flat, mantén la regla sincronizada: actualiza la regla de la suscripción cuando cambies su precio. Actualiza la regla de una factura con PATCH o envía split junto con add_lines o remove_lines cuando edites la factura. Los montos de las suscripciones en UF cambian en cada ciclo sin actualizar el precio, por lo que estas suscripciones no aceptan reglas flat.

Quién paga la comisión de procesamiento

Quién paga depende de si tu organización tiene activo el descuento automático de comisiones:
  • Con descuento automático de comisiones: Cada entrada con charge_processing_fee en true paga la comisión de procesamiento en proporción a su parte del cobro entre esas entradas. Las entradas que envían false u omiten el campo no pagan la comisión. Al menos una entrada debe tener charge_processing_fee en true. Si no, Fintoc rechaza la regla de split con el error MISSING_CHARGE_PROCESSING_FEE.
  • Sin descuento automático de comisiones: Ninguna entrada puede tener charge_processing_fee en true. Si no, Fintoc rechaza la regla de split con el error CHARGE_PROCESSING_FEE_NOT_ALLOWED. Tu organización paga la comisión de procesamiento, que Fintoc cobra en tu factura de fin de período.
Fintoc revisa esto cuando declaras la regla, no cuando cobra una factura. Los ejemplos de esta página tienen charge_processing_fee en true en una entrada, como lo hace una organización con descuento automático de comisiones. Fintoc redondea hacia abajo, a la unidad más pequeña de la moneda, la parte del monto y de la comisión de cada destinatario. El residuo de ambos va a la primera entrada que paga la comisión. Cuando ninguna entrada paga la comisión, el residuo del monto va a la primera entrada.
Si ya integras split en pagos únicos, antes charge_processing_fee debía estar en true en exactamente una entrada. Ahora más de una entrada puede tenerlo en true. El error MULTIPLE_CHARGE_PROCESSING_FEE ya no existe.

Crea una suscripción con una regla de split

Los ejemplos cobran el arriendo mensual de una unidad y lo dividen en tres partes: 85% para el propietario, 10% para la corredora y 5% para tu plataforma. Cada destinatario es una Entity de tu organización. El propietario paga la comisión de procesamiento, así que solo su entrada tiene charge_processing_fee en true. Servidor
La suscripción comienza en incomplete y pasa a active cuando el primer pago tiene éxito. Su split contiene la regla con los valores predeterminados completos, sin importar el estado del cobro. Consulta el PaymentIntent para obtener los montos calculados.

Crea un Checkout Session de suscripción con una regla de split

Usa este flujo cuando tu cliente aún necesita autorizar el medio de pago. Envía split junto con flow: subscription. Fintoc traspasa la regla a la suscripción que crea la sesión. Servidor
Fintoc valida la regla cuando creas la sesión, no cuando tu cliente la completa. Si una Entity no existe o no te pertenece, la solicitud falla en vez de crear una suscripción inválida. Fintoc vuelve a comprobar si el destinatario está operativo al momento del cobro.

Actualiza la regla de una suscripción

Envía split en PATCH /v2/subscriptions/{id} para reemplazar la regla. La nueva regla aplica a las facturas que la suscripción emite desde ese momento. Las facturas existentes conservan la regla heredada, incluso mientras están en draft. Fintoc reemplaza la regla completa en vez de combinar las entradas, así que envía todas las entradas que quieras conservar. Servidor
Esta respuesta supone que el primer pago aún no tiene éxito. Actualizar la regla no cambia el estado de la suscripción.
Si tu regla usa flat, actualízala cada vez que cambies el precio de un ítem de la suscripción. Si la regla ya no suma el total de los ítems, la suscripción reporta status: "inconsistent" con reason: "split_amount_mismatch". Fintoc no puede finalizar la siguiente factura hasta que la regla vuelva a sumar. Consulta Descuadres del split al finalizar.

Reemplaza la regla para un ciclo

Cada factura copia la regla de su suscripción al momento de su creación, en vez de mantener una referencia dinámica. Este comportamiento tiene tres consecuencias:
  • Cambiar la regla de la suscripción afecta a las facturas futuras, no a las existentes.
  • Una regla que declaras en una factura reemplaza la regla heredada solo para ese ciclo.
  • Una factura sin regla declarada ni heredada cobra sin split y te asigna el 100%.
Cada entrada del split de una factura indica el origen de su regla en el campo inherited. El campo es true cuando la factura copió la regla de su suscripción. El campo es false cuando declaraste la regla en la factura, ya sea en una factura independiente o como reemplazo para un ciclo. Para reemplazar el split de un ciclo de suscripción, edita su factura mientras está en draft. Desde el segundo ciclo, Fintoc crea cada factura en draft y la finaliza 1 hora después. La primera factura no pasa por draft, así que no puedes reemplazar su regla de esta forma. Consulta Invoices en el flujo de suscripción. El reemplazo no cambia la regla de la suscripción ni ningún otro ciclo. PATCH /v2/invoices/{id} reemplaza la regla completa, que debe sumar el total actual de la factura. Si también cambias el monto, envía split junto con add_lines o remove_lines. El monto y la regla cambian en la misma solicitud y mantienen la factura balanceada. Este ejemplo agrega una línea de gastos comunes de 30000 a la factura de noviembre. Solo para este ciclo, el propietario recibe 430000, la corredora no recibe nada y tu plataforma conserva 50000. Los montos flat suman el nuevo total de 480000. Servidor

Crea una factura con una regla de split

Para cobrar una factura independiente con su propia regla, envía split en POST /v2/invoices. Una factura independiente no depende de tus suscripciones ni cambia sus reglas. Las librerías de Fintoc para Node y Python no crean facturas. Llama al endpoint Crear una factura por HTTP, como en este ejemplo con curl. Servidor
curl
Esta factura independiente permanece en draft hasta que la finalices. La finalización la mueve a open e inicia el cobro con default_payment_method.

Consulta el split aplicado

Cuando Fintoc cobra la factura, crea un PaymentIntent y aplica la regla a su monto. El resultado es split_applied, el mismo objeto que recibes en los pagos únicos. Los pagos únicos siguen informando el resultado como antes. Payload del webhook Este ejemplo muestra la primera factura de la suscripción, que heredó la regla de porcentajes original, no la factura independiente anterior.
Maneja estos eventos para seguir los cobros y sus splits: Los eventos incluyen el mismo split_applied porque el resultado queda en el PaymentIntent. El PaymentIntent es común a todos los orígenes: una sesión de pago único, un ciclo de suscripción o una factura independiente. Una factura expone el split de su último intento de cobro. Si un cobro falla y reintentas, el nuevo intento calcula su propio split sobre el mismo monto. Solo el intento que se liquida mueve dinero.

Cuando un destinatario ya no está operativo

Una Entity puede dejar de ser elegible para recibir liquidaciones después de que declares la regla. Por ejemplo, Fintoc puede pausar la cuenta de la Entity durante una revisión de cumplimiento. Considera que la elegibilidad puede cambiar mientras una suscripción cobra cada mes. El cobro continúa. Fintoc cobra la factura como siempre y abona la parte de ese destinatario a la Entity raíz de tu organización. El resto del split no cambia y el pagador no ve ninguna diferencia. Hasta que la Entity vuelva a estar operativa, mantienes fondos que corresponden a tu destinatario. No abones a ese destinatario en tu contabilidad una parte redirigida. Fintoc redirige una parte cuando, al momento del cobro, el capabilities.settlement_recipient.status del destinatario no es operational o la Entity ya no existe. Esto también aplica cuando tu cliente paga la factura con una Checkout Session. Cada entrada de split_applied en la factura y en su PaymentIntent indica si Fintoc redirigió esa parte: Lee estos campos en el payload de invoice.payment_succeeded. El Dashboard también marca cada parte redirigida en la factura y el pago. Para reaccionar apenas Fintoc redirija una parte, suscríbete a invoice.split_redirected. Fintoc envía este evento cuando crea un intento de cobro de una factura y al menos una entrada de split_applied tiene redirected en true. El data del evento es la factura, con los mismos campos que los demás eventos de facturas. Fintoc no envía el evento en los intentos de cobro sin partes redirigidas.

Descuadres del split al finalizar

Fintoc vuelve a revisar la regla cuando finaliza una factura. Una regla no pasa esa revisión cuando sus montos flat no suman el total de la factura, o cuando una entrada percentage resulta en un monto de 0. Esto puede pasar cuando cambias las líneas de la factura o el precio de un ítem de la suscripción sin actualizar una regla flat. Mientras la regla no sume, la API reporta el descuadre en ambos objetos:
  • Una factura en draft reporta status: "inconsistent" con reason: "split_amount_mismatch".
  • Una suscripción cuya regla ya no suma el total de sus ítems reporta status: "inconsistent" con el mismo reason. La siguiente factura copia esa regla, así que Fintoc tampoco puede finalizarla.
reason es null en todos los demás estados. Cuando Fintoc intenta finalizar una factura inconsistente, Fintoc deja la factura en draft, no la cobra y envía invoice.finalization_failed. Fintoc no reintenta la finalización. Si llamas tú a Finalizar una factura, la solicitud falla con el error SPLIT_AMOUNT_MISMATCH. Para recuperarte:
  1. Envía una regla que sume el total de la factura con PATCH /v2/invoices/{id}. Si la suscripción causó el descuadre, actualiza también la regla de la suscripción para que las siguientes facturas sumen.
  2. Finaliza la factura con Finalizar una factura. La finalización mueve la factura a open e inicia el cobro.

Errores

Declarar una regla devuelve los mismos errores de validación que un Checkout Session de pago único, listados en Errores en Aceptar pagos con split. También puedes recibir estos códigos: Estos casos no generan un split y no son errores:
  • Una factura liquidada fuera de Fintoc con external_payment: true. No existe un PaymentIntent que dividir.
  • Una factura con monto cero. Fintoc marca la factura como pagada sin crear un PaymentIntent.
  • Una factura anulada. Anular la factura también anula su regla.
  • Una suscripción cancelada. Las facturas existentes siguen siendo válidas y conservan la regla heredada.

Prueba tu integración

Verifica cobros exitosos, cambios de monto y reglas flat desbalanceadas en modo test:
  1. Con tu secret key de prueba, crea una suscripción con una regla split de porcentajes y al menos dos Entities de prueba. Para crearlas y hacer su onboarding, sigue Crear una Entity.
  2. Espera el cobro simulado de la primera factura, como se describe en Prueba tu integración. Comprueba que invoice.payment_succeeded incluya split_applied y que todos los valores calculated_amount sumen el monto de la factura.
  3. Crea un Checkout Session de suscripción con la misma regla y el nombre de producto sandbox_draft. Fintoc crea su factura en draft, como se describe en Probar la creación de invoice con estado draft. Usa Agregar líneas para agregar una línea de 1, de modo que el total no se divida en partes exactas. Cuando Fintoc cobre la factura, comprueba que los porcentajes se calculen sobre el nuevo total y que el residuo del redondeo vaya a la primera entrada que paga la comisión.
  4. Repite el paso 3 con otra suscripción sandbox_draft. Mientras su factura está en draft, usa PATCH /v2/invoices/{id} para reemplazar la regla de la factura por una regla flat que sume el total. Luego agrega una línea sin enviar split. Revisa que la factura reporte status: "inconsistent" con reason: "split_amount_mismatch". Cuando Fintoc intenta finalizar la factura, la factura queda en draft y recibes invoice.finalization_failed.