Saltar al contenido principal
Un split config es una regla reutilizable que describe cómo dividir el monto de una transacción entre sus recipients. Usted crea la configuración una vez y la referencia después (por id o inline) al crear transacciones.
Para entender el modelo conceptual de split, los tipos de ítem y ejemplos numéricos paso a paso, consulte Split. Esta página cubre únicamente el CRUD de la configuración.

​
Endpoints

MétodoRutaDescripción
GET/splitsLista paginada de split configs
GET/splits/{id}Obtiene un split config por ID
POST/splitsCrea un split config
PUT/splits/{id}Actualiza un split config
DELETE/splits/{id}Elimina un split config (soft delete)
Todas las solicitudes utilizan el header x-api-key. Consulte Autenticación.

​
El objeto split config

Un split config tiene un name, opcionalmente vínculos con ventas/checkout, y un array config con las reglas de división (los “ítems de split”).

​
Ítem de split (config[])

​
recipientId
string
requerido
ID del recipient que recibe esta parte del monto. No puede estar vacío.
​
type
string
predeterminado:"sale"
Tipo de la porción. Valores aceptados: sale, interest, platform_fee.
​
value
number
requerido
Valor de la porción. Debe ser mayor que 0 (mínimo 0.01). La interpretación depende de valueType.
​
valueType
string
requerido
Cómo interpretar value. Valores aceptados: percentage (porcentaje de 0 a 100) o fixed (valor fijo).
​
processingFee
boolean
Marca el ítem que asume la tarifa de procesamiento. Exactamente 1 ítem del array debe tener processingFee: true.
​
liable
boolean
Marca el ítem responsable (liable) en caso de chargeback/disputa. Exactamente 1 ítem del array debe tener liable: true.
Reglas de validación del array config (retornan 400 si se violan):
  • Al menos 1 ítem de split es obligatorio.
  • Exactamente 1 ítem con processingFee: true.
  • Exactamente 1 ítem con liable: true.
  • Si existe al menos un ítem con valueType: "percentage", la suma de los value de esos ítems porcentuales debe ser exactamente 100 (tolerancia de 0.01). Los ítems fixed no se incluyen en esa suma.
Con respecto a fixed: cuando valueType es fixed, value es un monto monetario en centavos (entero), siguiendo la convención de valores de Z2Pay.

​
Listar split configs

GET /splits
Retorna una lista paginada de los split configs de su company.

​
Query params

​
name
string
Filtra por nombre.
​
isActive
boolean
Filtra por estado de activación (true/false).
​
salesKey
string
Filtra por la clave de venta vinculada.
​
checkoutId
string
Filtra por el checkout vinculado.
​
startDate
string
Fecha inicial del intervalo de creación. ISO 8601 con timezone (ej.: 2026-01-01T00:00:00-03:00).
​
endDate
string
Fecha final del intervalo de creación. ISO 8601 con timezone.
​
page
number
Número de página (paginación).
​
limit
number
Ítems por página (paginación).
curl -G https://api.sandbox.z2pay.com/splits \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d isActive=true \
  -d page=1 \
  -d limit=20

​
Obtener split config por ID

GET /splits/{id}
Retorna un split config específico con sus reglas.
​
id
string
requerido
ID del split config.
curl https://api.sandbox.z2pay.com/splits/spl_4f8a2c1e9b \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Estados posibles: 200 (encontrado) · 404 (no encontrado — consulte Errores). 
{
  "id": "spl_4f8a2c1e9b",
  "name": "Split padrão marketplace",
  "isActive": true,
  "salesKey": null,
  "checkoutId": null,
  "config": [
    {
      "recipientId": "rec_a1b2c3d4e5",
      "type": "sale",
      "value": 90,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_f6g7h8i9j0",
      "type": "platform_fee",
      "value": 10,
      "valueType": "percentage"
    }
  ]
}
El ejemplo anterior es ilustrativo. El conjunto exacto de campos retornados (timestamps, etc.) está definido por la entidad de split config — verifíquelo en el payload real de su sandbox.

