Split

Split divide o líquido de uma cobrança PIX entre a sua conta e até 10 outras contas da Lezty Pay. Cada recebedor recebe a parte dele na conta dele, no momento em que a cobrança é paga.

Nesta página, pagador é a conta que cria a cobrança e manda o split. Recebedor é a conta que recebe uma parte. Os dois são contas da Lezty Pay: não existe recebedor de fora.

Antes de começar: split vem desligado

Toda conta começa com a cota de split zerada. Enquanto ela estiver zerada, toda cobrança com splits[] que passa pelo split do processador é recusada com 400 split_quota_exceeded, também no ambiente de teste. Nos processadores sem split nativo (veja PIX sem split nativo), a cota não existe e essa recusa não acontece.

Para usar split, abra um chamado com o suporte da Lezty Pay pedindo a liberação para a conta que vai mandar o split. O recebedor não precisa de liberação. A cota liberada aparece na tela Splits do painel.

Passo 1: o pagador cadastra quem pode receber

Nenhuma conta recebe split de você sem estar na sua lista. Quem autoriza é o pagador, no painel dele. O recebedor não precisa fazer nada:

1. Abra Splits, aba Autorizações (no celular a aba se chama Acesso).
2. Em "Quem pode receber parte das suas vendas", digite o e-mail da conta Lezty Pay do recebedor.
3. Clique em "Autorizar e-mail".

É só pelo painel. Não existe rota com chave de API para montar a lista: é uma decisão da conta, não da integração. O exemplo abaixo mostra o contrato da chamada que o painel faz, e só:

Copiar#!/usr/bin/env bash
# VIA PAINEL. Este exemplo não chama a API, e é de propósito.
#
# Montar a lista de quem pode receber split das suas vendas é decisão da conta, não da integração:
# não existe rota com chave de API (sk_live_ ou sk_test_) para isso. Quem PAGA (quem cria a
# cobrança com splits[]) faz no painel:
#   1. https://app.leztypay.com/app/splits/authorizations (tela Splits, aba Autorizações)
#   2. Digita o e-mail da conta Lezty Pay de quem vai receber e clica em "Autorizar e-mail".
#
# Por baixo, o painel faz esta chamada com a sessão de quem está logado. Ela está aqui só para
# você conhecer o contrato: um único campo, e a resposta é a mesma exista ou não conta com esse
# e-mail.
#
#   POST /v1/me/split-authorizations
#   { "recipient_email": "[email protected]" }
#
# Resposta: 201 com { "id", "recipient_email", "created_at" }.
set -euo pipefail

echo "Cadastre o recebedor em https://app.leztypay.com/app/splits/authorizations"

O que vale saber sobre a lista:

• O painel responde igual exista ou não uma conta com aquele e-mail. Ninguém descobre quem tem conta na Lezty Pay cadastrando e-mails.
• Ela vale para produção e para o ambiente de teste ao mesmo tempo, e vale tanto para cobranças criadas no painel quanto para as criadas com a sua chave de API.
• Remover um e-mail é na mesma tela. Cobrança já criada continua valendo; só as novas são recusadas.
• Se o recebedor trocar o e-mail da conta, a entrada deixa de valer. Cadastre o e-mail novo.

A mesma lista aparece como opções de recebedor na Nova cobrança do painel.

Passo 2: o pagador cria a cobrança com splits[]

O split vai na criação da cobrança, no mesmo Cria uma cobrança (PIX, voucher, cripto, cartão ou carteira) de sempre. Cada item de splits[] tem três campos, todos obrigatórios:

• recipient_email: o e-mail da conta Lezty Pay do recebedor.
• kind: percent ou fixed.
• value: inteiro. Em percent, é bps sobre o líquido (1500 = 15 %, de 1 a 10000). Em fixed, é centavos (2000 = R$ 20,00).

