> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagamentos com Split

> Divida o valor líquido de uma transação entre múltiplas subcontas (recebedores) no momento da criação do pagamento

O **split de pagamento** permite dividir automaticamente o valor de uma transação entre múltiplas subcontas (submerchants). A divisão é definida no momento da criação do pagamento, e a liquidação de cada recebedor acontece de forma automática — inclusive a reversão em caso de estorno ou chargeback.

Casos de uso típicos: lojas que dividem receita com parceiros ou afiliados, marketplaces, plataformas SaaS que repassam valores a parceiros e PSPs/PaaS que operam subcontas.

## Pré-requisitos

<Steps>
  <Step title="Produtos habilitados">
    Os produtos **PaaS** e **Split** precisam estar habilitados para o seu
    merchant. A ativação é feita pela equipe UvviPay — solicite ao seu contato
    comercial.
  </Step>

  <Step title="Subcontas criadas e aprovadas">
    As subcontas **recebedoras** devem estar criadas via
    [`POST /v1/submerchants`](/api-reference/submerchants/create) e **ativas**.
    Guarde o `id` (UUID) retornado na criação — ele é usado como `recipientId`
    nas regras de split. O owner não precisa de subconta: sem `subMerchant` no
    payload, o próprio merchant é o owner.
  </Step>
</Steps>

## Como funciona

Em um pagamento com split existem dois papéis:

| Papel           | Como é definido                                                  | Função                                                                          |
| --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Owner**       | O próprio merchant (padrão) ou o objeto `subMerchant` do payload | Dono da transação. Recebe o valor líquido e é a origem dos valores distribuídos |
| **Recebedores** | Array `split` do payload                                         | Subcontas que recebem uma parte do valor líquido                                |

<Note>
  O objeto `subMerchant` é **opcional**. Sem ele, o próprio merchant é o owner
  do split — o caso comum de quem quer apenas dividir valores com parceiros.
  Quando informado, o `subMerchant` identifica pelo documento (CPF/CNPJ) uma
  subconta já cadastrada, que passa a ser owner; se o documento for o do
  próprio merchant sem subconta cadastrada, o merchant segue como owner.
</Note>

O owner não precisa (nem pode) aparecer entre os recebedores do `split`: o restante do líquido já permanece com ele automaticamente.

### Base de cálculo: valor líquido

O split é calculado sobre o **valor líquido** da transação:

```
líquido = valor bruto - taxas (MDR + taxa fixa) - reserva financeira
```

As taxas da transação são sempre suportadas pelo owner. O que for definido no `split` sai do líquido do owner e é creditado aos recebedores; o restante permanece com o owner.

## Regras de split

Cada regra do array `split` tem três campos:

| Campo         | Tipo                   | Descrição                                                                                          |
| ------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| `recipientId` | string (UUID)          | `id` da subconta recebedora, retornado na criação da subconta                                      |
| `type`        | `percentage` \| `flat` | Forma de cálculo da regra                                                                          |
| `amount`      | number                 | Percentual (1 a 100) quando `type=percentage`, ou valor **inteiro em centavos** quando `type=flat` |

Os dois tipos podem ser combinados na mesma transação.

### Percentual (`percentage`)

O valor do recebedor é `líquido × percentual / 100`, arredondado para o centavo mais próximo.

<Note>
  Quando os percentuais somam exatamente 100 (sem regras `flat`), o último
  recebedor absorve o resíduo de arredondamento, garantindo que o líquido seja
  distribuído por completo, centavo a centavo.
</Note>

### Valor fixo (`flat`)

O recebedor recebe exatamente o valor informado, em centavos. O valor deve ser inteiro — centavos fracionados são rejeitados.

## Validações

A criação do pagamento é rejeitada com `400 Bad Request` quando qualquer regra abaixo é violada:

