Split de pagamentos

O split permite distribuir o valor de uma venda entre o estabelecimento e um ou mais vendedores vinculados à operação.

O cliente realiza um único pagamento, enquanto a distribuição dos valores é processada automaticamente conforme as regras informadas no objeto split.

O split pode ser utilizado em vendas realizadas por Cartão, Pix ou Boleto.

Como gerar uma Venda com Split

Para realizar uma venda com repasse de valores aos vendedores, inclua o objeto split na requisição de criação da venda (charge).

Cada item do array representa a participação de um recebedor e deve conter seu identificador no campo seller_uuid, além do tipo de regra utilizado para calcular o valor que será recebido.

Portanto, é necessário:

Determinar o tipo de divisão
Respeitar as regras de cálculo
Informar o UUid de um seller aprovado e ativo.

Tipos de divisão

A fórmula do cálculo de recebimento de cada participante é definida pelo campo type.

Através desse campo, é possível definir se: o cálculo será baseado em percentual, valor fixo ou automático com base no restante não calculado.

Tipo	Descrição
`AMOUNT`	Define um valor fixo, informado em centavos.
`PERCENTAGE`	Define um percentual sobre o valor total da venda.
`REMAINING`	Destina ao vendedor o saldo disponível após a aplicação das demais regras.

📘
Valores de acordo o Tipo de divisão
Em regras do tipo PERCENTAGE, o campo amount utiliza quatro casas de precisão. Por exemplo, 5000 representa 50% e 1250 representa 12,5%.
Em regras do tipo AMOUNT, o campo amount é informado em centavos. Por exemplo, 2500 representa R$ 25,00.

Saldo não distribuído

Quando a soma das regras informadas não distribuir todo o valor da venda, o saldo restante será destinado automaticamente ao estabelecimento primary.

Por exemplo, em uma venda de R$ 100,00 com dois vendedores recebendo 40% e 30%, os 30% não distribuídos permanecerão com o primary.

Utilização do tipo `REMAINING`

O tipo REMAINING permite destinar a um vendedor secondary todo o saldo disponível após a aplicação das demais regras do split.

Nesse cenário, o estabelecimento primary precisa ser informado explicitamente no array split, com sua participação definida por AMOUNT ou PERCENTAGE.

Somente após reservar a participação do primary e calcular as demais regras, o saldo disponível será destinado ao vendedor configurado com REMAINING.

Gerar Venda com split

A parametrização do split deve ser feito diretamente na venda split

📘
Meios de Pagamento
O objeto está disponível para utilizar nos meios de pagamentos Cartão, Pix e Boleto

Campo	Nome	Descrição	Exemplo
seller_uuid	Identificação do Vendedor	UUid do seller (vendedor)	-
type	Tipo de divisão/split	tipo da divisão do pagamento. "AMOUNT", "PERCENTAGE" ou "REMAINING"	o tipo "REMAINING" sinaliza que o vendedor irá receber o restante do valor não alocado.
amount	Valor	valor ou percentual a ser recebido. Ex.: 100% = 10000 ou 35,55% = 3555	R$ 50,00 = 5000, R$ 12.000 = 1200000

O split de uma venda, pode ser adicionado em duas situações:

Na cobrança da venda.
Após a cobrança, sendo o limite até o mesmo dia (até 23:59).

Consultar Status de Split em uma Venda

É possível consultar os valores e status das situações do split através do método de consulta, verifique nossa seção Consultar Split de uma Venda

Os campos settlement_status_code e settlement_status_description sinalizam a situação de acordo a tabela abaixo:

settlement_status_code	settlement_status_description	Descrição
1001	PENDING	Pendente de pagamento ou aprovação.
1002	READY_TO_SETTLE	Pagamento aprovado, pronto para liquidação.
1003	SETTLEMENT_SENT	Liquidação foi enviada e aguarda a conclusão do processamento.
1004	SETTLED	Liquidado.

Casos de uso e exemplos

Abaixo alguns casos de uso, com explicação e exemplo de requisição.

Recebedores utilizados nos exemplos Os UUIDs abaixo identificam o estabelecimento e os vendedores utilizados nas requisições. Ocultar Exibir

Estabelecimento Primary

8772147d-0c7a-4e3e-8273-3524d7b37adf

Vendedor 1 Secondary

0ec683ae-14da-455a-be39-98737a344762

Vendedor 2 Secondary

a25f03f6-f551-4b22-9350-2cd959f4b0df

Vendedor 3 Secondary

7a7c8666-c869-4f63-929e-aaa4cec85407

