Essa funcionalidade, deve ser utilizada sempre que um usuário da sua aplicação deseja realizar o pagamento de um QR Code Pix dinâmico.

Desta forma o caso de uso pode ser:

Como Fintech quero disponibilizar para os meus usuários a possibilidade de realizar pagamentos de QR Codes dinâmicos, para qualquer instituição financeira, uma vez que ele scanear, ou digitar o copia e cola, onde será retirado o saldo de sua conta e usado para pagar o emissor do QR Code.

Por que usar um QR Code dinâmico?

Apresenta em seu escopo um rol extenso de campos passíveis de configuração por parte do recebedor.
Permite a realização de pagamento imediato ou com vencimento.
É usado uma única vez para uma transação específica.
Além do valor, permite a inserção de mais informações na modalidade com vencimento, como as regras de cálculo de juros, multa, descontos, entre outras.
É recomendado para recebedores que demandem funcionalidades facilitadoras do processo de conciliação, da integração de sistemas e da automatização de processos.
É gerada por meio da integração via API Pix. Segundo define o BCB, é possível gerar um único QR Code ou proporcionar uma geração em lote, necessária, por exemplo, para empresas prestadoras de serviço que desejam gerar faturas para toda sua base de clientes. Por isso, o QR Code Pix agiliza os processos das empresas, principalmente dos comércios.

Passos para Integrar

Converter QR Code no formato EMV
Realizar autenticação na API - [API Reference]
Consultar Informações do QR Code a partir do código EMV- [API Reference]
Consultar Chave vinculada ao QR Code - [API Reference]
Realizar o Pix Cash Out - [API Reference]
Receber o Webhook com Status do Pix

Caso seja necessário você pode consultar o status do Pix manualmente.

Consultar Status do Pix - [API Reference]

Decodificando QR Code

Para iniciar o processo de pagamento de um QR Code é necessário realizar sua leitura, portanto, é preciso decodificar ele, onde é gerado um código EMV (padrão criado para leitura de QR Code Pix no Brasil, nos sistemas financeiros geralmente é nomeado de Pix Copia e Cola). Para isso, basta utilizar API Retorna as informações do QR Code a partir de um EMV.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/emv/full' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "emv":  "00020101021226930014br.gov.bcb.pix2571api-h.developer.celcoin.com.br/v1/p/v2/0223b7626a7247e58a35cfadb1c18ba85204000053039865802BR5907Celcoin6007Barueri61080120100562070503***6304CB07"
}'

Modelo de retorno:

{
	"version": "1.0.0",
	"status": 200,
	"body": {
		"type": "IMMEDIATE",
		"merchantAccountInformation": {
			"url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/629051a146ced3f2cb1dc6276d7515",
			"gui": "br.gov.bcb.pix",
			"merchantCategoryCode": "0000",
			"additionaldata": null,
			"withdrawalServiceProvider": null,
			"merchantName": "Teste Pix Celcoin",
			"merchantCity": "barueri",
			"postalCode": null
		},
		"key": "fc048fc5-925f-405d-bfd7-8d3117f9f53c",
		"amount": {
			"original": 10.0,
			"abatement": null,
			"discount": null,
			"interest": null,
			"final": 10.0,
			"fine": null,
			"canModifyFinalAmount": false,
			"withdrawal": null,
			"change": null
		},
		"transactionIdentification": "kk6g232xel65a0daee4dd13kk4000177597",
		"payload": {
			"status": "ACTIVE",
			"revision": 0,
			"calendar": {
				"createdAt": "2025-03-05T15:12:37.195Z",
				"presentation": "2025-03-05T15:13:02.954Z",
				"dueDate": null,
				"validateAfterDuedate": null,
				"expiration": 30000,
				"expirationDate": "2025-03-05T23:32:37.195Z"
			},
			"debtor": {
				"cpf": null,
				"cnpj": null,
				"name": null
			},
			"receiver": null,
			"payerQuestion": null,
			"additionalInformation": null
		}
	}
}

