Documentação
Status PageSuporte
  1. cel_banking - BaaS & Core
  2. Pix
  3. Split Pix

Split de Pix Cash-in por QR Code dinâmico (immediate)

Essa funcionalidade deve ser utilizada para realizar a criação de um QR Code de cobrança imediata., incluindo a opção de configurar um split de pagamento exclusivo para contas BaaS Celcoin.

Como criar um QR Code dinâmico (immediate) com split

Para realizar a geração de um QR Code Pix com Split de pagamento, deve-se utilizar a API - Split de Pix Cash-in por QR Code dinâmico (immediate).

A requisição deverá seguir o mesmo padrão utilizado atualmente para geração do Qrcode na API do PIX, adicionando o objeto feeInfo no payload da requisição.

Exemplo de objeto feeInfo:

"feeInfo": {
		"percent": 10,
        "totalAmount": 10,
		"feeDetails": [
			{
				"amount": 8,
				"description": "teste descricao",
				"clientRequestId": "{{clientCode}}",
				"accountCredit": "{{baas_account_env}}"
			},
            			{
				"amount": 2,
				"description": "teste descricao ",
				"clientRequestId": "{{clientCode}}",
				"accountCredit": "{{baas_account_env}}"
			}

Campos do objeto Split (feeInfo)

O objeto feeInfo é responsável por definir como o valor do split será distribuído entre as contas recebedoras.

Os campos possuem o seguinte comportamento:

Nome

Tipo

Descrição

percent

int

Percentual do split em cima do valor do Qr Code Gerado. Este campo serve como uma configuração geral para evitar erros.

totalAmount

decimal

Valor total que será distribuído entre as contas configuradas no split.
É a soma dos valores amount da lista do feeDetails

feeDetails

objeto

Lista contendo os detalhes da distribuição para cada conta recebedora. Objeto com as contas que receberão o split, onde é informado a conta, o valor e a descrição que aparecerá no extrato da conta

feeDetails.amount

decimal

Valor que será destinado para a conta informada.

feeDetails.description

string

Descrição do que será exibido no extrato do cliente

feeDetails.clientRequestID

string

Identificador único da operação de split para aquela conta recebedora.

feeDetails.accountCredit

string

Numero da conta individualizada que receberá parte da transação (split)

Regras gerais:

Para aplicar o split no QR Code Pix, é necessário popular o objeto feeInfo, onde é preciso informar como o split se realizará.

Limites e Quantidade de Contas:

  • Por padrão, é possível configurar até 5 (cinco) contas recebedoras em um mesmo split (além da conta principal recebedora do QR Code).
  • Caso exista necessidade de utilizar uma quantidade superior de contas, entre em contato para avaliação da solicitação.

Regra do Campo percent:

  • Por padrão, o percentual máximo permitido é de 10% sobre o valor total do QR Code. Caso seja necessário utilizar um percentual superior, entre em contato para avaliação da solicitação.
  • Esse campo percent funciona como uma validação de segurança (trava) para evitar divergências no valor total configurado para o split.

Exemplo de funcionamento

Valor total do QR Code: R$ 100,00

Campo percent: 10%

Neste caso, o totalAmount (que é a soma de todos os amounts dentro do feeDetails) deverá ser igual a R$ 10,00.

📘

Importante

No feeInfo não deverá ser informado o valor total do Qr Code. A informação do totalAmount é somente referente ao valor que será "splitado".

Também não deverá ser informada a conta "originadora" do split (a conta que gerou a chave pix/qr code).

Regras do clientRequestId

Para cada conta recebedora configurada no split:

  • Deve ser informado um clientRequestId único;
  • Não é permitido reutilizar o mesmo clientRequestId para múltiplas contas dentro do mesmo split

Regras de Devolução (Refund)

Sempre que uma transação Pix possuir configuração de split:

  • Em casos de devolução total ou parcial (refund), o valor devolvido será debitado exclusivamente da conta originadora da cobrança
  • Os valores enviados para contas participantes do split não serão estornados automaticamente. Ou seja, não haverá retirada automática de recursos das contas que receberam parte do split.

Modelo de request completo:

Rota - https://sandbox.openfinance.celcoin.dev/baas/v2/immediate/split

curl --request POST \
     --url https://sandbox.openfinance.celcoin.dev/baas/v2/immediate/split \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "clientRequestId": "f9b978a6-ab7e-4460-997d",
  "payerQuestion": "Informar cartao fidelidade",
  "key": "b7e4702-fb05-480",
  "locationId": 775645,
  "debtor": {
    "cpf": "12345678909",
    "cnpj": "42591962000102",
    "name": "Nome Silva"
  },
  "amount": {
    "original": 20,
    "changeType": 0,
    "withdrawal": {
      "vldnAmount": "10",
      "agentMode": "AGTEC",
      "withdrawalServiceProvider": "13935893",
      "changeType": 0
    },
    "change": {
      "vldnAmount": 13,
      "vlcpAmount": 25,
      "agentMode": "AGTEC",
      "withdrawalServiceProvider": "13935893",
      "changeType": 0
    }
  },
  "calendar": {
    "expiration": "86400"
  },
  "feeInfo": {
    "totalAmount": 100,
    "percent": 10
  }
}
👍

Retorno de sucesso

Modelo de response:

{
  "revision": 0,
  "transactionId": 9267254,
  "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
  "status": "ACTIVE",
  "lastUpdate": "2021-04-29",
  "payerQuestion": "Esta cobrança é referente a...",
  "additionalInformation": [
    {
      "value": "string",
      "key": "string"
    }
  ],
  "debtor": {
    "name": "string",
    "cpf": "string",
    "cnpj": "string"
  },
  "amount": {
    "original": 0,
    "changeType": 0,
    "withdrawal": {
      "vldnAmount": 0,
      "agentMode": "string",
      "withdrawalServiceProvider": "string",
      "changeType": 0
    },
    "change": {
      "vldnAmount": 0,
      "vlcpAmount": 0,
      "agentMode": "string",
      "withdrawalServiceProvider": "string",
      "changeType": 0
    }
  },
  "location": {
    "merchant": {
      "postalCode": "string",
      "city": "string",
      "merchantCategoryCode": 0,
      "name": "string"
    },
    "url": "string",
    "emv": "string",
    "type": "string",
    "locationId": "string",
    "id": "string"
  },
  "key": "5d000ece-b3f0-47b3-8bdd-c183e8875862",
  "calendar": {
    "expiration": 0
  },
  "createAt": "2021-04-29",
  "transactionIdentification": "kk6g232xel65a0daee4dd13kk479195205",
  "feeInfo": {
    "totalAmount": 100.97,
    "percent": 10,
    "feeDetails": [
      {
        "amount": 50.97,
        "description": "Pagamento referente a...",
        "clientRequestId": "f9b978a6-ab7e-4460-997d-2a5b2f30a956",
        "accountCredit": "30012345076543"
      }
    ]
  }
}

Erros

❗

Error 400

{
  "errorCode": "CBE620",
  "message": "Operação não realizada. Excedeu o tamanho maximo de FeeDetails permitido."
}

Tabela de Erros

Código ErroDescrição
CBE620Operação não realizada. Excedeu o tamanho maximo de FeeDetails permitido.
CBE621AccountCredit é obrigatório.
CBE622A soma dos valores do feeDetails não equivale a porcentagem informada.
CBE623TotalAmount é obrigatório.
CBE624A proporção de split informada excede o permitido ou é inválida.
CBE625Operação não permitida. Limite de webhooks cadastrados para o mesmo evento atingido.
CBE626A soma dos valores do feeDetails é diferente do totalAmount.

Recebendo notificações automáticas (Webhook)

Oferecemos a opção de configurar webhooks para receber notificações automáticas sempre que um pagamento via Pix Cash-in e informações sobre o Split. Esses webhooks são um meio eficiente de receber atualizações em tempo real sobre as transações realizadas.

📘

A conciliação para identificar a qual Qr Code Pix se refere o Split, deverá ser realizado com o campo TaxId. Essa informação do Qr Code Pix é "carregada" também para a transferência interna, permitindo assim a identificação de qual Qr Code Pix foi responsável por aquela transferencia interna de Split.

Para mais informações sobre a configuração e utilização dos webhooks, consulte a documentação específica disponível.

Eventos:
pix-payment-in -> Informações sobre o pagamento principal

internal-transfer-out -> Informações sobre o pagamento do split

Exemplos de Webhook (JSON)

pix-payment-in

{
    "webhookId": "receivement-E18236120202506262124s10c3fe4601",
    "RequestBody": {
        "TransactionType": "RECEIVEPIX",
        "Amount": 10,
        "createTimestamp": "06/26/2025 18:25:18",
        "TransactionId": "202506260000438423",
        "DebitParty": {
            "Account": "848093397",
            "Bank": "18236120",
            "Branch": "0001",
            "PersonType": "NATURAL_PERSON",
            "TaxId": "015358603",
            "AccountType": "TRAN",
            "Name": "Alessandro Oliveira"
        },
        "TransactionTypePix": "TRANSFER",
        "ClientRequestId": "50f5a7ef-966e-4e46-be38-6c16d5be1428",
        "Tenant": "5XT25YNjP8JDTG0i0PLdIyG0vYP6+BBLSWa6oSQm/SRrdlsHUuQOJeaTvabURFQ==",
        "withdrawalAgentMode": "AGTEC",
        "CreditParty": {
            "Account": "3005396812279",
            "Bank": "13935893",
            "Branch": "0001",
            "PersonType": "NATURAL_PERSON",
            "TaxId": "01535876603",
            "AccountType": "TRAN",
            "Key": "c563347a-7c07-44c0-bb09-674da64d525c",
            "Name": ""
        },
        "PaymentType": "IMMEDIATE",
        "transactionIdBRCode": "2754137742",
        "InitiationType": "DYNAMIC_QRCODE",
        "Urgency": "HIGH",
        "EndToEndId": "E18236120202506262124s10c3fe4601",
        "transactionIdentification": "kk6g232xel65a0daee4dd13kk2754137742"
    }
}

internal-transfer-out

{
							"webhookId": "3ed701cc-7bff-4de4-b2f1-e2d64707d9fc",
							"body": {
								"amount": 0.25,
								"debitParty": {
									"bank": "13935893",
									"taxId": "01535876603",
									"name": "Alessandro Henrique de Oliveira",
									"branch": "0001",
									"account": "3005396812279"
								},
								"clientRequestId": "8562e6ec-4d21-468e-81f8-2ecf381e55e6",
								"oldBalance": 33.41,
								"description": "split dinamico",
								"id": "3ed701cc-7bff-4de4-b2f1-e2d64707d9fc",
								"endToEndId": "5df2febc-9320-4af7-b665-f566a2fb33e3",
								"creditParty": {
									"bank": "13935893",
									"taxId": "01535876603",
									"name": "Alessandro Henrique de Oliveira",
									"branch": "0001",
									"account": "300539681148817"
								}
							},
							"entity": "internal-transfer-out",
							"createTimestamp": "2025-06-26T18:25:48.8619755",
							"status": "CONFIRMED"
						}

Link Documentação: Modelos de Webhooks do BaaS

Updated about 1 hour ago