curl --request POST \
--url https://api.sandbox.z2pay.com/v1/splits \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"config": [
{
"recipientId": "<string>",
"value": 1.01,
"type": "sale",
"processingFee": true,
"liable": true
}
],
"salesKey": "<string>",
"checkoutId": "<string>",
"isActive": true
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
config: [
{
recipientId: '<string>',
value: 1.01,
type: 'sale',
processingFee: true,
liable: true
}
],
salesKey: '<string>',
checkoutId: '<string>',
isActive: true
})
};
fetch('https://api.sandbox.z2pay.com/v1/splits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/splits"
payload = {
"name": "<string>",
"config": [
{
"recipientId": "<string>",
"value": 1.01,
"type": "sale",
"processingFee": True,
"liable": True
}
],
"salesKey": "<string>",
"checkoutId": "<string>",
"isActive": True
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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"
}{
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}Criar split
Salva uma regra de divisão reutilizável, para referenciar depois ao cobrar.
curl --request POST \
--url https://api.sandbox.z2pay.com/v1/splits \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"config": [
{
"recipientId": "<string>",
"value": 1.01,
"type": "sale",
"processingFee": true,
"liable": true
}
],
"salesKey": "<string>",
"checkoutId": "<string>",
"isActive": true
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
config: [
{
recipientId: '<string>',
value: 1.01,
type: 'sale',
processingFee: true,
liable: true
}
],
salesKey: '<string>',
checkoutId: '<string>',
isActive: true
})
};
fetch('https://api.sandbox.z2pay.com/v1/splits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/splits"
payload = {
"name": "<string>",
"config": [
{
"recipientId": "<string>",
"value": 1.01,
"type": "sale",
"processingFee": True,
"liable": True
}
],
"salesKey": "<string>",
"checkoutId": "<string>",
"isActive": True
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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"
}{
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}POST /splits
Faz parte do recurso Splits — as regras de validação do array config estão lá, e
o modelo com exemplos numéricos em Split.
Salva a configuração para reusar: depois de criada, basta passar o spl_ em payments[].splitId ao
criar a transação. Criar um split não move dinheiro nenhum — ele só
descreve a divisão.
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.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.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
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
}
]
}'
{
"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"
}
Authorizations
API Key da Credential (gerada no Backoffice)
Headers
Chave única para garantir idempotência da requisição
Body
Nome de identificação da configuração de split.
1Regras de divisão: como o valor é repartido entre os recebedores.
1Show child attributes
Show child attributes
Chave de vendas (salesKey) para vincular/identificar este split.
ID do checkout vinculado a este split.
Define se a configuração de split está ativa.
Response
Split criado
Identificador único do registro.
Nome do registro.
Regras de divisão do split por recebedor.
Show child attributes
Show child attributes
Chave de vendas (salesKey) associada ao split.
ID do checkout vinculado à configuração de split.
Indica se o registro está ativo.
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).