Copiar#!/usr/bin/env bash
# Cria uma cobrança PIX de R$ 200,00 que divide o líquido com duas contas Lezty Pay.
# Precisa de LM_API_URL e LM_API_KEY no ambiente. Cada `recipient_email` tem que ter
# autorizado o e-mail da SUA conta antes, no painel dele; senão a cobrança é recusada.
#   export LM_API_URL=https://api.leztypay.com
#   export LM_API_KEY=sk_test_...
set -euo pipefail

curl --fail-with-body -sS "$LM_API_URL/v1/transactions" \
  -H "Authorization: Bearer $LM_API_KEY" \
  -H "Idempotency-Key: pedido-A124-tentativa-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20000,
    "payment_method": "pix",
    "customer": {
      "name": "Maria Silva",
      "email": "[email protected]",
      "document": "123.456.789-09"
    },
    "metadata": { "order_id": "A124" },
    "splits": [
      { "recipient_email": "[email protected]", "kind": "percent", "value": 1500 },
      { "recipient_email": "[email protected]", "kind": "fixed", "value": 2000 }
    ]
  }'

O mesmo em Node, com tratamento de erro:

Copiar// Cria uma cobrança PIX com split, com o fetch global do Node 22. Sem dependência.
//   LM_API_URL=https://api.leztypay.com LM_API_KEY=sk_test_... node split-create.mjs
const apiUrl = process.env.LM_API_URL;
const apiKey = process.env.LM_API_KEY;