Importante: os UUIDs são ilustrativos e devem ser substituídos pelos identificadores dos recebedores cadastrados na conta.

↘ Selecione um exemplo Clique em um dos cartões abaixo para atualizar a requisição e a explicação exibidas na sequência.

Exemplos com PERCENTAGE e AMOUNT Variações por meio de pagamento, quantidade de vendedores e tipos de divisão.

Cartão · 2 vendedores PERCENTAGE + PERCENTAGE Cartão · 3 vendedores PERCENTAGE + AMOUNT + PERCENTAGE Pix · 2 vendedores PERCENTAGE + PERCENTAGE Boleto · 2 vendedores PERCENTAGE + PERCENTAGE

Exemplos com REMAINING Cenários em que o primary é informado explicitamente e um secondary recebe o saldo restante.

Cartão · 2 vendedores Primary PERCENTAGE + REMAINING Pix · 2 vendedores Primary AMOUNT + REMAINING

{ } Cartão com split — 2 vendedores

JSON

POST https://gateway-sandbox.cyclopay.com/v1/charges

{
  "amount": 8000,
  "order_id": "BR0000-{{$randomBankAccount}}",
  "order_info": "charge description",
  "currency": "BRL",
  "type": "PAYMENT",
  "soft_descriptor": "PAYTEST",
  "client_ip": "{{$randomIP}}",
  "payments": [
    {
      "payment_method": "card",
      "amount": 8000,
      "create_token": true,
      "card": {
        "number": "5970100300000067",
        "exp_year": 2028,
        "exp_month": 12,
        "cvv": "1234",
        "holder_name": "{{$randomFullName}}"
      }
    }
  ],
  "customer": {
    "name": "{{$randomFullName}}",
    "email": "{{$randomEmail}}",
    "phone": "551198570711",
    "mobile_phone": "5511985270748",
    "birth_date": "2000-01-01",
    "document_type": "CPF",
    "document_number": "62286843023"
  },
  "split": [
    {
      "seller_uuid": "0ec683ae-14da-455a-be39-98737a344762",
      "type": "PERCENTAGE",
      "amount": 5000
    },
    {
      "seller_uuid": "a25f03f6-f551-4b22-9350-2cd959f4b0df",
      "type": "PERCENTAGE",
      "amount": 2000
    }
  ]
}

Como interpretar

Distribuição do valor

Venda no cartão no valor total de R$ 80,00, com duas regras percentuais.

Vendedor 1

PERCENTAGEamount: 5000

50% R$ 40,00

Vendedor 2

PERCENTAGEamount: 2000

20% R$ 16,00

Distribuição da venda R$ 80,00

Vendedor 1 50%

Vendedor 2 20%

EstabelecimentoSaldo automático 30%

Resultado

Os vendedores recebem 70% da venda. Os R$ 24,00 restantes são destinados automaticamente ao estabelecimento.

O cliente realiza um único pagamento de R$ 80,00.

{ } Cartão com split misto — 3 vendedores

JSON

POST https://gateway-sandbox.cyclopay.com/v1/charges

{
  "amount": 10000,
  "order_id": "BR0001-{{$randomBankAccount}}",
  "order_info": "charge description",
  "currency": "BRL",
  "type": "PAYMENT",
  "soft_descriptor": "PAYTEST",
  "client_ip": "{{$randomIP}}",
  "payments": [
    {
      "payment_method": "card",
      "amount": 10000,
      "create_token": true,
      "card": {
        "number": "5970100300000067",
        "exp_year": 2028,
        "exp_month": 12,
        "cvv": "1234",
        "holder_name": "{{$randomFullName}}"
      }
    }
  ],
  "customer": {
    "name": "{{$randomFullName}}",
    "email": "{{$randomEmail}}",
    "phone": "551198570711",
    "mobile_phone": "5511985270748",
    "birth_date": "2000-01-01",
    "document_type": "CPF",
    "document_number": "62286843023"
  },
  "split": [
    {
      "seller_uuid": "0ec683ae-14da-455a-be39-98737a344762",
      "type": "PERCENTAGE",
      "amount": 4000
    },
    {
      "seller_uuid": "a25f03f6-f551-4b22-9350-2cd959f4b0df",
      "type": "AMOUNT",
      "amount": 2500
    },
    {
      "seller_uuid": "7a7c8666-c869-4f63-929e-aaa4cec85407",
      "type": "PERCENTAGE",
      "amount": 2000
    }
  ]
}

Como interpretar

Distribuição do valor