A propriedade type representa o tipo do QR Code, portanto deve ser validado se o que você está consultando é estático (STATIC) ou dinâmico (IMMEDIATE ou DUEDATE). É importante saber qual é o tipo do qrcode, pois isso irá definir o modelo do pagamento a ser utilizado.

Estrutura dos dados retornados:

Campo	Descrição
version	Versão da API utilizada.
status	Código de status da resposta.
body	Objeto.
body.type	Tipo do QRCode (STATIC, IMMEDIATE ou DUEDATE).
body.merchantAccountInformation	Objeto.
body.merchantAccountInformation.url	URL do QR Code Pix gerado.
body.merchantAccountInformation.gui	Informações sobre a cobrança atrelada ao QR Code
body.merchantAccountInformation.merchantCategoryCode	Código da categoria do emissor da cobrança
body.merchantAccountInformation.merchantName	Nome do emissor da cobrança.
body.merchantAccountInformation.merchantCity	Cidade do emissor da cobrança.
body.merchantAccountInformation.postalCode	Código postal do emissor da cobrança.
body.key	Chave Pix.
body.amount	Objeto.
body.amount.original	Valor original da transação.
body.amount.final	Valor final da transação.
body.amount.canModifyFinalAmount	Indica se o valor final pode ser alterado.
body.transactionIdentification	Identificador único do QRCode.
body.payload	Objeto.
body.payload.status	Status do QRCode.
body.payload.revision	Número de revisão.
body.payload.calendar	Objeto.
body.payload.calendar.createdAt	Data e hora de criação da transação.
body.payload.calendar.presentation	Data e hora de apresentação da transação.
body.payload.calendar.expiration	Tempo de expiração do QRCode em segundos.
body.payload.calendar.expirationDate	Data e hora de expiração do pagamento.
body.payload.debtor	Objeto.
body.payload.debtor.cpf	CPF do pagador, caso tenha sido definido.
body.payload.debtor.cnpj	CNPJ do devedor, caso tenha sido definido.
body.payload.debtor.name	Nome do devedor, caso tenha sido definido.
body.payload.receiver	Informações do recebedor.
body.payload.payerQuestion	Pergunta ao pagador (se houver).
body.payload.additionalInformation	Informações adicionais (se houver).

O fluxo abaixo explica como dar continuidade no pagamento de QR Codes dinâmicos.

📘
Caso você não tenha um EMV de um QR Code dinâmico, para realizar os testes, basta criar um via API Celcoin Criar um QR Code imediato (COB) (Dynamic), Criar QR Code dinâmico com vencimento (COBV).
É importante usar chaves criadas no ambiente de sandbox para a criação dos QRCodes e conseguir finalizar seus testes, caso contrário será apresentado erro na hora de realizar a consulta da chave DICT ou no webhook de confirmação após o pagamento.

Consultar chaves Pix Externa (DICT)

Para realizar o pagamento de um QR Code é necessário consultar os dados bancários cadastrados na chave Pix que retornou da consulta EMV. Sendo assim, se faz necessário realizar uma consulta no DICT na API Retorna as informações do DICT utilizando uma chave cadastrada no Pix, onde será retornado algumas informações que são obrigatórias ao realizar um pagamento.

cURL da chamada

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/celcoin-baas-pix-dict-webservice/v1/pix/dict/entry/external/[email protected]' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

Exemplo de retorno

👍
Sucesso 200

{
  "version": "1.0.0",
  "status": "SUCCESS",
  "body": {
    "keyType": "string",
    "key": "string",
    "account": {
      "participant": "30306294",
      "branch": "0001",
      "account": "10545584",
      "accountType": "TRAN",
      "createDate": "2020-11-03T06:30:00-03:00"
    },
    "owner": {
      "type": "NATURAL_PERSON",
      "documentNumber": "34335125070",
      "name": "Carlos Henrique da Silva"
    },
    "endtoEndId": "string",
    "statistics": {
      "lastUpdated": "2023-03-08T11:01:26.101Z",
      "counters": [
        {
          "type": "string",
          "by": "string",
          "d3": "string",
          "d30": "string",
          "m6": "string"
        }
      ]
    }
  }
}