| Regra                                                                                                | Erro                                                                                                    |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `subMerchant` informado com documento sem subconta cadastrada (e diferente do documento do merchant) | `Subconta owner do split nao encontrada para o documento do subMerchant informado`                      |
| Produto PaaS não habilitado para o merchant                                                          | `Split requer o produto PaaS habilitado para este merchant`                                             |
| Produto Split não habilitado para o merchant                                                         | `Produto Split nao esta habilitado para este merchant`                                                  |
| Recebedor inexistente ou de outro merchant                                                           | `Recebedor de split nao encontrado`                                                                     |
| Recebedor inativo                                                                                    | `Recebedor de split inativo`                                                                            |
| Recebedor repetido no array                                                                          | `Recebedor duplicado no split`                                                                          |
| Owner incluído como recebedor                                                                        | `Recebedor de split nao pode ser o subMerchant owner da transacao`                                      |
| Percentual fora de 1–100 ou soma dos percentuais acima de 100                                        | `Percentual de split deve estar entre 1 e 100` / `A soma dos percentuais de split nao pode exceder 100` |
| Valor `flat` fracionado                                                                              | `Valor flat de split deve ser inteiro em centavos`                                                      |
| Soma das regras acima do líquido                                                                     | `A soma dos valores de split excede o valor liquido da transacao`                                       |

## Exemplo de requisição

Pagamento PIX de R\$ 100,00 com split: 30% para uma subconta e R\$ 20,00 fixos para outra. O restante do líquido permanece com o owner — neste exemplo, o próprio merchant (sem `subMerchant` no payload).

```json POST /v1/payments theme={null}
{
  "externalId": "ORDER-12345",
  "amount": 10000,
  "paymentMethod": "pix",
  "customer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": { "number": "12345678901", "type": "cpf" }
  },
  "items": [
    { "title": "Produto Exemplo", "quantity": 1, "unitPrice": 10000 }
  ],
  "split": [
    {
      "recipientId": "5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f",
      "type": "percentage",
      "amount": 30
    },
    {
      "recipientId": "8c1e5f7b-4d3e-4a8b-8c0d-1e2f3a4b5c6d",
      "type": "flat",
      "amount": 2000
    }
  ]
}
```

Para que uma **subconta** seja owner (caso PaaS/marketplace), envie também o objeto `subMerchant` com o documento dela — os demais campos do pagamento não mudam.

Supondo taxas + reserva de R\$ 5,00 (`500` centavos), a distribuição do líquido de R\$ 95,00 (`9500`) seria:

| Conta                     | Valor     |
| ------------------------- | --------- |
| Recebedor 1 (30% de 9500) | R\$ 28,50 |
| Recebedor 2 (flat)        | R\$ 20,00 |
| Owner (restante)          | R\$ 46,50 |

## Split na resposta

A resposta da criação e da consulta ([`GET /v1/payments/{id}`](/api-reference/payments/get)) inclui o campo `split` com o valor **efetivamente calculado** para cada recebedor, em centavos. Os [webhooks](/webhooks) de status da transação (`transaction.paid`, `transaction.refunded`, `transaction.chargedback` etc.) também carregam o mesmo campo `split` no `data`:

```json theme={null}
{
  "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "status": "paid",
  "amount": 10000,
  "paymentMethod": "pix",
  "split": [
    { "recipient_id": "5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f", "amount": 2850 },
    { "recipient_id": "8c1e5f7b-4d3e-4a8b-8c0d-1e2f3a4b5c6d", "amount": 2000 }
  ]
}
```

<Note>
  Transações com split criadas antes da disponibilização deste campo não
  retornam `split` na consulta.
</Note>

## Estorno e chargeback

O split é revertido automaticamente — nenhuma ação adicional é necessária:

* **Estorno** ([`PUT /v1/payments/{id}/refund`](/api-reference/payments/refund)): na mesma operação do estorno, cada recebedor é debitado no valor que recebeu e esse valor é creditado de volta ao owner.
* **Chargeback**: mesma reversão, vinculada ao chargeback correspondente.

