Configurar Split de Pagamentos

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.

{
  "bankAccountNumber": "CONTA_PAGADORA",
  "instructions": [
    {
      "amount": 10,
      "type": "PERCENTAGE",
      "transferType": "INTERNAL",
      "beneficiary": {
        "number": "CONTA_BENEFICIARIA"
      }
    }
  ]
}

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.

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

Formas de repasse (`transferType`)

INTERNAL
PIX_MANUAL
EXTERNAL
PIX_KEY

O beneficiário precisa ser uma conta interna, pertencente à mesma conta proprietária da API key.

Mínimo

{
  "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

{
  "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"
        }
      }
    }
  ]
}

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.

Nesse tipo, os dados bancários e os dados principais do titular são validados pela API.

Mínimo funcional

{
  "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

{
  "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.

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.

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

{
  "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.

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.

Para repassar valores via chave Pix hoje, use PIX_MANUAL com os dados bancários da conta correspondente à chave.

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.

{
  "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.

{
  "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`

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.

Regras de negócio

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.

Referência da API

Criar configuração

POST /baas/api/v1/split-payments/configurations

Adicionar instrução

POST /baas/api/v1/split-payments/configurations/:splitPaymentId/beneficiaries

Atualizar instrução

PATCH /baas/api/v1/split-payments/configurations/:splitPaymentId/beneficiaries/:splitPaymentBeneficiaryId

Introdução

Autenticação

Receber via Pix (Pix Cash-in)

Pagar via Pix (Pix Cash-out)

Cobranças via Boleto

Split de Pagamentos

Webhooks

Configurar Split de Pagamentos

Criar configuração com instruções

Formas de repasse (`transferType`)

Mínimo

Completo

Mínimo funcional

Completo

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

Atualizar a regra de uma instrução

Valores aceitos

Regras de negócio

Referência da API

Criar configuração

Adicionar instrução

Atualizar instrução

​Criar configuração com instruções

​Formas de repasse (transferType)

​Mínimo

​Completo

​Mínimo funcional

​Completo

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

​Atualizar a regra de uma instrução

​Valores aceitos

​Regras de negócio

​Referência da API

Criar configuração

Adicionar instrução

Atualizar instrução

Criar configuração com instruções

Formas de repasse (`transferType`)

Mínimo

Completo

Mínimo funcional

Completo

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

Atualizar a regra de uma instrução

Valores aceitos

Regras de negócio

Referência da API