Cálculo de split - Z2Pay Developers

Split es la división del valor de un pago entre dos o más destinatarios (rec_). Usted define una configuración de split (porcentual o valores fijos), y Z2Pay calcula cuánto recibe cada destinatario, quién asume la tarifa de procesamiento y quién es el responsable financiero de la transacción. Esta página explica cómo funciona el cálculo, con ejemplos numéricos. Para crear, editar y listar configuraciones de split (el CRUD de la API), consulte Core API · Splits.

Todos los valores en esta página son enteros en centavos. Un pago de R$ 100,00 equivale a 10000. Consulte Convenciones.

Anatomía de un ítem de split

Una configuración de split es una lista (config) de ítems. Cada ítem describe la porción de un destinatario:

recipientId

string

requerido

ID del destinatario que recibe esta porción (rec_...). El destinatario debe existir y estar vinculado al gateway utilizado en el pago.

value

number

requerido

Valor de la porción. Mínimo 0.01. Cuando valueType es percentage, es el porcentaje (ej.: 60 = 60%). Cuando es fixed, es el valor en centavos (ej.: 3000 = R$ 30,00).

valueType

string

requerido

Cómo interpretar value. Uno de:

percentage — value es un porcentaje.
fixed — value es un valor fijo en centavos.

type

string

predeterminado:"sale"

Naturaleza de la porción. Uno de:

sale — porción de venta (predeterminado).
interest — porción de intereses/recargos.
platform_fee — porción de la plataforma (tarifa de marketplace). Tiene un efecto especial en el cálculo (consulte Cuando existe platform_fee).

processingFee

boolean

Indica que este destinatario asume la tarifa de procesamiento (MDR/adquirencia) del pago. Opcional en el ítem, pero la configuración completa debe tener exactamente un ítem con processingFee: true.

liable

boolean

Indica que este destinatario es el responsable financiero de la transacción — quien responde por devoluciones, contracargos y absorbe los excedentes de redondeo. Opcional en el ítem, pero la configuración completa debe tener exactamente un ítem con liable: true.

Reglas de validación

Al guardar o utilizar una configuración de split, Z2Pay valida:

La lista debe tener al menos 1 ítem

config no puede estar vacía.

Si es porcentual, la suma debe ser 100%

Cuando los ítems usan valueType: "percentage", la suma de todos los value debe ser exactamente 100 (tolerancia de 0.01). De lo contrario, la solicitud es rechazada con el mensaje “La suma de los porcentajes debe ser 100%”.

Exactamente 1 ítem con processingFee

Ni cero, ni dos. Exactamente un ítem de la lista debe tener processingFee: true.

Exactamente 1 ítem con liable

La misma regla: exactamente un ítem debe tener liable: true.

Las reglas de processingFee y liable aplican a la configuración en su conjunto. Si construye la lista sin ningún ítem marcado (o con más de uno), la validación falla. Los errores de validación de payload retornan 400 (VALIDATION_ERROR); consulte Errores.

Cómo se calcula el valor de cada porción

El valor (amount) de cada ítem, en centavos, depende del valueType:

`valueType`	Fórmula	Observación
`percentage`	`floor(valorDelPago × value / 100)`	Redondea hacia abajo (trunca centavos).
`fixed`	`value`	Se usa tal cual (ya está en centavos).

El redondeo de porcentajes es siempre hacia abajo (floor). Por eso la suma de las porciones puede quedar algunos centavos por debajo del valor total — ese excedente se trata en la siguiente sección.

`processingFee` y `liable`, en una frase cada uno

processingFee → quién paga la tarifa de procesamiento (MDR/adquirencia) de ese pago.
liable → quién es el responsable financiero: responde por devoluciones/contracargos y absorbe el excedente de redondeo (los centavos restantes del floor).

Redondeo mediante el responsable (excedente)

Cuando la suma de las porciones no coincide exactamente con el valor del pago (efecto del floor en los porcentajes), la diferencia restante se suma a la porción del responsable de la tarifa. De este modo, el split siempre cierra con el valor total, al centavo.

En la práctica: el destinatario que asume la tarifa de procesamiento es también quien recibe (o pierde) los centavos de redondeo. Esto mantiene la cuenta exacta sin distribuir fracciones entre todos.

Ejemplo 1 — Split porcentual simple (60/40)

Pago de R$ 100,00 (10000 centavos), dividido entre dos destinatarios: 60% para el comerciante, 40% para un socio. El comerciante asume la tarifa y es el responsable.

{
  "name": "Lojista + parceiro 60/40",
  "config": [
    {
      "recipientId": "rec_lojista",
      "type": "sale",
      "value": 60,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_parceiro",
      "type": "sale",
      "value": 40,
      "valueType": "percentage"
    }
  ]
}

Cálculo sobre 10000:

Destinatario	Porcentaje	`floor(10000 × %)`	Tras excedente
`rec_lojista`	60%	`6000`	`6000`
`rec_parceiro`	40%	`4000`	`4000`
Total	100%	`10000`	`10000`

En este caso no hay excedente: 6000 + 4000 = 10000.

Ejemplo 2 — Redondeo (el excedente va al responsable)

Pago de R$ 100,01 (10001 centavos), mismo split 60/40.

Destinatario	Porcentaje	`floor(10001 × %)`	Tras excedente
`rec_lojista`	60%	`floor(6000,6)` = `6000`	`6000 + 1` = `6001`
`rec_parceiro`	40%	`floor(4000,4)` = `4000`	`4000`
Total	100%	`10000` (falta `1`)	`10001`

