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

# Configurar Split de Pagamentos

> Crie uma configuração de Split de Pagamento e cadastre ou atualize instruções de repasse, por tipo de transferência.

Configurar um Split de Pagamento envolve dois passos: criar a configuração associada à conta de recebimento e cadastrar as instruções que definem quanto e para quem cada pagamento é repassado. Você também pode adicionar novas instruções ou alterar a regra de uma instrução existente a qualquer momento.

## Criar configuração com instruções

Use `POST /baas/api/v1/split-payments/configurations` para criar a configuração já com uma ou mais instruções.

```json theme={null}
{
  "bankAccountNumber": "CONTA_PAGADORA",
  "instructions": [
    {
      "amount": 10,
      "type": "PERCENTAGE",
      "transferType": "INTERNAL",
      "beneficiary": {
        "number": "CONTA_BENEFICIARIA"
      }
    }
  ]
}
```

<Note>
  `bankAccountNumber`, no nível raiz do corpo, é a conta que **recebe** os pagamentos originais. Cada item de `instructions` define uma regra de repasse e o `beneficiary` que a recebe.
</Note>

O formato exigido para `beneficiary` muda de acordo com o `transferType` escolhido. As seções abaixo detalham cada um.

## Formas de repasse (`transferType`)

<Tabs>
  <Tab title="INTERNAL">
    O beneficiário precisa ser uma conta interna, pertencente à mesma conta proprietária da API key.

    ### Mínimo

    ```json theme={null}
    {
      "bankAccountNumber": "CONTA_PAGADORA",
      "instructions": [
        {
          "amount": 10,
          "type": "PERCENTAGE",
          "transferType": "INTERNAL",
          "beneficiary": {
            "number": "CONTA_BENEFICIARIA"
          }
        }
      ]
    }
    ```

    Basta informar `beneficiary.number`. A API consulta a conta beneficiária e preenche automaticamente:

    * agência;
    * ISPB;
    * tipo da conta;
    * nome do titular;
    * documento do titular.

    ### Completo

    ```json theme={null}
    {
      "bankAccountNumber": "CONTA_PAGADORA",
      "instructions": [
        {
          "amount": 10,
          "type": "PERCENTAGE",
          "transferType": "INTERNAL",
          "beneficiary": {
            "number": "CONTA_BENEFICIARIA",
            "branch": "0001",
            "participantIspb": "12345678",
            "type": "PAYMENT",
            "holder": {
              "document": "12345678901",
              "name": "Nome do beneficiário",
              "email": "beneficiario@email.com",
              "phoneNumber": "85999999999",
              "type": "NATURAL"
            }
          }
        }
      ]
    }
    ```

    <Note>
      Mesmo enviando o payload completo, `branch`, `participantIspb`, `type` da conta, `holder.name` e `holder.document` são sobrescritos pelos dados encontrados na conta beneficiária. Para `INTERNAL`, o único dado que realmente importa é `beneficiary.number`.
    </Note>
  </Tab>

  <Tab title="PIX_MANUAL">
    Nesse tipo, os dados bancários e os dados principais do titular são validados pela API.

    ### Mínimo funcional

    ```json theme={null}
    {
      "bankAccountNumber": "CONTA_PAGADORA",
      "instructions": [
        {
          "amount": 50,
          "type": "FIXED",
          "transferType": "PIX_MANUAL",
          "beneficiary": {
            "number": "123456",
            "branch": "0001",
            "participantIspb": "12345678",
            "type": "CURRENT",
            "holder": {
              "document": "CPF_OU_CNPJ_VALIDO",
              "name": "Nome do beneficiário"
            }
          }
        }
      ]
    }
    ```

    ### Completo

    ```json theme={null}
    {
      "bankAccountNumber": "CONTA_PAGADORA",
      "instructions": [
        {
          "amount": 50,
          "type": "FIXED",
          "transferType": "PIX_MANUAL",
          "beneficiary": {
            "number": "123456",
            "branch": "0001",
            "participantIspb": "12345678",
            "type": "CURRENT",
            "holder": {
              "document": "12345678901",
              "name": "Nome do beneficiário",
              "email": "beneficiario@email.com",
              "phoneNumber": "85999999999",
              "type": "NATURAL"
            }
          }
        }
      ]
    }
    ```

    Regras de validação:

    * `beneficiary.number`: entre 2 e 25 caracteres;
    * `beneficiary.branch`: entre 1 e 10 caracteres;
    * `beneficiary.participantIspb`: exatamente 8 caracteres;
    * `beneficiary.type`: precisa ser um valor válido do enum de tipo de conta;
    * `holder.document`: CPF ou CNPJ válido;
    * `holder.name`: entre 1 e 100 caracteres;
    * `holder.email`, `holder.phoneNumber` e `holder.type`: opcionais.
  </Tab>

  <Tab title="EXTERNAL">
    <Warning>
      A API aceita o valor `EXTERNAL` para `transferType`, mas ainda não faz validação específica dos dados bancários informados. Evite usar em produção até que a validação completa esteja disponível.
    </Warning>

    Se optar por usar mesmo assim, envie sempre o payload completo, no mesmo formato de `PIX_MANUAL`:

    ```json theme={null}
    {
      "bankAccountNumber": "CONTA_PAGADORA",
      "instructions": [
        {
          "amount": 50,
          "type": "FIXED",
          "transferType": "EXTERNAL",
          "beneficiary": {
            "number": "123456",
            "branch": "0001",
            "participantIspb": "12345678",
            "type": "CURRENT",
            "holder": {
              "document": "12345678901",
              "name": "Nome do beneficiário",
              "email": "beneficiario@email.com",
              "phoneNumber": "85999999999",
              "type": "NATURAL"
            }
          }
        }
      ]
    }
    ```

    Enviar apenas `beneficiary.holder` vazio é tecnicamente aceito pela API, mas resulta em um cadastro incompleto e não deve ser usado.
  </Tab>

  <Tab title="PIX_KEY">
    <Warning>
      `PIX_KEY` ainda não está funcional nesta rota. O valor é aceito no corpo da requisição, mas a chave Pix informada não é processada e o beneficiário não é cadastrado corretamente. Não utilize esse `transferType` até que o suporte seja anunciado.
    </Warning>

    Para repassar valores via chave Pix hoje, use `PIX_MANUAL` com os dados bancários da conta correspondente à chave.
  </Tab>