​
Crear split config

POST /splits
Crea una nueva configuración de split. Retorna 201 con el split config creado. Soporta idempotencia mediante el header Idempotency-Key. Consulte Convenciones.

​
Body

​
name
string
requerido
Nombre del split config. No puede estar vacío.
​
config
array
requerido
Array de ítems de split. Sigue las reglas descritas en El objeto split config.
​
salesKey
string
Clave de venta a vincular. Opcional; acepta null.
​
checkoutId
string
Checkout a vincular. Opcional; acepta null.
​
isActive
boolean
predeterminado:"true"
Define si el split config nace activo.
curl -X POST https://api.sandbox.z2pay.com/splits \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 9c1f0e7a-2b54-4d3a-8f10-aa11bb22cc33" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Split padrão marketplace",
    "config": [
      {
        "recipientId": "rec_a1b2c3d4e5",
        "type": "sale",
        "value": 90,
        "valueType": "percentage",
        "processingFee": true,
        "liable": true
      },
      {
        "recipientId": "rec_f6g7h8i9j0",
        "type": "platform_fee",
        "value": 10,
        "valueType": "percentage"
      }
    ]
  }'

{
  "id": "spl_4f8a2c1e9b",
  "name": "Split padrão marketplace",
  "isActive": true,
  "salesKey": null,
  "checkoutId": null,
  "config": [
    {
      "recipientId": "rec_a1b2c3d4e5",
      "type": "sale",
      "value": 90,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_f6g7h8i9j0",
      "type": "platform_fee",
      "value": 10,
      "valueType": "percentage"
    }
  ]
}
Cuando valueType es fixed, value es el monto en centavos. La regla de “suma = 100” considera únicamente los ítems con valueType: "percentage" — los ítems fixed quedan excluidos. En el ejemplo a continuación, como ningún ítem es porcentual, la regla no aplica.
{
  "name": "Split com taxa fixa de plataforma",
  "config": [
    {
      "recipientId": "rec_a1b2c3d4e5",
      "type": "sale",
      "value": 9500,
      "valueType": "fixed",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_f6g7h8i9j0",
      "type": "platform_fee",
      "value": 500,
      "valueType": "fixed"
    }
  ]
}
Los errores de validación del array config (suma ≠ 100, ninguno/múltiples processingFee, ninguno/múltiples liable) retornan 400. Consulte Errores.

​
Actualizar split config

PUT /splits/{id}
Actualiza un split config existente. Todos los campos del body son opcionales — envíe únicamente los que desea modificar. Retorna 200 con el split config actualizado.
​
id
string
requerido
ID del split config.

​
Body

​
name
string
Nuevo nombre. Si se envía, no puede estar vacío.
​
config
array
Nuevo array de ítems de split. Si se envía, sigue las mismas reglas de validación que en la creación.
​
salesKey
string
Clave de venta. Acepta null.
​
checkoutId
string
Checkout. Acepta null.
​
isActive
boolean
Activa o desactiva el split config.
curl -X PUT https://api.sandbox.z2pay.com/splits/spl_4f8a2c1e9b \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'
Estados posibles: 200 (actualizado) · 404 (no encontrado) · 400 (validación).

​
Eliminar split config

DELETE /splits/{id}
Elimina un split config mediante soft delete. Retorna 200 con la entidad que contiene el campo deletedAt completado.
​
id
string
requerido
ID del split config.
curl -X DELETE https://api.sandbox.z2pay.com/splits/spl_4f8a2c1e9b \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Estados posibles: 200 (eliminado) · 404 (no encontrado).

​
Ver también

Split (valores)

Modelo conceptual y ejemplos numéricos paso a paso de la división.

Recipients

Registre los destinatarios referenciados en recipientId.

Transacciones

Aplique un split config al crear una transacción.

Errores

Formato de errores y cómo manejar 400 / 404.