Referência

Master divide com parceiros (Cobrança imediata com split): a cobrança nasce na sua conta e a regra informa a conta de cada parceiro.

Seller divide com a master (Split para Conta Master): você envia o header X-Sub-Account com o número da subconta do seller, e a cobrança nasce nela. Como a regra do split não informa accountNumber, a API resolve automaticamente para a sua conta master.

{
  "amount": 1.00,
  "externalTxid": "loja-01-caixa-03",
  "split": [
    { "type": "fixed", "accountNumber": "896532569", "amount": 0.10 },
    { "type": "fixed", "accountNumber": "125485692", "amount": 0.10 }
  ]
}

{
  "amount": 1.00,
  "externalTxid": "loja-01-caixa-03",
  "split": [
    { "type": "fixed", "amount": 0.10 }
  ]
}

Campos de uma regra de split

• •Informe accountNumber. No modelo "seller para a master", deixe de fora: a API preenche com a master do token.
• •Máximo de 20 recebedores por cobrança.
• •A soma dos splits do tipo percentage não pode passar de 100%.
• •A mesma conta não pode aparecer em duas regras do mesmo split.

Cálculo e limite do split

• •Uma regra percentage é sempre calculada sobre o valor bruto da cobrança (amount), nunca sobre o valor líquido.
• •Uma regra fixed usa exatamente o valor informado.
• •A soma de todas as regras já resolvidas não pode passar do valor líquido da cobrança (valor bruto menos a taxa Pix da conta). Se a conta tiver crédito de taxa suficiente, o limite passa a ser o próprio valor bruto.
• •Passar do limite retorna 400 SPLIT_EXCEEDS_NET_AMOUNT, com os dois valores já calculados na mensagem.

{
  "error": {
    "message": "O valor dos splits (R$12.00) excede o valor líquido da cobrança (R$9.80)",
    "code": "SPLIT_EXCEEDS_NET_AMOUNT",
    "details": null,
    "timestamp": "2026-02-18T22:19:31.013Z"
  }
}

Criar a cobrança só registra as regras do split; nenhuma transferência acontece nesse momento. O dinheiro só se move quando o Pix é efetivamente pago: nesse instante, a ValidaPay calcula o valor de cada regra sobre o valor bruto, credita cada recebedor (categoria SPLIT_IN no extrato dele) e credita o restante, já descontadas taxa e splits, na conta que gerou a cobrança (categoria PAYMENT).

Consultando uma cobrança com split

O mesmo GET /v1/charges/:chargeId de Pix traz, quando a cobrança tem split, o objeto splitscom o resultado de cada regra. Quando a cobrança nasceu numa subconta (modelo "seller para a master"), a resposta também traz accountId (a subconta dona da cobrança) e masterAccountId (a master dela):

{
  "chargeId": "cha_1774539002481_sp1itxk9a",
  "status": "PAID",
  "amount": 1.00,
  "paymentType": "PIX",
  "accountId": "896532569",
  "masterAccountId": "428965347",
  "emv": "00020101021226910014br.gov.bcb.pix2569qrcode.pix.celcoin.com.br/pixqrcode/v2/77e66fbad26b0b294eeb56c7c7c29f5204000053039865802BR5909ValidaPix6013Florianopolis62070503***6304BA13",
  "paidAt": "2026-02-18T22:22:50.031Z",
  "createdAt": "2026-02-18T22:19:31.013Z",
  "splits": {
    "id": "spl_1774539002481_a1b2c3d4e",
    "chargeId": "cha_1774539002481_sp1itxk9a",
    "splitRules": [
      {
        "type": "fixed",
        "amount": 0.10,
        "accountNumber": "428965347",
        "paidAmount": 0.10,
        "paidAt": "2026-02-18T22:22:51.203Z",
        "error": null
      }
    ],
    "createdAt": "2026-02-18T22:19:31.013Z",
    "updatedAt": "2026-02-18T22:22:51.203Z"
  }
}

A conta master pode consultar diretamente o status de uma cobrança criada em qualquer uma das suas subcontas, sem precisar enviar X-Sub-Account no GET.

NOT_FOUND e UNAUTHORIZED só acontecem no modelo "seller para a master", quando X-Sub-Account aponta para uma subconta inexistente ou que não pertence à master autenticada.

Perguntas frequentes