Splits - Z2Pay Developers

A split config is a reusable rule that describes how to divide a transaction amount among its recipients. You create the configuration once and reference it later (by id or inline) when creating transactions.

To understand the conceptual split model, item types, and step-by-step numeric examples, see Split. This page covers only the configuration CRUD.

Endpoints

Method	Route	Description
`GET`	`/splits`	Paginated list of split configs
`GET`	`/splits/{id}`	Retrieve a split config by ID
`POST`	`/splits`	Create a split config
`PUT`	`/splits/{id}`	Update a split config
`DELETE`	`/splits/{id}`	Remove a split config (soft delete)

All requests use the x-api-key header. See Authentication.

The split config object

A split config has a name, optional links to sales/checkout, and a config array containing the split rules (the “split items”).

Split item (`config[]`)

recipientId

string

required

ID of the recipient receiving this portion of the amount. Cannot be empty.

type

string

default:"sale"

Type of the portion. Accepted values: sale, interest, platform_fee.

value

number

required

Value of the portion. Must be greater than 0 (minimum 0.01). Interpretation depends on valueType.

valueType

string

required

How to interpret value. Accepted values: percentage (percentage from 0 to 100) or fixed (fixed amount).

processingFee

boolean

Marks the item that bears the processing fee. Exactly 1 item in the array must have processingFee: true.

liable

boolean

Marks the item responsible (liable) in the event of a chargeback/dispute. Exactly 1 item in the array must have liable: true.

Validation rules for the config array (return 400 if violated):

At least 1 split item is required.
Exactly 1 item with processingFee: true.
Exactly 1 item with liable: true.
If at least one item has valueType: "percentage", the sum of value for those percentage items must be exactly 100 (tolerance of 0.01). fixed items are excluded from this sum.

Regarding fixed: when valueType is fixed, value is a monetary amount in cents (integer), following Z2Pay’s value conventions.

List split configs

GET /splits

Returns a paginated list of split configs for your company.

Query params

name

string

Filter by name.

isActive

boolean

Filter by activation status (true/false).

salesKey

string

Filter by linked sales key.

checkoutId

string

Filter by linked checkout.

startDate

string

Start date of the creation range. ISO 8601 with timezone (e.g., 2026-01-01T00:00:00-03:00).

endDate

string

End date of the creation range. ISO 8601 with timezone.

page

number

Page number (pagination).

limit

number

Items per page (pagination).

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

Retrieve a split config by ID

GET /splits/{id}

Returns a specific split config with its rules.

string

required

ID of the split config.

curl https://api.sandbox.z2pay.com/splits/spl_4f8a2c1e9b \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Possible statuses: 200 (found) · 404 (not found — see Errors).

{
  "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"
    }
  ]
}

The example above is illustrative. The exact set of fields returned (timestamps, etc.) is defined by the split config entity — confirm against the actual payload from your sandbox.

Create a split config

POST /splits

Creates a new split configuration. Returns 201 with the created split config. Supports idempotency via the Idempotency-Key header. See Conventions.

Body

name

string

required

Name of the split config. Cannot be empty.

config

array

required

Array of split items. Follows the rules described in The split config object.

salesKey

string

Sales key to link. Optional; accepts null.

checkoutId

string

Checkout to link. Optional; accepts null.

isActive

boolean

default:"true"

Defines whether the split config is created as active.

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"
    }
  ]
}

Example with fixed amounts (cents)

When valueType is fixed, value is the amount in cents. The “sum = 100” rule applies only to items with valueType: "percentage" — fixed items are excluded. In the example below, since no item is percentage-based, the rule does not apply.

{
  "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"
    }
  ]
}

Validation errors in the config array (sum ≠ 100, missing/multiple processingFee, missing/multiple liable) return 400. See Errors.

Update a split config

PUT /splits/{id}

Updates an existing split config. All body fields are optional — send only what you want to change. Returns 200 with the updated split config.

string

required

ID of the split config.

Body

name

string

New name. If provided, cannot be empty.

config

array

New array of split items. If provided, follows the same validation rules as creation.

salesKey

string

Sales key. Accepts null.

checkoutId

string

Checkout. Accepts null.

isActive

boolean

Activates or deactivates the 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 }'

Possible statuses: 200 (updated) · 404 (not found) · 400 (validation error).

Remove a split config

DELETE /splits/{id}

Removes a split config via soft delete. Returns 200 with the entity containing the deletedAt field populated.

string

required

ID of the split config.

curl -X DELETE https://api.sandbox.z2pay.com/splits/spl_4f8a2c1e9b \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Possible statuses: 200 (removed) · 404 (not found).

Split (values)

Conceptual model and step-by-step numeric examples of the split distribution.

Recipients

Transactions

Apply a split config when creating a transaction.

Errors

Error format and how to handle 400 / 404.

​Endpoints

​The split config object

​Split item (config[])

​List split configs

​Query params

​Retrieve a split config by ID

​Create a split config

​Body

​Update a split config

​Body

​Remove a split config

​See also

Split (values)

Recipients

Transactions

Errors

Endpoints

The split config object

Split item (`config[]`)

List split configs

Query params

Retrieve a split config by ID

Create a split config

Body

Update a split config

Body

Remove a split config

See also