Venda no cartão no valor total de R$ 100,00, combinando percentual e valor fixo.

Vendedor 1

PERCENTAGEamount: 4000

40% R$ 40,00

Vendedor 2

AMOUNTamount: 2500

R$ 25,00 valor fixo

Terceiro vendedor

PERCENTAGEamount: 2000

20% R$ 20,00

Distribuição da venda R$ 100,00

Vendedor 1 40%

Vendedor 2 R$ 25,00

Terceiro vendedor 20%

Recebedor principalSaldo automático 15%

Resultado

As regras distribuem R$ 85,00. Os R$ 15,00 restantes são destinados automaticamente ao estabelecimento.

Os tipos PERCENTAGE e AMOUNT podem ser utilizados na mesma venda.

{ } Pix com split — 2 vendedores

JSON

POST https://gateway-sandbox.cyclopay.com/v1/charges

{
  "amount": 6000,
  "order_id": "BR0002-{{$randomBankAccount}}",
  "order_info": "charge description",
  "currency": "BRL",
  "type": "PAYMENT",
  "client_ip": "{{$randomIP}}",
  "payments": [
    {
      "payment_method": "pix",
      "amount": 6000
    }
  ],
  "customer": {
    "name": "{{$randomFullName}}",
    "email": "{{$randomEmail}}",
    "phone": "551198570711",
    "mobile_phone": "5511985270748",
    "birth_date": "2000-01-01",
    "document_type": "CPF",
    "document_number": "62286843023"
  },
  "split": [
    {
      "seller_uuid": "0ec683ae-14da-455a-be39-98737a344762",
      "type": "PERCENTAGE",
      "amount": 5000
    },
    {
      "seller_uuid": "a25f03f6-f551-4b22-9350-2cd959f4b0df",
      "type": "PERCENTAGE",
      "amount": 3500
    }
  ]
}

Como interpretar

Distribuição do valor

Venda via Pix no valor total de R$ 60,00, com duas regras percentuais.

Vendedor 1

PERCENTAGEamount: 5000

50% R$ 30,00

Vendedor 2

PERCENTAGEamount: 3500

35% R$ 21,00

Distribuição da venda R$ 60,00

Vendedor 1 50%

Vendedor 2 35%

EstabelecimentoSaldo automático 15%

Resultado

Os vendedores recebem 85% da venda. Os R$ 9,00 restantes são destinados automaticamente ao estabelecimento.

O cliente realiza um único pagamento via Pix de R$ 60,00.

{ } Boleto com split — 2 vendedores

JSON

POST https://gateway-sandbox.cyclopay.com/v1/charges

{
  "amount": 9000,
  "order_id": "BR0003-{{$randomBankAccount}}",
  "order_info": "charge description",
  "currency": "BRL",
  "type": "PAYMENT",
  "client_ip": "{{$randomIP}}",
  "payments": [
    {
      "payment_method": "boleto",
      "amount": 9000
    }
  ],
  "customer": {
    "name": "{{$randomFullName}}",
    "email": "{{$randomEmail}}",
    "phone": "551198570711",
    "mobile_phone": "5511985270748",
    "birth_date": "2000-01-01",
    "document_type": "CPF",
    "document_number": "62286843023"
  },
  "split": [
    {
      "seller_uuid": "0ec683ae-14da-455a-be39-98737a344762",
      "type": "PERCENTAGE",
      "amount": 6000
    },
    {
      "seller_uuid": "a25f03f6-f551-4b22-9350-2cd959f4b0df",
      "type": "PERCENTAGE",
      "amount": 2500
    }
  ]
}

Como interpretar

Distribuição do valor

Venda por boleto no valor total de R$ 90,00, com duas regras percentuais.

Vendedor 1

PERCENTAGEamount: 6000

60% R$ 54,00

Vendedor 2

PERCENTAGEamount: 2500

25% R$ 22,50

Distribuição da venda R$ 90,00

Vendedor 1 60%

Vendedor 2 25%

Recebedor principalSaldo automático 15%

Resultado

Os vendedores recebem 85% da venda. Os R$ 13,50 restantes são destinados automaticamente ao estabelecimento.

O cliente realiza um único pagamento por boleto de R$ 90,00.

{ } Cartão com REMAINING — primary percentual

JSON

POST https://gateway-sandbox.cyclopay.com/v1/charges