❗
Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CBE177",
    "message": "Operação não permitida. Conta esta bloqueada"
  }
}

Tabela de errorCode

Code	Message
CBE091	É necessário informar pelo menos um dos campos: id, clientCode, ou endtoendId.
CBE039	Account invalido.
CBE175	Cadastro de chave não permitido. Verifique o formato da chave informada
CBE041	Account possui tamanho maximo de 20 caracteres
CBE174	O Campo key não pode ultrapassar 77 caracteres
CBE176	Operação não permitida. Conta esta encerrada
CBE177	Operação não permitida. Conta esta bloqueada
CBE190	Operação Não permitida. Chave não esta vinculada a essa conta.

Transferência Pix Cash-Out a partir de QR Code Dinâmico

JSON de exemplo

{
  "amount": 25.55,
  "clientCode": "1458854",
  "transactionIdentification": "dc8cf02b81b54bd59323453b207e704a",
  "endToEndId": "E3030629420200808185300887639654",
  "initiationType": "DYNAMIC_QRCODE",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "transactionType": "TRANSFER",
  "debitParty": {
    "account": "444444"
  },
  "creditParty": {
    "bank": "30306294",
    "key": "5244f4e-15ff-413d-808d-7837652ebdc2",
    "account": "10545584",
    "branch": "10545584",
    "taxId": "11122233344",
    "name": "Celcoin",
    "accountType": "CACC"
  },
  "remittanceInformation": "Texto de mensagem"
}

cURL da chamada

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/baas-wallet-transactions-webservice/v1/pix/payment' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 25.55,
  "clientCode": "1458854",
  "transactionIdentification": "dc8cf02b81b54bd59323453b207e704a",
  "endToEndId": "E3030629420200808185300887639654",
  "initiationType": "DYNAMIC_QRCODE",
  "paymentType": "IMMEDIATE",
  "urgency": "HIGH",
  "transactionType": "TRANSFER",
  "debitParty": {
    "account": "444444"
  },
  "creditParty": {
    "bank": "30306294",
    "key": "5244f4e-15ff-413d-808d-7837652ebdc2",
    "account": "10545584",
    "branch": "10545584",
    "taxId": "11122233344",
    "name": "Celcoin",
    "accountType": "CACC"
  },
  "remittanceInformation": "Texto de mensagem"
}'

Descrição dos campos