const res = await fetch(`${apiUrl}/v1/transactions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Idempotency-Key': 'pedido-A124-tentativa-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 20000,
    payment_method: 'pix',
    customer: {
      name: 'Maria Silva',
      email: '[email protected]',
      document: '123.456.789-09',
    },
    metadata: { order_id: 'A124' },
    splits: [
      // `percent` é em bps sobre o LÍQUIDO da cobrança: 1500 = 15 %.
      { recipient_email: '[email protected]', kind: 'percent', value: 1500 },
      // `fixed` é em centavos: 2000 = R$ 20,00.
      { recipient_email: '[email protected]', kind: 'fixed', value: 2000 },
    ],
  }),
});

const body = await res.json();

if (!res.ok) {
  // Erro de split vem no mesmo envelope. `param` aponta o item (`splits[0].recipient_email`)
  // e `details` traz os números do limite que estourou.
  const { code, message, param, details, request_id } = body.error;
  console.error(res.status, code, message, param ?? '', details ?? {}, request_id);
  process.exit(1);
}

// Antes do pagamento os valores são projeção: `projected` é true e `amount` de cada split é null.
console.log('id:', body.id, 'status:', body.status);
console.log(
  'líquido:',
  body.net,
  'vai para splits:',
  body.split_total,
  'fica com você:',
  body.net_after_splits,
);
for (const split of body.splits) {
  console.log(split.id, split.recipient.email, split.kind, split.value, split.status);
}
console.log('copia e cola:', body.pix.payload);

A resposta é a cobrança de sempre, com mais quatro campos: splits, split_total, net_after_splits e projected. Encurtada para caber na página:

{
  "id": "txn_01j9x5k8p2q3r4s5t6u7v8w9xy",
  "object": "transaction",
  "mode": "test",
  "status": "pending",
  "amount": 20000,
  "fee": 899,
  "net": 19101,
  "pix": {
    "payload": "00020126580014br.gov.bcb.pix...",
    "expires_at": "2026-09-24T12:28:00.000Z"
  },
  "metadata": { "order_id": "A124" },
  "splits": [
    {
      "id": "spl_01j9x5k8p2q3r4s5t6u7v8w9xy",
      "recipient": { "email": "[email protected]", "display_name": "Loja B" },
      "kind": "percent",
      "value": 1500,
      "status": "pending",
      "amount": null,
      "reserve": null,
      "settled_at": null,
      "reversed_at": null
    },
    {
      "id": "spl_01j9x5k8p2q3r4s5t6u7v8w9xz",
      "recipient": { "email": "[email protected]", "display_name": "Loja C" },
      "kind": "fixed",
      "value": 2000,
      "status": "pending",
      "amount": null,
      "reserve": null,
      "settled_at": null,
      "reversed_at": null
    }
  ],
  "split_total": 4865,
  "net_after_splits": 14236,
  "projected": true
}

• split_total é quanto sai do seu líquido para os recebedores.
• net_after_splits é o que fica com você: net menos split_total.
• projected é true antes do pagamento. Os dois números acima são uma projeção, e o amount de cada split ainda é null. Depois do pagamento eles passam a ser o valor que caiu de fato na conta de cada recebedor.

Os mesmos campos voltam na consulta por id, Consulta uma cobrança.

O split não muda depois de criado. Para corrigir, crie outra cobrança; a antiga expira sozinha se ninguém pagar.

Percentual é sobre o líquido

percent incide sobre o líquido da cobrança (net, o valor menos a taxa), nunca sobre amount. 15 % de R$ 200,00 não é R$ 30,00.

A cobrança do exemplo, com uma taxa de R$ 8,99 nesta conta:

15 % de R$ 191,01 são R$ 28,6515, e o centavo é arredondado: R$ 28,65. O centavo que sobra de qualquer arredondamento fica com o pagador.

A taxa é a da sua conta, congelada na criação da cobrança (Criar uma cobrança). Numa conta com outra taxa, o mesmo percent dá outro valor.

fixed é em centavos

fixed é um valor fixo em centavos, como amount: 2000 são R$ 20,00, e não R$ 2.000,00. Ele não depende da taxa: o recebedor recebe exatamente esse valor, desde que caiba no líquido e nos limites abaixo.

Limites

Até 10 recebedores

splits[] aceita no máximo 10 itens, e cada recebedor aparece uma vez só. Você não pode mandar split para a sua própria conta.

Teto por cobrança: 30 % do líquido

A soma de todos os splits de uma cobrança não passa de 30 % do líquido. Um fixed entra nessa conta pelo percentual equivalente do líquido, arredondado para cima.

No exemplo: 15 % da Loja B mais R$ 20,00 da Loja C, que são 10,48 % de R$ 191,01. Total de 25,48 %, dentro do teto. Acima dele, a cobrança é recusada com 400 split_percent_exceeded, e details traz o teto e o que foi pedido.

Cota de 30 dias por conta

Cada conta pagadora tem uma cota: o total que ela pode mandar em split nos últimos 30 dias corridos. Ela começa zerada (ver "Antes de começar", no topo), e o valor liberado é combinado com o suporte, que também ajusta a cota quando você precisar de mais.

• Conta tudo o que você mandou em split nos últimos 30 dias, inclusive split estornado por contestação.
• Cobrança ainda não paga reserva cota pelo valor projetado. Se ela expirar ou falhar, a reserva volta.
• Produção e ambiente de teste têm consumo separado.

Se a cobrança nova passar da cota, ela é recusada com 400 split_quota_exceeded. Em details vêm quota_cents (a sua cota), used_cents (quanto já foi usado), requested_cents (quanto esta cobrança pediria) e window_days. A tela Splits do painel mostra a cota e o quanto já foi usado.

Nada é criado quando um limite estoura. Não existe "cria sem o split": quem pediu split recebe split ou recebe erro.

Erros de split

Todos respondem no envelope de Erros. Programe contra code. Nos erros de um item, param aponta qual (splits[1].recipient_email, por exemplo).

Na criação da cobrança:

Do primeiro ao split_quota_exceeded, nada foi criado: corrija e repita com a mesma Idempotency-Key. Depois de split_rejected_by_partner a cobrança existe como failed, e a mesma chave devolve o mesmo 400; qualquer nova tentativa precisa de chave nova.

Na lista de recebedores, pelo painel:

O que acontece no pagamento

Quando a cobrança é paga, o processador credita cada recebedor na hora, e os eventos saem assim:

• Pagador: recebe transaction.paid como sempre, com o net cheio (19101 no exemplo). A sua parte depois do split está em net_after_splits na consulta da cobrança. Recebe também um transaction.split.settled por split.
• Recebedor: recebe um transaction.split.settled com a parte dele.

Os dois tipos são públicos e entram em ["*"] (Catálogo de eventos). Pagador e recebedor recebem o mesmo tipo de evento, cada um vendo só a sua parte: o recebedor nunca vê os dados do cliente, os itens, o metadata nem o e-mail do pagador.

O transaction.split.settled que chega ao recebedor, com data.object no formato Split:

{
  "id": "evt_01j9x5k8p2q3r4s5t6u7v8w9xy",
  "object": "event",
  "type": "transaction.split.settled",
  "mode": "test",
  "created_at": "2026-09-24T12:00:05.000Z",
  "data": {
    "object": {
      "id": "spl_01j9x5k8p2q3r4s5t6u7v8w9xy",
      "object": "split",
      "mode": "test",
      "status": "settled",
      "amount": 2865,
      "reserve": 287,
      "reserve_released_at": null,
      "kind": "percent",
      "value": 1500,
      "source_seller": { "display_name": "Loja A" },
      "transaction": {
        "id": "txn_01j9x5k8p2q3r4s5t6u7v8w9xy",
        "amount": 20000,
        "paid_at": "2026-09-24T12:00:05.000Z"
      },
      "settled_at": "2026-09-24T12:00:05.000Z",
      "reversed_at": null,
      "created_at": "2026-09-24T11:58:00.000Z"
    }
  }
}

O mesmo evento, como chega ao pagador: o item de splits[] com o destinatário, e a cobrança inteira em data.object.transaction (encurtada aqui). Formato completo em TransactionSplitEventForPayer.

{
  "id": "evt_01j9x5k8p2q3r4s5t6u7v8w9xz",
  "object": "event",
  "type": "transaction.split.settled",
  "mode": "test",
  "created_at": "2026-09-24T12:00:05.000Z",
  "data": {
    "object": {
      "id": "spl_01j9x5k8p2q3r4s5t6u7v8w9xy",
      "object": "split",
      "mode": "test",
      "recipient": { "email": "[email protected]", "display_name": "Loja B" },
      "kind": "percent",
      "value": 1500,
      "status": "settled",
      "amount": 2865,
      "reserve": 287,
      "settled_at": "2026-09-24T12:00:05.000Z",
      "reversed_at": null,
      "transaction": {
        "id": "txn_01j9x5k8p2q3r4s5t6u7v8w9xy",
        "object": "transaction",
        "status": "paid",
        "amount": 20000,
        "fee": 899,
        "net": 19101,
        "metadata": { "order_id": "A124" },
        "split_total": 4865,
        "net_after_splits": 14236,
        "paid_at": "2026-09-24T12:00:05.000Z"
      }
    }
  }
}

amount é o valor que o processador creditou. Ele pode diferir da projeção em um centavo, por arredondamento; o que vale é o do evento.

reserve vem 0 no PIX: não há reserva, a parte do recebedor fica disponível (Saques).

Split em voucher (LATAM)

Cobrança voucher (LATAM) também aceita splits[]. Aqui o split é só do nosso lado: o processador não sabe dele, a divisão acontece no saldo internacional de cada conta.

• Só kind: percent. O valor em reais de um voucher só existe quando o comprador paga; por isso fixed responde 400 split_rejected_for_voucher (details.reason é fixed_unsupported).
• base diz sobre o que o percentual incide: gross é o valor da cobrança em reais (amount), net (padrão) é o líquido depois da taxa. base em cobrança que não é voucher responde 400 split_base_unsupported_for_payment_method.
• Sem teto de 30 % e sem cota. Esses limites são do processador do PIX e não valem em voucher.
• A parte do recebedor é limitada ao líquido. Ela é calculada no pagamento, com o valor definitivo em reais. Se a soma das partes passar do líquido, a última parte é cortada, quem sobra sem nada fica cancelled e a venda segue (o pagador fica com 0 nessa venda).
• amount vem null até pagar, e split_total e net_after_splits são projeção (projected: true).
• Reserva e liberação. A parte do recebedor entra no saldo internacional dele junto com a liquidação da venda e passa pela mesma reserva de 10 % por 90 dias.
• As recusas de validação (recebedor fora da sua lista, fixed, base inválida) acontecem antes da cobrança ser criada: nada fica aberto.

MED: o split é estornado inteiro

Quando a cobrança sofre uma contestação (MED) e ela é perdida, o dinheiro volta ao cliente. Com split:

• O pagador devolve a parte que ficou com ele e recebe transaction.chargeback, como sem split. A tarifa da contestação, quando houver, fica com o pagador.
• Cada recebedor devolve tudo o que recebeu daquele split, inclusive a parte que já tenha sido sacada. Não existe devolução parcial.
• Os dois lados recebem transaction.split.reversed, no mesmo formato do settled, com status reversed e reversed_at preenchido.

Se o recebedor já sacou o dinheiro, o saldo disponível dele fica negativo. Enquanto estiver negativo, os saques dele ficam travados, e ele recebe seller.payout_locked. A trava sai sozinha quando o saldo volta a zero ou mais, por exemplo com novos recebimentos, e aí chega seller.payout_unlocked. Se a conta tiver outra trava de saque, ela continua valendo.

Para quem recebe split: dinheiro de split pode voltar enquanto a venda de origem puder ser contestada. Leve isso em conta antes de sacar tudo.

Como o recebedor vê o que recebeu

O recebedor não vê a cobrança do pagador em Lista cobranças do seller. Ele vê o split, numa visão reduzida: quem mandou (source_seller), a cobrança de origem (transaction.id, transaction.amount, transaction.paid_at), o valor, a reserva e o status. Sem dados do cliente.

Três caminhos:

• Painel: a tela Splits, aba Recebidos. A aba Enviados mostra o que você mandou.
• API: Lista splits recebidos ou enviados com role=received (o padrão) ou role=paid, filtros por status, transaction_id, created_from e created_to, e paginação por cursor (Paginação). Um split por id em Consulta um split (pagador ou recebedor).
• Webhook: transaction.split.settled e transaction.split.reversed, acima.

Copiar#!/usr/bin/env bash
# Splits que a SUA conta recebeu e que já foram liquidados, 50 por página.
# A resposta traz `next_cursor`: repita a chamada com `cursor=<next_cursor>` até vir nulo.
# `role=paid` lista os que você mandou para outras contas.
set -euo pipefail

curl --fail-with-body -sS -G "$LM_API_URL/v1/splits" \
  -H "Authorization: Bearer $LM_API_KEY" \
  --data-urlencode "role=received" \
  --data-urlencode "status=settled" \
  --data-urlencode "created_from=2026-09-01T00:00:00Z" \
  --data-urlencode "limit=50"

Somando tudo o que chegou no período, página por página:

Copiar// Soma tudo o que a sua conta recebeu em split no período, página por página, pelo cursor.
//   LM_API_URL=... LM_API_KEY=... node split-list-received.mjs
const apiUrl = process.env.LM_API_URL;
const apiKey = process.env.LM_API_KEY;

let cursor = null;
let recebido = 0;

do {
  const query = new URLSearchParams({
    role: 'received',
    status: 'settled',
    created_from: '2026-09-01T00:00:00Z',
    limit: '100',
  });
  if (cursor !== null) query.set('cursor', cursor);

  const res = await fetch(`${apiUrl}/v1/splits?${query}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const pagina = await res.json();

  if (!res.ok) {
    console.error(res.status, pagina.error.code, pagina.error.request_id);
    process.exit(1);
  }

  for (const split of pagina.data) {
    // Sem dados do cliente: só quem mandou (`source_seller`) e a cobrança de origem.
    console.log(split.id, split.source_seller.display_name, split.transaction.id, split.amount);
    recebido += split.amount;
  }

  cursor = pagina.next_cursor;
} while (cursor !== null);

