> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar split
> Salva uma regra de divisão reutilizável, para referenciar depois ao cobrar.
`POST /splits`
Faz parte do recurso [Splits](/pt-BR/splits) — as regras de validação do array `config` estão lá, e
o modelo com exemplos numéricos em [Split](/pt-BR/valores/split).
Salva a configuração para reusar: depois de criada, basta passar o `spl_` em `payments[].splitId` ao
[criar a transação](/pt-BR/transactions/create). Criar um split não move dinheiro nenhum — ele só
descreve a divisão.
**Os recebedores precisam existir e estar vinculados à sua conta.** A validação recusa em dois
níveis: `404` se algum `recipientId` não existe; `400` se existe mas não está vinculado.
O **status** do vínculo não é conferido aqui: dá para salvar um split com um recebedor ainda
`pending` (ou até `refused`), e o erro só aparece **na cobrança** que usar o split — com mensagem
genérica de propósito, porque ela sobe até a página de checkout e o comprador final não pode ver
o status cadastral de terceiros. Antes de vender, confira os vínculos em
[`GET /recipients`](/pt-BR/recipients/list).
**`processingFee` e `liable` são obrigatórios em quem os carrega.** Exatamente um item precisa
marcar cada um: quem arca com a taxa de processamento e quem responde por chargebacks. Não é
preferência — o adquirente recusa a venda sem um responsável definido.
**A soma dos percentuais tem de fechar em 100.** Só entram nessa conta os itens
`valueType: "percentage"` — os `fixed` ficam de fora. A tolerância é de 0,01.
**`isActive: false` guarda a regra sem colocá-la em uso.** Serve para montar a divisão antes de
ela valer.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/splits \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketplace — 80/20",
"config": [
{
"recipientId": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"value": 80,
"valueType": "percentage",
"type": "sale",
"processingFee": true,
"liable": true
},
{
"recipientId": "rec_h2q8dm4xzkw05rbvtsc7jyneo",
"value": 20,
"valueType": "percentage",
"type": "platform_fee",
"processingFee": false,
"liable": false
}
]
}'
```
```json Resposta 201 theme={null}
{
"id": "spl_t8k3nzc1qvre6y0wjaxm5fdbh",
"name": "Marketplace — 80/20",
"isActive": true,
"config": [
{
"recipientId": "rec_v57bi6ruyolouw3cpaq2ofy1k",
"value": 80,
"valueType": "percentage",
"type": "sale",
"processingFee": true,
"liable": true
},
{
"recipientId": "rec_h2q8dm4xzkw05rbvtsc7jyneo",
"value": 20,
"valueType": "percentage",
"type": "platform_fee",
"processingFee": false,
"liable": false
}
],
"createdAt": "2026-08-11T12:00:00.000Z"
}
```
## OpenAPI
````yaml openapi/psp.json POST /splits
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/splits:
post:
tags:
- Splits
summary: Criar split
description: >-
Cria um split — a regra de como o valor de uma venda é dividido entre
recebedores
operationId: SplitConfigController_create
parameters:
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
description: Nome de identificação da configuração de split.
config:
type: array
items:
type: object
properties:
recipientId:
type: string
minLength: 1
description: ID do recebedor que recebe esta parte do split.
type:
type: string
enum:
- sale
- interest
- platform_fee
default: sale
description: >-
Categoria da parte do split: sale (venda), interest
(juros) ou platform_fee (taxa da plataforma).
value:
type: number
minimum: 0.01
description: >-
Valor desta parte: percentual quando
valueType=percentage; valor fixo em centavos quando
valueType=fixed.
valueType:
type: string
enum:
- percentage
- fixed
description: >-
Como interpretar value: percentage (percentual do
total) ou fixed (valor fixo em centavos).
processingFee:
type: boolean
description: >-
Se true, este recebedor arca (proporcionalmente) com
as taxas de processamento.
liable:
type: boolean
description: >-
Se true, este recebedor é responsável por chargebacks
e estornos desta parte.
required:
- recipientId
- value
- valueType
minItems: 1
description: >-
Regras de divisão: como o valor é repartido entre os
recebedores.
salesKey:
type: string
nullable: true
description: >-
Chave de vendas (salesKey) para vincular/identificar este
split.
checkoutId:
type: string
nullable: true
description: ID do checkout vinculado a este split.
isActive:
type: boolean
default: true
description: Define se a configuração de split está ativa.
required:
- name
- config
responses:
'201':
description: Split criado
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
name:
type: string
description: Nome do registro.
config:
type: array
items:
type: object
properties:
recipientId:
type: string
description: ID do recebedor.
type:
type: string
enum:
- sale
- interest
- platform_fee
description: >-
Categoria da parte do split: sale (venda), interest
(juros) ou platform_fee (taxa da plataforma).
value:
type: number
description: >-
Valor da parte do split (percentual ou em centavos,
conforme valueType).
valueType:
type: string
description: 'Tipo do valor do split: percentage ou fixed.'
processingFee:
type: boolean
description: >-
Indica se esta parte arca com as taxas de
processamento.
liable:
type: boolean
description: >-
Indica se este recebedor é responsável por
chargebacks e estornos desta parte.
description: Regras de divisão do split por recebedor.
salesKey:
type: string
nullable: true
description: Chave de vendas (salesKey) associada ao split.
checkoutId:
type: string
nullable: true
description: ID do checkout vinculado à configuração de split.
isActive:
type: boolean
description: Indica se o registro está ativo.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
example:
id: spl_rja7dpb3xfyccdg7ukuicd0am
name: Split padrão produtores
config:
- recipientId: rec_tazseadvfg6aym95njwzvc6fs
type: sale
value: 80
valueType: percentage
processingFee: true
liable: true
- recipientId: rec_guuh4ppadxc0n47i82fuseq5u
type: platform_fee
value: 20
valueType: percentage
processingFee: false
liable: false
salesKey: SALES-2025-ABC
checkoutId: chk_yi65vojl1sh936l7b93tdg8ix
isActive: true
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````