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

Suggest Edits

Essa funcionalidade deve ser utilizada para realizar a criação de um QR Code de cobrança imediata. Desta forma, o caso de uso poderia ser:

Como fintech, quero disponibilizar aos meus usuários, a possibilidade de cobrar de forma imediata através de sua chave Pix, onde ele deverá apenas preencher o valor da operação e será apresentado um QR Code e seu código "Pix Copia e Cola" para pagamento da cobrança.

Por que usar um QR Code de cobrança imediata (immediate)?

Pode receber APENAS UM pagamento;
Além do valor, permite a inserção de mais informações, como tempo de expiração e dados do devedor;
Conciliação via identificador, possibilitando associar a transação Pix à cobrança correlata;
Em sua estrutura interna, é configurada uma URL que é acessada no momento de sua leitura. Assim, as informações trazidas pela URL podem variar em função de diversos parâmetros;
O QR Code dinâmico contém somente as informações básicas do usuário recebedor. As demais estão em um webservice da instituição do recebedor, com base nessa URL.

Fluxo de integração

Existem duas opções de fluxo para a criação de uma cobrança QRCode imediata, sendo elas:

Em duas etapas confirme o fluxograma anterior (Criação do location + Criação da Cobrança)
Em uma unica chamada, onde realizaremos internamente e criação do Location e a vinculação com a cobrança imediata (Dynamic).

Criando um QR Code

Para criar uma nova cobrança, é necessário gerar um QR Code e atrelar a ele os dados da cobrança que deseja executar, desta forma, o primeiro passo seria criar um QR Code, utilizando a API Criar um QR Code (Location).

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/location' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
  "type": "COB",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": "0000", 
    "name": "Celcoin Pagamentos"
  }
}'

Perceba que, no campo type, deve ser preenchido o valor COB e que o objeto merchant, você deve preencher os dados do recebedor, que incluem postalCode (CEP), city (cidade) e name (nome do recebedor). A propriedade merchantCategoryCode, pode ser preenchida com valor 0000.

Modelo de retorno:

{
    "status": "CREATED",
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "merchant": {
        "postalCode": "01201005",
        "city": "Barueri",
        "merchantCategoryCode": "0000",
        "name": "Celcoin Pagamentos"
    },
    "url": "api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f924",
    "emv": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f9245204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***63042570",
    "type": "COB",
    "locationId": 12730559
}

Se a sua requisição for recebida com sucesso, o retorno da propriedade status será CREATED.

Sugerimos que seja armazenado em sua aplicação o locationId (código do QR Code), EMV, pois você precisará desses valores para as próximas requisições.

Criando uma cobrança Pix imediata

Em seguida, deve ser realizada a requisição na API Criar cobrança imediata, para vincular o QR Code criado na requisição de location, a uma cobrança imediata Pix.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/immediate' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52207",
    "payerQuestion": "Não pagável após vencimento.",
    "key": "[email protected]",
    "locationId": 12730559,
    "debtor": {
        "name": "Fulano de Tal",
        "cnpj": "33188542046"
    },
    "amount": {
        "original": 15.00,
        "changeType": 0
    },
    "calendar": {
        "expiration": 86400
    },
    "additionalInformation": [
        {
            "value": "Assinatura de serviço",
            "key": "Produto 1"
        }
    ]
}'

A propriedade clientRequestId deve ser populada com um id único, fornecido por sua aplicação.

Dentro do objeto debtor, deve ser informado o nome e CPF/CNPJ de quem irá pagar os valores.

A propriedade key, deve ser preenchido com a chave Pix cadastrada na conta BaaS para a qual você deseja receber a cobrança. No exemplo acima, utilizamos a chave "[email protected]"

Dentro do objeto amount, deve ser informado o valor da cobrança e, por último, o objeto calendar deve ser populado com a data de expiração do QR Code. É importante ressaltar que todo QR Code dinâmico tem um tempo determinado para expirar. Caso esta data não seja informada na criação, será assumida a duração de 86400 segundos, que corresponde a 24 horas.

Modelo de retorno:

{
    "revision": 0,
    "transactionId": 9163565,
    "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52207",
    "status": "ACTIVE",
    "lastUpdate": "2022-03-07T18:02:09.8646387+00:00",
    "payerQuestion": "Não pagável após vencimento.",
    "additionalInformation": [
        {
            "value": "Assinatura de serviço",
            "key": "Produto 1"
        }
    ],
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": null,
        "cnpj": "33188542046"
    },
    "amount": {
        "original": 15.00,
        "changeType": 0,
        "withdrawal": null,
        "change": null
    },
    "location": {
        "merchant": {
            "postalCode": "01201005",
            "city": "Barueri",
            "merchantCategoryCode": "0000",
            "name": "Celcoin Pagamentos"
        },
        "url": "api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f924",
        "emv": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f9245204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***63042570",
        "type": "COB",
        "locationId": 12730559,
        "id": null
    },
    "key": "[email protected]",
    "calendar": {
        "expiration": 86400
    },
    "createAt": "2022-03-07T18:02:09.8646387+00:00",
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk9163565"
}

Sugerimos que seja armazenada, em sua aplicação, as propriedades transactionId e transactionIdentification, para conseguir receber da Celcoin o status da cobrança via webhook, createAt e expiration, para avaliar se o QR Code ainda é válido.

O campo Revision indica quantas revisões ocorreram no QR Code e campo Status, informa o status atual da cobrança imediata, podendo ser:

"ACTIVE": ativo, mas ainda não teve pagamento;
"CONCLUDED": quando o pagamento já ocorreu;
"DELETED_BY_RECEIVING_USER": deletado por solicitação do usuário final;
"DELETED_BY_PSP": deletado por solicitação do participante do Pix.

🚧
A seguir o fluxo alternativo resumido (Dynamic):

Criando uma cobrança Pix imediata (Dynamic)

Esta chamada resume as duas chamadas anteriores em uma unica requisição Dynamic da mesma forma criando uma cobrança imediata Pix.

Modelo de request:

curl --location 'https://sandbox.openfinance.celcoin.dev/pix/v1/brcode/dynamic' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "key": "[email protected]",
  "amount": "10.00",
  "merchant": {
    "merchantCategoryCode": "5651",
    "postalCode": "06519435",
    "city": "barueri",
    "name": "Teste Celcoin"
  },
  "expiration": 30000,
  "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52208",
  "payerName": "Teste Celcoin",
  "payerCPF": "13935893000370",
  "payerQuestion": "Criacao do QRCode immediate teste"
}'

A propriedade clientRequestId deve ser populada com um id único, fornecido por sua aplicação.

Dentro do objeto debtor, deve ser informado o nome e CPF/CNPJ de quem irá pagar os valores.

A propriedade key, deve ser preenchido com a chave Pix cadastrada na conta BaaS para a qual você deseja receber a cobrança. No exemplo acima, utilizamos a chave ""

Modelo de retorno:

{
    "version": "1.0.0",
    "status": 201,
    "body": {
        "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52208",
        "pactualId": null,
        "transactionId": "4000095510",
        "createTimestamp": "2024-09-04T02:05:42.5489802Z",
        "lastUpdateTimestamp": "0001-01-01T00:00:00",
        "entity": "DynamicBRCode",
        "status": "ACTIVE",
        "tags": null,
        "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000095510",
        "body": {
            "key": "[email protected]",
            "revision": "0",
            "location": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/69e2bd66eecb47dfc632a5c7fcbcac",
            "debtor": {
                "name": "Teste Celcoin",
                "cpf": "13935893000370",
                "cnpj": null
            },
            "amount": {
                "original": 10.00
            },
            "calendar": {
                "expiration": 30000,
                "dueDate": "2024-09-04T07:25:42.5489826"
            },
            "dynamicBRCodeData": {
                "pointOfInitiationMethod": "12",
                "payloadFormatIndicator": "01",
                "countryCode": "BR",
                "merchantName": "Teste Celcoin",
                "merchantCity": "barueri",
                "transactionIdentification": "***",
                "transactionAmount": "10.00",
                "emvqrcps": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/pixqrcode/v2/69e2bd66eecb47dfc632a5c7fcbcac5204000053039865802BR5913Teste Celcoin6007barueri62070503***63045967",
                "merchantCategoryCode": 5651,
                "transactionCurrency": 986,
                "merchantAccountInformation": {
                    "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/69e2bd66eecb47dfc632a5c7fcbcac"
                }
            },
            "additionalInformation": null
        }
    }
}

O campo Revision indica quantas revisões ocorreram no QR Code e campo Status, informa o status atual da cobrança imediata, podendo ser:

