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 desplit 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_feeentruepaga la comisión de procesamiento en proporción a su parte del cobro entre esas entradas. Las entradas que envíanfalseu omiten el campo no pagan la comisión. Al menos una entrada debe tenercharge_processing_feeentrue. Si no, Fintoc rechaza la regla de split con el errorMISSING_CHARGE_PROCESSING_FEE. - Sin descuento automático de comisiones: Ninguna entrada puede tener
charge_processing_feeentrue. Si no, Fintoc rechaza la regla de split con el errorCHARGE_PROCESSING_FEE_NOT_ALLOWED. Tu organización paga la comisión de procesamiento, que Fintoc cobra en tu factura de fin de período.
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 tienecharge_processing_fee en true.
Servidor
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íasplit junto con flow: subscription. Fintoc traspasa la regla a la suscripción que crea la sesión.
Servidor
Actualiza la regla de una suscripción
Envíasplit 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
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%.
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íasplit 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
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 unPaymentIntent 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.
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, elcapabilities.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 montosflat 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
draftreportastatus: "inconsistent"conreason: "split_amount_mismatch". - Una suscripción cuya regla ya no suma el total de sus ítems reporta
status: "inconsistent"con el mismoreason. 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:
- Envía una regla que sume el
totalde la factura conPATCH /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. - Finaliza la factura con Finalizar una factura. La finalización mueve la factura a
opene 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 unPaymentIntentque 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 reglasflat desbalanceadas en modo test:
- Con tu secret key de prueba, crea una suscripción con una regla
splitde porcentajes y al menos dos Entities de prueba. Para crearlas y hacer su onboarding, sigue Crear una Entity. - Espera el cobro simulado de la primera factura, como se describe en Prueba tu integración. Comprueba que
invoice.payment_succeededincluyasplit_appliedy que todos los valorescalculated_amountsumen el monto de la factura. - Crea un Checkout Session de suscripción con la misma regla y el nombre de producto
sandbox_draft. Fintoc crea su factura endraft, como se describe en Probar la creación de invoice con estadodraft. Usa Agregar líneas para agregar una línea de1, 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. - Repite el paso 3 con otra suscripción
sandbox_draft. Mientras su factura está endraft, usaPATCH /v2/invoices/{id}para reemplazar la regla de la factura por una reglaflatque sume el total. Luego agrega una línea sin enviarsplit. Revisa que la factura reportestatus: "inconsistent"conreason: "split_amount_mismatch". Cuando Fintoc intenta finalizar la factura, la factura queda endrafty recibesinvoice.finalization_failed.