console.log('recebido em split, em centavos:', recebido);

O transaction.id é o mesmo nas duas pontas. É ele que concilia o split do recebedor com a cobrança do pagador.

No ambiente de teste

Split funciona no ambiente de teste com as mesmas regras de produção: lista de recebedores, cota, teto e erros. A cobrança do exemplo termina em 00 e paga sozinha em poucos segundos, e aí chegam os eventos de split.

Os gatilhos de sempre continuam valendo. 06 (contestação) em uma cobrança com split testa o transaction.split.reversed. E estes finais de amount só valem com splits[] e só depois que a cobrança passou pelas validações acima:

Em 21, 22, 23 e 25 a cobrança fica failed. Teste que a sua integração mostra o erro e que a nova tentativa usa uma Idempotency-Key nova.

Referência

• Cria uma cobrança (PIX, voucher, cripto, cartão ou carteira): o campo splits do corpo, item a item em SplitRequestItem.
• Consulta uma cobrança: splits, split_total, net_after_splits e projected.
• Lista splits recebidos ou enviados e Consulta um split (pagador ou recebedor): o objeto Split.
• Autoriza um e-mail a receber split das vendas do seller da sessão: só pelo painel, com a sessão de quem está logado.
• Eventos: transaction.split.settled e transaction.split.reversed, em TransactionSplitEventForRecipient para o recebedor e TransactionSplitEventForPayer para o pagador.