Campo	Descrição	Tipo Campo
amount*	Valor da transação.
clientCode*	Identificador único da transação gerado pelo cliente.
transactionIdentification	Identificador único retornado durante a leitura do BRCode.	Se initiationType igual a MANUAL ou DICT, esse campo não deve ser informado, Se initiationType igual a STATIC_QRCODE, esse campo se torna obrigatório e com tamanho maximo permitido de 25 caracteres. Se initiationType igual a DYNAMIC_QRCODE, esse campo se torna obrigatório e com tamanho maximo permitido entre 26 a 35 caracteres.
endToEndId	Identificador ponta-a-ponta associado ao pagamento.	Se initiationType igual a MANUAL, esse campo não deve ser informado pois o mesmo sera gerado pela Celcoin. Se initiationType diferente de MANUAL, esse campo deve ser recuperado pelo endpoint /pix/dict/{key}.
initiationType	Tipo de iniciação do pagamento	MANUAL: Pagamento via dados transacionais da conta. (creditParty.key, endToEndId, e transactionIdentification, não devem ser informados). DICT: Pagamento via chave. (Campos obrigatórios : creditParty.key, e endToEndId.transactionIdentification não deve ser informado). STATIC_QRCODE: Pagamento via BRCode estatico. (Campos obrigatórios : creditParty.key, endToEndId, e transactionIdentification). DYNAMIC_QRCODE: Pagamento via BRCode dinamico. (Campos obrigatórios : creditParty.key, endToEndId, e transactionIdentification).
paymentType	Tipo de pagamento	IMMEDIATE: Usado para pagamentos imediatos. FRAUD: Usado para pagamento por suspeita de fraude. SCHEDULED: Usado apenas para pagamentos agendados.
urgency	Determina a urgência do pagamento	HIGH - usado para pagamentos imediatos. NORMAL - usado para pagamentos agendados.
transactionType	Tipo da transação Pix	TRANSFER: Usado para pagamentos imediatos.
debitParty	Objeto
account*	Número da conta de origem (Quem irá pagar).
creditParty	Objeto
bank*	Identificador do Banco de destino (ISPB - Identificador de Sistema de Pagamentos Brasileiro).
key*	Chave Pix.
account	Número da Conta de destino (Quem irá receber).
branch	Número da agência de destino.
taxId	Número do documento (CPF ou CNPJ) da conta de destino.
name*	Nome da conta de destino
accountType	Tipo de Conta Pix.	CACC - Normal ou contas digitais TRAN - Conta de pagamentos SLRY - Conta salario SVGS - Conta poupança
remittanceInformation	Determina um texto a ser apresentado ao pagador para que ele possa inserir uma informação correlacionada, em formato livre, para ser enviada ao destinatário. Se presente durante a leitura do Dynamic BRCode deve ser preservado e informado aqui.

❗
Campo com * são obrigatórios na chamada

Exemplo de retorno

🚧
Atenção!!
Caso ocorra algum erro da família 5xx ao tentar realizar um pagamento, ou transfêrencia Pix e, ao consultar nossa api o status da transação esteja PROCESSING, recomendamos que aguarde até receber o disparo do gatilho com o novo status da transação. Sendo assim, não recomendamos o cancelamento da transação, pois o mesmo pode acarretar problemas em sua integração.

👍
Sucesso 200

{
  "status": "PROCESSING",
  "version": "1.0.0",
  "body": {
    "id": "34fee7bc-4d40-4605-9af8-398ed7d0d6b5",
    "amount": 0,
    "clientCode": "1458854",
    "transactionIdentification": "dc8cf02b81b54bd59323453b207e704a",
    "endToEndId": "E3030629420200808185300887639654",
    "initiationType": "STATIC_QRCODE",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH",
    "transactionType": "TRANSFER",
    "debitParty": {
      "account": "444444",
      "branch": "1",
      "taxId": "11122233344",
      "name": "Celcoin",
      "accountType": "CACC"
    },
    "creditParty": {
      "bank": "30306294",
      "key": "5244f4e-15ff-413d-808d-7837652ebdc2",
      "account": "10545584",
      "branch": "1",
      "taxId": "11122233344",
      "name": "Celcoin",
      "accountType": "CACC"
    },
    "remittanceInformation": "Texto de mensagem"
  }
}

❗
Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CBE039",
    "message": "Account invalido.."
  }
}

Tabela de errorCode