<Note>
  A reversão usa exatamente os valores distribuídos na venda. Se o saldo de um
  recebedor for insuficiente, o débito ainda é registrado e o saldo pode ficar
  negativo até compensação futura.
</Note>

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Preciso ser marketplace ou PaaS para usar split?">
    Não — você não precisa operar como marketplace nem como plataforma. A
    ativação do split usa dois produtos internos, chamados **PaaS** e **Split**,
    habilitados pela equipe UvviPay via contato comercial; o nome do produto não
    exige que o seu negócio seja um PaaS. Depois de habilitado, basta enviar o
    array `split` no pagamento: sem o objeto `subMerchant`, o próprio merchant é
    o owner da transação, sem nenhum cadastro adicional.
  </Accordion>

  <Accordion title="Preciso me cadastrar como subconta para usar split?">
    Não. O owner padrão do split é o próprio merchant. Você só cria subcontas
    para os **recebedores** (seus parceiros). O objeto `subMerchant` no
    pagamento é opcional e serve apenas para operações em que uma subconta é a
    dona da transação (caso marketplace).
  </Accordion>

  <Accordion title="O split incide sobre o valor bruto ou líquido?">
    Sobre o **líquido**: valor bruto menos taxas (MDR + taxa fixa) e reserva
    financeira. As taxas da transação são sempre do owner — os recebedores
    recebem o valor da regra sem desconto de tarifas.
  </Accordion>

  <Accordion title="Como sei quanto foi efetivamente para cada recebedor?">
    A resposta da criação, a consulta (`GET /v1/payments/{id}`) e os webhooks de
    status trazem o campo `split` com o valor calculado por recebedor, em
    centavos: `[{ "recipient_id": "...", "amount": 2850 }]`. É o valor final,
    já com arredondamento aplicado.
  </Accordion>

  <Accordion title="E se a soma dos percentuais for menor que 100?">
    O restante do líquido permanece com o owner automaticamente. Inválido
    apenas quando os percentuais ultrapassam 100 ou quando a soma das regras
    excede o líquido.
  </Accordion>

  <Accordion title="Como funciona o arredondamento de percentuais?">
    Cada regra é arredondada para o centavo mais próximo. Quando os percentuais
    somam exatamente 100 (sem regras `flat`), o último recebedor do array
    absorve o resíduo, garantindo que o líquido seja distribuído por completo.
  </Accordion>

  <Accordion title="Posso alterar o split depois que o pagamento foi criado?">
    Não. O split é definido na criação do pagamento e é imutável. Para uma
    divisão diferente, crie um novo pagamento. Ajustes excepcionais devem ser
    tratados com o suporte.
  </Accordion>

  <Accordion title="O que acontece com o split em estorno ou chargeback?">
    A reversão é automática e integral: cada recebedor é debitado exatamente no
    valor que recebeu, e o valor volta ao owner na mesma operação. Se o saldo
    do recebedor for insuficiente, ele pode ficar negativo até compensação.
  </Accordion>

  <Accordion title="O pagamento foi recusado — o split foi aplicado?">
    Não. O split só é efetivado na liquidação de pagamentos aprovados. A
    validação das regras acontece **antes** da cobrança: se alguma regra for
    inválida, a transação nem chega a ser cobrada (erro 400).
  </Accordion>

  <Accordion title="Quando o recebedor pode usar o valor?">
    O valor segue a liquidação normal da transação: em PIX entra como saldo
    disponível; em cartão entra como saldo agendado e fica disponível conforme
    o cronograma de recebíveis.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Criar pagamento" href="/api-reference/payments/create">
    Referência completa do endpoint com os campos subMerchant e split
  </Card>

  <Card title="Criar subconta" href="/api-reference/submerchants/create">
    Cadastre os recebedores e obtenha o recipientId
  </Card>
</CardGroup>