Split de pagamento

Divida o DePix de uma cobrança entre duas ou mais carteiras suas, automaticamente, sem mover nada à mão.

seu cliente ──Pix──► Pix2DePix ──DePix──► carteira de split ──┬──► carteira A (60%)
                                     (retenção 24h)           └──► carteira B (40%)

Serve para quem vende no próprio site e precisa separar o dinheiro na origem: sócios, fornecedor e loja, operação e reserva. A divisão sai numa única transação Liquid, com uma saída por carteira — ela confirma inteira ou não confirma. Não existe split pela metade.

Como funciona

1. Você cria a cobrança em POST /v1/split-charges, com os destinos e o percentual de cada um.
2. Seu cliente paga o Pix. O DePix líquido vai para um endereço só desta cobrança, na nossa carteira de split.
3. Depois da retenção antifraude de 24h, a cobrança vai para settled.
4. Em seguida montamos a transação que divide o valor e a transmitimos. Quando ela confirma na Liquid, você recebe charge.split.completed com o txId e o valor que caiu em cada carteira.

Consulta, listagem e cancelamento são as rotas de sempre, em /v1/charges — a cobrança com split é uma cobrança como as outras, com um bloco split a mais.

Taxa

A taxa do split é a do seu plano + 1 ponto percentual, cobrada na mesma linha da conversão Pix → DePix. A parcela fixa por depósito não muda. A taxa de rede da transação de divisão é por nossa conta — não sai do seu DePix.

Com plano de 1,99% e uma venda de R$ 1.000,00:

A resposta traz tudo aberto: amount.feeBps já com o +1 ponto (299) e split.planFeeBps com a taxa do plano sozinha (199). A taxa fica congelada na criação: trocar de plano depois não muda uma cobrança que já existe.

Cobrança sem split, em POST /v1/charges, continua pagando só a taxa do plano.

Regras dos destinos

• De 2 a 10 destinos, cada um com um endereço Liquid diferente.
• Percentuais com até duas casas decimais, somando exatamente 100. 33.33 + 66.67 passa; 33.333 + 66.667 não passa.
• Os endereços são validados na criação (formato e checksum). Endereço errado é 400 invalid_request na hora, e não um split perdido 24h depois.
• A configuração é imutável. Para mudar destinos, cancele a cobrança (se ainda não foi paga) e crie outra.

O centavo que sobra da divisão vai para quem teve a maior fração cortada: a soma do que cai nas carteiras é sempre exatamente o líquido.

1. Crie a cobrança

curl https://apiv2.pix2depix.com/v1/split-charges \
  -H "Authorization: Bearer $P2D_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amountInCents": 100000,
    "payerTaxNumber": "529.982.247-25",
    "payerName": "Maria Silva",
    "externalId": "pedido-8891",
    "split": {
      "destinations": [
        { "address": "lq1qq…carteira-a", "percent": 60 },
        { "address": "lq1qq…carteira-b", "percent": 40 }
      ]
    }
  }'

A resposta é a cobrança de sempre — mostre pix.qrCode ao seu cliente —, com o split pendente:

{
  "id": "6a92586d486e6a4f3d305214",
  "status": "awaiting_payment",
  "amount": {
    "grossInCents": 100000,
    "feeBps": 299,
    "feeFixedInCents": 99,
    "feeInCents": 3089,
    "netInCents": 96911
  },
  "split": {
    "status": "pending",
    "planFeeBps": 199,
    "destinations": [
      { "address": "lq1qq…carteira-a", "percent": 60 },
      { "address": "lq1qq…carteira-b", "percent": 40 }
    ]
  }
}

Idempotência funciona como em POST /v1/charges: o mesmo externalId com o mesmo corpo devolve a cobrança original (200). O split faz parte do corpo — mesmo externalId com destinos diferentes é 409 external_id_conflict.

2. Acompanhe pelos eventos

Além dos eventos normais da cobrança, o split tem dois próprios:

O corpo de charge.split.completed:

{
  "id": "6a93c1f0b245fe8443a36011",
  "type": "charge.split.completed",
  "createdAt": "2026-09-20T14:03:11.000Z",
  "environment": "live",
  "data": {
    "charge": {
      "id": "6a92586d486e6a4f3d305214",
      "externalId": "pedido-8891",
      "status": "settled",
      "split": {
        "status": "completed",
        "planFeeBps": 199,
        "destinations": [
          { "address": "lq1qq…carteira-a", "percent": 60, "amountInCents": 58147 },
          { "address": "lq1qq…carteira-b", "percent": 40, "amountInCents": 38764 }
        ],
        "txId": "3f1c…e9a0",
        "completedAt": "2026-09-20T14:03:10.000Z"
      }
    }
  }
}

Valide a assinatura e deduplique pelo id do evento, como em qualquer outro — está tudo em Webhooks.

Status do split

split.status anda sozinho, independente do status da cobrança:

Não use split.status para decidir se libera o produto — quem decide é o status da cobrança, settled. O split é o repasse de um dinheiro que já é seu.

Teste no sandbox

Com uma chave p2d_test_, a cobrança com split percorre o ciclo inteiro sem dinheiro. Ao empurrar para settled, o split conclui na hora, com txId de zeros, e o charge.split.completed chega ao seu webhook de teste:

curl https://apiv2.pix2depix.com/v1/test/charges/$ID/advance \
  -H "Authorization: Bearer $P2D_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "settled" }'

O exemplo completo, executável, está em exemplos/split.mjs.

Erros específicos

Os demais são os mesmos da cobrança comum — veja Erros.