</Tabs>

## Adicionar uma instrução a uma configuração existente

Use `POST /baas/api/v1/split-payments/configurations/:splitPaymentId/beneficiaries` para incluir uma nova instrução em uma configuração já criada. O corpo segue o mesmo formato de um item de `instructions`, de acordo com o `transferType` escolhido.

```json theme={null}
{
  "amount": 20,
  "type": "FIXED",
  "transferType": "PIX_MANUAL",
  "beneficiary": {
    "number": "789012",
    "branch": "0001",
    "participantIspb": "12345678",
    "type": "CURRENT",
    "holder": {
      "document": "12345678901",
      "name": "Nome do beneficiário"
    }
  }
}
```

## Atualizar a regra de uma instrução

Use `PATCH /baas/api/v1/split-payments/configurations/:splitPaymentId/beneficiaries/:splitPaymentBeneficiaryId` para alterar `amount` e/ou `type` de uma instrução já cadastrada. Os dados do beneficiário (`transferType` e `beneficiary`) não são alterados por esse endpoint.

```json theme={null}
{
  "type": "PERCENTAGE",
  "amount": 3
}
```

## Valores aceitos

| Campo                         | Valores                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------ |
| `instructions[].type`         | `PERCENTAGE`, `FIXED`                                                                                  |
| `instructions[].transferType` | `INTERNAL`, `PIX_MANUAL`, `EXTERNAL`, `PIX_KEY`                                                        |
| `beneficiary.type`            | `PAYMENT`, `CURRENT`, `SAVING`, `SALARY`, `ESCROW`, `MINIPI`, `ADMINISTERED`, `TRANSACTIONAL`, `OWNER` |
| `holder.type`                 | `NATURAL`, `LEGAL`                                                                                     |

<Warning>
  Na situação atual, os tipos seguramente utilizáveis em produção são `INTERNAL` e `PIX_MANUAL`. `EXTERNAL` ainda não tem validação dos dados bancários e `PIX_KEY` não está funcional nesta rota.
</Warning>

## Regras de negócio

<Warning>
  * Para `type: PERCENTAGE`, o percentual máximo por instrução é **5%** do valor do pagamento.
  * Para `type: FIXED`, se o `amount` exceder **50%** do valor da transação recebida, o split não é realizado para aquela instrução naquele pagamento.
</Warning>

## Referência da API

<CardGroup cols={2}>
  <Card title="Criar configuração" icon="plus" href="/api-reference/split-pagamentos/criar-split">
    `POST /baas/api/v1/split-payments/configurations`
  </Card>

  <Card title="Adicionar instrução" icon="user-plus" href="/api-reference/split-pagamentos/adicionar-beneficiario">
    `POST /baas/api/v1/split-payments/configurations/:splitPaymentId/beneficiaries`
  </Card>

  <Card title="Atualizar instrução" icon="pen" href="/api-reference/split-pagamentos/atualizar-beneficiario">
    `PATCH /baas/api/v1/split-payments/configurations/:splitPaymentId/beneficiaries/:splitPaymentBeneficiaryId`
  </Card>
</CardGroup>