Splits - Z2Pay Developers

Um split config é uma regra reutilizável que descreve como dividir o valor de uma transação entre seus recipients. Você cria a configuração uma vez e a referencia depois (por id ou inline) ao criar transações.

Para entender o modelo conceitual de split, os tipos de item e exemplos numéricos passo a passo, veja Split. Esta página cobre apenas o CRUD da configuração.

Endpoints

Método	Rota	Descrição
`GET`	`/splits`	Lista paginada de split configs
`GET`	`/splits/{id}`	Busca um split config por ID
`POST`	`/splits`	Cria um split config
`PUT`	`/splits/{id}`	Atualiza um split config
`DELETE`	`/splits/{id}`	Remove um split config (soft delete)

Todas as requisições usam o header x-api-key. Veja Autenticação.

O objeto split config

Um split config tem um name, opcionalmente vínculos com vendas/checkout, e um array config com as regras de divisão (os “itens de split”).

Item de split (`config[]`)

recipientId

string

obrigatório

ID do recipient que recebe esta parte do valor. Não pode ser vazio.

type

string

padrão:"sale"

Tipo da parcela. Valores aceitos: sale, interest, platform_fee.

value

number

obrigatório

Valor da parcela. Deve ser maior que 0 (mínimo 0.01). A interpretação depende de valueType.

valueType

string

obrigatório

Como interpretar value. Valores aceitos: percentage (percentual de 0 a 100) ou fixed (valor fixo).

processingFee

boolean

Marca o item que arca com a taxa de processamento. Exatamente 1 item do array deve ter processingFee: true.

liable

boolean

Marca o item responsável (liable) em caso de chargeback/contestação. Exatamente 1 item do array deve ter liable: true.

Regras de validação do array config (retornam 400 se violadas):

Pelo menos 1 item de split é obrigatório.
Exatamente 1 item com processingFee: true.
Exatamente 1 item com liable: true.
Se houver pelo menos um item com valueType: "percentage", a soma dos value desses itens percentuais deve ser exatamente 100 (tolerância de 0.01). Itens fixed não entram nessa soma.

Quanto a fixed: quando valueType é fixed, value é um valor monetário em centavos (inteiro), seguindo a convenção de valores do Z2Pay.

Listar split configs

GET /splits

Retorna uma lista paginada dos split configs da sua company.

Query params

name

string

Filtra por nome.

isActive

boolean

Filtra por status de ativação (true/false).

salesKey

string

Filtra pela chave de venda vinculada.

checkoutId

string

Filtra pelo checkout vinculado.

startDate

string

Data inicial do intervalo de criação. ISO 8601 com timezone (ex.: 2026-01-01T00:00:00-03:00).

endDate

string

Data final do intervalo de criação. ISO 8601 com timezone.

page

number

Número da página (paginação).

limit

number

Itens por página (paginação).

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

Buscar split config por ID

GET /splits/{id}

Retorna um split config específico com suas regras.

string

obrigatório

ID do split config.

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

Status possíveis: 200 (encontrado) · 404 (não encontrado — veja Erros).

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

O exemplo acima é ilustrativo. O conjunto exato de campos retornados (timestamps, etc.) é definido pela entidade de split config — confirme no payload real da sua sandbox.

Criar split config

POST /splits

Cria uma nova configuração de split. Retorna 201 com o split config criado. Suporta idempotência via header Idempotency-Key. Veja Convenções.

Body

name

string

obrigatório

Nome do split config. Não pode ser vazio.

config

array

obrigatório

Array de itens de split. Segue as regras descritas em O objeto split config.

salesKey

string

Chave de venda a vincular. Opcional; aceita null.

checkoutId

string

Checkout a vincular. Opcional; aceita null.

isActive

boolean

padrão:"true"

Define se o split config já nasce ativo.

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

Exemplo com valores fixos (centavos)

Quando valueType é fixed, value é o valor em centavos. A regra de “soma = 100” considera apenas os itens com valueType: "percentage" — os itens fixed ficam de fora. No exemplo abaixo, como nenhum item é percentual, a regra não se 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"
    }
  ]
}

Erros de validação do array config (soma ≠ 100, nenhum/múltiplos processingFee, nenhum/múltiplos liable) retornam 400. Veja Erros.

Atualizar split config

PUT /splits/{id}

Atualiza um split config existente. Todos os campos do body são opcionais — envie apenas o que deseja alterar. Retorna 200 com o split config atualizado.

string

obrigatório

ID do split config.

Body

name

string

Novo nome. Se enviado, não pode ser vazio.

config

array

Novo array de itens de split. Se enviado, segue as mesmas regras de validação da criação.

salesKey

string

Chave de venda. Aceita null.

checkoutId

string

Checkout. Aceita null.

isActive

boolean

Ativa ou desativa o 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 }'

Status possíveis: 200 (atualizado) · 404 (não encontrado) · 400 (validação).

Remover split config

DELETE /splits/{id}

Remove um split config via soft delete. Retorna 200 com a entidade contendo o campo deletedAt preenchido.

string

obrigatório

ID do split config.

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

Status possíveis: 200 (removido) · 404 (não encontrado).

Veja também

Split (valores)

Modelo conceitual e exemplos numéricos passo a passo da divisão.

Recipients

Cadastre os recebedores referenciados em recipientId.

Transações

Aplique um split config ao criar uma transação.

Erros

Formato dos erros e como tratar 400 / 404.

​Endpoints

​O objeto split config

​Item de split (config[])

​Listar split configs

​Query params

​Buscar split config por ID

​Criar split config

​Body

​Atualizar split config

​Body

​Remover split config

​Veja também

Split (valores)

Recipients

Transações

Erros

Endpoints

O objeto split config

Item de split (`config[]`)

Listar split configs

Query params

Buscar split config por ID

Criar split config

Body

Atualizar split config

Body

Remover split config

Veja também