{
  "amount": 10000,
  "order_id": "BR0004-{{$randomBankAccount}}",
  "order_info": "charge description",
  "currency": "BRL",
  "type": "PAYMENT",
  "soft_descriptor": "PAYTEST",
  "client_ip": "{{$randomIP}}",
  "payments": [
    {
      "payment_method": "card",
      "amount": 10000,
      "create_token": true,
      "card": {
        "number": "5970100300000067",
        "exp_year": 2028,
        "exp_month": 12,
        "cvv": "1234",
        "holder_name": "{{$randomFullName}}"
      }
    }
  ],
  "customer": {
    "name": "{{$randomFullName}}",
    "email": "{{$randomEmail}}",
    "phone": "551198570711",
    "mobile_phone": "5511985270748",
    "birth_date": "2000-01-01",
    "document_type": "CPF",
    "document_number": "62286843023"
  },
  "split": [
    {
      "seller_uuid": "8772147d-0c7a-4e3e-8273-3524d7b37adf",
      "type": "PERCENTAGE",
      "amount": 2000
    },
    {
      "seller_uuid": "0ec683ae-14da-455a-be39-98737a344762",
      "type": "PERCENTAGE",
      "amount": 5000
    },
    {
      "seller_uuid": "a25f03f6-f551-4b22-9350-2cd959f4b0df",
      "type": "REMAINING"
    }
  ]
}

Como interpretar

Distribuição do valor

Venda no cartão no valor total de R$ 100,00, com participação explícita do primary.

Estabelecimento

PERCENTAGEamount: 2000

20% R$ 20,00

Vendedor 1

PERCENTAGEamount: 5000

50% R$ 50,00

Vendedor 2

REMAININGsem amount

30% R$ 30,00

Distribuição da venda R$ 100,00

Recebedor principalRegra explícita 20%

Vendedor 1 50%

Vendedor 2 · REMAINING 30%

Resultado

Após reservar 20% para o primary e 50% para o Vendedor 1, o vendedor com REMAINING recebe os 30% restantes.

Quando um seller secondary utiliza REMAINING, o primary deve aparecer no array com uma regra AMOUNT ou PERCENTAGE.

{ } Pix com REMAINING — primary por valor

JSON

POST https://gateway-sandbox.cyclopay.com/v1/charges

{
  "amount": 12000,
  "order_id": "BR0005-{{$randomBankAccount}}",
  "order_info": "charge description",
  "currency": "BRL",
  "type": "PAYMENT",
  "client_ip": "{{$randomIP}}",
  "payments": [
    {
      "payment_method": "pix",
      "amount": 12000
    }
  ],
  "customer": {
    "name": "{{$randomFullName}}",
    "email": "{{$randomEmail}}",
    "phone": "551198570711",
    "mobile_phone": "5511985270748",
    "birth_date": "2000-01-01",
    "document_type": "CPF",
    "document_number": "62286843023"
  },
  "split": [
    {
      "seller_uuid": "8772147d-0c7a-4e3e-8273-3524d7b37adf",
      "type": "AMOUNT",
      "amount": 2000
    },
    {
      "seller_uuid": "0ec683ae-14da-455a-be39-98737a344762",
      "type": "PERCENTAGE",
      "amount": 2500
    },
    {
      "seller_uuid": "a25f03f6-f551-4b22-9350-2cd959f4b0df",
      "type": "REMAINING"
    }
  ]
}

Como interpretar

Distribuição do valor

Venda via Pix no valor total de R$ 120,00, com valor fixo para o primary.

Estabelecimento

AMOUNTamount: 2000

R$ 20,00 valor fixo

Vendedor 1

PERCENTAGEamount: 2500

25% R$ 30,00

Vendedor 2

REMAININGsem amount

R$ 70,00 saldo restante

Distribuição da venda R$ 120,00

Recebedor principalRegra explícita R$ 20,00

Vendedor 1 25%

Vendedor 2 · REMAINING R$ 70,00

Resultado

Depois de destinar R$ 20,00 ao primary e R$ 30,00 ao Vendedor 1, o Vendedor 2 com REMAINING recebe o saldo de R$ 70,00.

O campo amount deve ser omitido na regra do tipo REMAINING.

Split de pagamentos

Como gerar uma Venda com Split

Tipos de divisão

Valores de acordo o Tipo de divisão

Saldo não distribuído

Utilização do tipo REMAINING

Gerar Venda com split

Meios de Pagamento

O split de uma venda, pode ser adicionado em duas situações:

Consultar Status de Split em uma Venda

Casos de uso e exemplos

Distribuição do valor

Distribuição do valor

Distribuição do valor

Distribuição do valor

Distribuição do valor

Distribuição do valor

Utilização do tipo `REMAINING`