"ACTIVE": ativo, mas ainda não teve pagamento;
"CONCLUDED": quando o pagamento já ocorreu;
"DELETED_BY_RECEIVING_USER": deletado por solicitação do usuário final;
"DELETED_BY_PSP": deletado por solicitação do participante do Pix.

Objeto Split

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

É possível informar até 5 contas diferentes para receber valor referente a um mesmo Qr Code.

O campo percentservirá como uma "trava" de segurança para evitar erros de preenchimento.
Exemplo: o campo percent está preenchido com 10%.

O valor total do Qr Code é de R$ 100,00.

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

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

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	É a soma dos valores amount da lista do feeDetails
feeDetails	objeto	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 a conta receberá do split
feeDetails.description	string	Descrição do que será exibido no extrato do cliente
feeDetails.clientRequestID	string	Identificador único
feeDetails.accountCredit	string	Numero da conta individualizada que receberá parte da transação (split)

Tabela de Erros

Código Erro	Descrição
CBE620	Operação não realizada. Excedeu o tamanho maximo de FeeDetails permitido.
CBE621	AccountCredit é obrigatório.
CBE622	A soma dos valores do feeDetails não equivale a porcentagem informada.
CBE623	TotalAmount é obrigatório.
CBE624	A proporção de split informada excede o permitido ou é inválida.
CBE625	Operação não permitida. Limite de webhooks cadastrados para o mesmo evento atingido.
CBE626	A soma dos valores do feeDetails é diferente do totalAmount.

Modelo de request completo:

Rota Immediate - /immediate/split

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/duedate/split' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "clientRequestId": "f9b978a6-ab7e-4460-997d-2a5b2f30a956",
  "expirationAfterPayment": 10,
  "duedate": "2021-04-29 00:00:00",
  "debtor": {
    "name": "João da Silva",
    "cpf": "J11122233366",
    "cnpj": "1112223300100",
    "city": "Barueri",
    "publicArea": "Avenida Brasil",
    "state": "SP",
    "postalCode": "01202003",
    "email": "[email protected]"
  },
  "receiver": {
    "name": "João da Silva",
    "cpf": "J11122233366",
    "cnpj": "1112223300100",
    "postalCode": "01202003",
    "publicArea": "Barueri",
    "state": "SP",
    "fantasyName": "Nome de Comercial",
    "city": "Barueri"
  },
  "locationId": 55845,
  "amount": 15.63,
  "amountDicount": {
    "discountDateFixed": [
      {
        "date": "2021-04-29",
        "amountPerc": "1.00"
      }
    ],
    "hasDicount": false,
    "modality": "FIXED_VALUE_UNTIL_THE_DATES_INFORMED",
    "amountPerc": "0.00"
  },
  "amountAbatement": {
    "hasAbatement": false,
    "modality": "FIXED_VALUE",
    "amountPerc": "0.00"
  },
  "amountFine": {
    "hasFine": false,
    "modality": "FIXED_VALUE",
    "amountPerc": "0.00"
  },
  "amountInterest": {
    "hasInterest": false,
    "modality": "VALUE_CALENDAR_DAYS",
    "amountPerc": "0.00"
  },
  "additionalInformation": [
    {
      "value": "Assinatura de serviço",
      "key": "Produto 1"
    }
  ],
  "payerQuestion": "pagamento referente a...",
  "key": "5d000ece-b3f0-47b3-8bdd-c183e8875862",
  "feeInfo": {
    "totalAmount": 50.97,
    "percent": 10,
    "feeDetails": [
      {
        "amount": 50.97,
        "description": "Pagamento referente a...",
        "clientRequestId": "f9b978a6-ab7e-4460-997d-2a5b2f30a956",
        "accountCredit": "30012345076543"
      }
    ]
  }
}'

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 for recebido. 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.

Evento:

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

Em caso de dúvidas adicionais, nossa equipe de suporte estará disponível para ajudar.

Updated about 20 hours ago

Por que usar um QR Code de cobrança imediata (immediate)?

Fluxo de integração

Criando um QR Code

Criando uma cobrança Pix imediata

🚧A seguir o fluxo alternativo resumido (Dynamic):

Criando uma cobrança Pix imediata (Dynamic)

Objeto Split

Recebendo notificações automáticas (Webhook)

🚧
A seguir o fluxo alternativo resumido (Dynamic):