Coprodutor e afiliado do LeztyBot

Cobranças criadas pelo LeztyBot com a conta conectada pelo OAuth não precisam da lista de recebedores: conectar o app já é a autorização. Ele ainda precisa ter conta ativa e, em produção, cadastro aprovado. Para qualquer outra chave a lista continua obrigatória, salvo a conta da plataforma, que recebe de qualquer pagador. Um e-mail sem conta LeztyPay responde split_recipient_not_authorized, o mesmo erro de um e-mail fora da lista, para ninguém descobrir quem tem conta.

Para conferir um recebedor antes de cobrar, use Confere se um e-mail pode receber split nesta chave (POST /v1/splits/recipients/check, corpo { "email": "..." }, permissão charges, 30 requisições por minuto por chave). A resposta é { eligible, code, reason }, com os mesmos códigos da criação da cobrança: split_recipient_not_authorized, ou split_recipient_not_eligible com reason status ou kyc.

Limite de itens

Uma cobrança aceita até 10 itens em splits[], contando a conta da casa: a casa mais 9 recebedores. Passou disso, too_many_splits.

PIX sem split nativo

Alguns processadores de PIX não dividem o pagamento por conta própria. Quando a sua cobrança sai por um deles, o split vale do mesmo jeito, mas é feito só do nosso lado: o dinheiro entra inteiro e a divisão acontece no saldo de cada conta, no momento em que a cobrança é paga. Você não precisa mudar nada na chamada: splits[] é o mesmo.

O que muda nesse caso:

• Sem teto de 30 % e sem cota. Esses limites são do split do processador. split_percent_exceeded e split_quota_exceeded não são respondidos.
• Recebedor. Basta a conta estar ativa (e, em produção, com cadastro aprovado) e estar na lista do pagador. split_recipient_not_eligible com details.reason de acquirer ou subaccount não acontece.
• Continuam valendo split_amount_too_small e split_exceeds_net, e todas as regras de lista de recebedores, duplicidade e formato. base segue só para voucher.
• No pagamento, o amount de cada split é sempre o valor projetado da criação. percent e fixed funcionam, e fixed é exatamente o valor pedido.
• Contestação (MED). A parte do recebedor volta ao pagador, como no split de sempre.