Code	Message
CBE001	ClientCode é obrigatório.
CBE093	ClientCode possui tamanho maximo de 200 caracteres.
CBE094	amount é obrigatório.
CBE095	amount invalido.Favor verificar a formatação do campo e deve ser maior que 0.
CBE100	Existe um lançamento idêntico pendente.Favor aguarde para realizar esta operação para evitar duplicidade.
CBE101	Já existe um lançamento com o mesmo clientCode. Favor realizar uma nova operação.
CBE102	Lançamento de debito não permitido.Valor ultrapassa o limite maximo permitido por operação.
CBE107	debitParty é obrigatório.
CBE108	debitparty.account é obrigatório.
CBE109	debitparty.account invalido.
CBE110	debitparty.account possui tamanho maximo de 20 caracteres.
CBE115	creditParty é obrigatório.
CBE116	creditparty.account é obrigatório.
CBE117	creditparty.account invalido.
CBE118	creditparty.account possui tamanho maximo de 20 caracteres.
CBE119	creditParty.branch é obrigatório.
CBE120	creditParty.branch invalido.
CBE121	creditParty.taxId é obrigatório.
CBE122	creditParty.taxId invalido.
CBE123	Transação não permitida.Conta com saldo insuficiente.
CBE124	Lançamento não permitido.debit.account esta encerrada.
CBE126	creditParty.bank é obrigatório e deve existir na lista de participantes Pix.
CBE127	creditParty.name é obrigatório e possui tamanho maximo de 120 caracteres.
CBE128	creditParty.accountType não foi informado ou é invalido.
CBE129	remittanceInformation possui tamanho máximo de 140 caracteres.
CBE130	initiationType invalido.
CBE131	paymentType invalido.
CBE132	urgency invalido.
CBE133	transactionType invalido.
CBE134	Campo transactionIdentification é de uso exclusivo para pagamentos de QRCodes. InitiationType STATIC_QRCODE ou DYNAMIC_QRCODE.
CBE135	Campo transactionIdentification é de preenchimento obrigatório para pagamentos de QRCodes. InitiationType DYNAMIC_QRCODE.
CBE136	Quando initiationType igual a STATIC_QRCODE o campo transactionIdentification não pode ultrapassar 25 caracteres.
CBE137	Quando initiationType igual a DYNAMIC_QRCODE o campo transactionIdentification não pode ultrapassar 35 caracteres.
CBE139	Já existe uma transação com o mesmo endToEndId. Favor realizar uma nova operação.
CBE139	Quando initiationType igual a DICT os campos endToEndId e credityParty.key se tornam obrigatórios.
CBE140	Quando initiationType igual a STATIC_QRCODE o campo credityParty.key se torna obrigatório.
CBE141	Quando initiationType igual a DYNAMIC_QRCODE o campo credityParty.key se torna obrigatório.
CBE142	Quando initiationType igual a MANUAL o campo credityParty.key não deve ser informado.
CBE143	Quando paymentType está preenchido com Valor SCHEDULED, o campo urgency deve ser preenchido com valor NORMAL.
CBE144	Quando paymentType está preenchido com Valor IMMEDIATE ou FRAUD, o campo urgency deve ser preenchido com valor HIGH.
CBE145	Tipo de iniciação de pagamento não permitido.Para mais informações, entre em contato com o nosso suporte.
CBE146	endToEndId invalido.
CBE159	Lançamento não permitido.Sua conta esta bloqueada.

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-out for realizado. Esses webhooks são um meio eficiente de receber atualizações em tempo real sobre as transações realizadas.

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

Evento: pix-payment-out

Link Documentação: Modelos de Webhooks do BaaS

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

Realizar um Pix Cash-Out por QR Code Dinâmico

Por que usar um QR Code dinâmico?

Passos para Integrar

Decodificando QR Code

📘

Consultar chaves Pix Externa (DICT)

👍
Sucesso 200

❗
Error 400

Transferência Pix Cash-Out a partir de QR Code Dinâmico

Descrição dos campos

❗
Campo com * são obrigatórios na chamada

Exemplo de retorno

🚧
Atenção!!

👍
Sucesso 200

❗
Error 400

Recebendo notificações automáticas (Webhook)

Por que usar um QR Code dinâmico?

Passos para Integrar

Decodificando QR Code

📘

Consultar chaves Pix Externa (DICT)

👍Sucesso 200

❗Error 400

Transferência Pix Cash-Out a partir de QR Code Dinâmico

Descrição dos campos

❗Campo com * são obrigatórios na chamada

Exemplo de retorno

🚧Atenção!!

👍Sucesso 200

❗Error 400

Recebendo notificações automáticas (Webhook)

👍
Sucesso 200

❗
Error 400

❗
Campo com * são obrigatórios na chamada

🚧
Atenção!!

👍
Sucesso 200

❗
Error 400