6000 + 4000 = 10000, faltó 1 centavo para cerrar los 10001. Como rec_lojista es quien asume la tarifa (processingFee: true), absorbe el excedente y recibe 6001. El split cierra exacto.

Ejemplo 3 — Valores fijos con varios destinatarios

Pago de R$ 150,00 (15000 centavos), dividido en valores fijos para tres destinatarios. El primero asume la tarifa y es el responsable.

{
  "name": "Três fornecedores (fixo)",
  "config": [
    {
      "recipientId": "rec_fornecedorA",
      "type": "sale",
      "value": 10000,
      "valueType": "fixed",
      "processingFee": true,
      "liable": true
    },
    { "recipientId": "rec_fornecedorB", "type": "sale", "value": 3000, "valueType": "fixed" },
    { "recipientId": "rec_fornecedorC", "type": "sale", "value": 2000, "valueType": "fixed" }
  ]
}

Destinatario	`value` (centavos)	Recibe
`rec_fornecedorA`	`10000`	`10000`
`rec_fornecedorB`	`3000`	`3000`
`rec_fornecedorC`	`2000`	`2000`
Total	—	`15000`

En split fijo, la suma de los valores es responsabilidad suya — Z2Pay no fuerza que coincida con el valor del pago. Si la suma de las porciones fijas no cierra con el total, la diferencia va a la porción del responsable de la tarifa (mismo mecanismo de excedente del Ejemplo 2). Asegúrese de que los valores fijos sumen lo que espera.

No puede mezclar porcentual y fijo en la lógica de suma: si hay ítems percentage, la suma de ellos debe ser 100%. Mantenga la configuración coherente (todos porcentajes sumando 100, o valores fijos consistentes con el pago).

Cuando existe `platform_fee`

Si algún ítem de la configuración tiene type: "platform_fee", la plataforma (propietaria de la platform_fee) asume automáticamente el rol de responsable, independientemente de los flags individuales:

La porción platform_fee pasa a ser quien asume la tarifa de procesamiento.
La porción platform_fee pasa a ser la liable (responsable financiera).
La porción platform_fee absorbe el excedente de redondeo.

Es decir: existiendo platform_fee, los flags processingFee/liable de los demás ítems no cambian quién asume la tarifa/responsabilidad en el cálculo — la plataforma lo asume. Use platform_fee para modelar la tarifa del marketplace.

Ejemplo 4 — Marketplace con `platform_fee`

Pago de R$ 100,00 (10000 centavos): 90% para el vendedor, 10% de tarifa de la plataforma.

{
  "name": "Marketplace 90/10",
  "config": [
    {
      "recipientId": "rec_vendedor",
      "type": "sale",
      "value": 90,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_plataforma",
      "type": "platform_fee",
      "value": 10,
      "valueType": "percentage"
    }
  ]
}

Destinatario	Tipo	`floor(10000 × %)`	Rol en el cálculo
`rec_vendedor`	`sale`	`9000`	Recibe `9000`
`rec_plataforma`	`platform_fee`	`1000`	Asume tarifa, `liable`, absorbe excedente
Total	—	`10000`	—

Aunque rec_vendedor tenga processingFee: true y liable: true en el JSON, como existe un ítem platform_fee es la plataforma quien asume la tarifa y la responsabilidad en el cálculo de las reglas enviadas al gateway. La configuración aún debe respetar la regla de “exactamente 1 processingFee y 1 liable” al momento de guardar.

Dónde aparece el split después

Cada pago procesado con split genera registros de split de pago (uno por destinatario), con el amount calculado en centavos, el type, el valueType, y los flags processingFee/liable efectivos. Puede consultar esos registros a través de Core API · Splits.

Errores comunes

Situación	Status	Dónde ver
Suma de porcentajes diferente de 100%	400	Errores
Ningún ítem o más de uno con `processingFee`	400	Errores
Ningún ítem o más de uno con `liable`	400	Errores
Destinatario sin vínculo en el gateway del pago	422	Errores

Ver también

Core API · Splits

CRUD de configuraciones de split y consulta de los splits de un pago.

Destinatarios

Registre los destinatarios (rec_) que participan en el split.

Visión general de valores

Cómo se articulan las tarifas, el split y la liquidación.

Liquidación

Cuándo y cómo se liquida cada porción al destinatario.

​Anatomía de un ítem de split

​Reglas de validación

​Cómo se calcula el valor de cada porción

​processingFee y liable, en una frase cada uno

​Redondeo mediante el responsable (excedente)

​Ejemplo 1 — Split porcentual simple (60/40)

​Ejemplo 2 — Redondeo (el excedente va al responsable)

​Ejemplo 3 — Valores fijos con varios destinatarios

​Cuando existe platform_fee

​Ejemplo 4 — Marketplace con platform_fee

​Dónde aparece el split después

​Errores comunes

​Ver también

Core API · Splits

Destinatarios

Visión general de valores

Liquidación

Anatomía de un ítem de split

Reglas de validación

Cómo se calcula el valor de cada porción

`processingFee` y `liable`, en una frase cada uno

Redondeo mediante el responsable (excedente)

Ejemplo 1 — Split porcentual simple (60/40)

Ejemplo 2 — Redondeo (el excedente va al responsable)

Ejemplo 3 — Valores fijos con varios destinatarios

Cuando existe `platform_fee`

Ejemplo 4 — Marketplace con `platform_fee`

Dónde aparece el split después

Errores comunes

Ver también