Como Fintech quero disponibilizar para os meus usuários a possibilidade de realizar pagamentos de QR Codes estáticos, para qualquer instituição financeira, uma vez que ele escanear, 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 estático?

Rol mais limitado de campos em seu escopo.
Pagamento imediato.
O mesmo QR Code pode ser usado em múltiplas transações.
Permite definir um valor fixo da cobrança, ou deixar o valor ser preenchido pelo pagador.
Recomendamos para recebimentos que não necessariamente exigem integração de sistemas e de automatização de processos, como é o caso de pessoas físicas, profissionais liberais e algumas micro e pequenas empresas.
Em geral, é gerado no próprio canal oficial da instituição: aplicativo ou internet banking, na opção “Pix”, “cobrar com QR Code” ou outros, conforme definições do BCB.

Passos para Integrar

Converter QR Code no formato EVP
Realizar autenticação na API - [API Reference]
Consultar Informações do QR Code a partir do código EVP - [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]

📘
Glossário
EVP = Chave Aleatória

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' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "emv": "00020126730014br.gov.bcb.pix0123testepix@celcoin.com.br0224Referente ao custo de...520400005303986540510.555802BR5907Celcoin6007Barueri61080120100562270523testqrcodestaticcelcoin6304C3A1"
}'

Modelo de retorno:

{
    "type": "1",
    "collection": null,
    "payloadFormatIndicator": "01",
    "merchantAccountInformation": {
        "url": null,
        "gui": "br.gov.bcb.pix",
        "key": "[email protected]",
        "additionalInformation": "Referente ao custo de...",
        "withdrawalServiceProvider": null
    },
    "merchantCategoryCode": 0,
    "transactionCurrency": 986,
    "transactionAmount": 10.55,
    "countryCode": "BR",
    "merchantName": "Celcoin",
    "merchantCity": "Barueri",
    "postalCode": "01201005",
    "initiationMethod": null,
    "transactionIdentification": "testqrcodestaticcelcoin"
}

A propriedade type representa o tipo do QR Code, portanto deve ser validado se o que você está consultando é estático (representado pelo valor 1), ou dinâmico (2). O fluxo abaixo explica como dar continuidade para QR Codes estáticos. No caso de QR Codes dinâmicos veja esse artigo.

Recomendamos que seja armazenado em sua aplicação a propriedade key (chave Pix), o transactionIdentification (id de identificação da transação), para uso nas próximas requisições.

Estrutura dos dados retornados:

Campo	Descrição
type	Tipo do QR Code (1 = estático, 2 = dinâmico)
collection	Informa se o QRCode dinâmico é COB (1) ou COBV (2)
payloadFormatIndicator	Indicador de formato de carga útil
merchantAccountInformation	Informações sobre a cobrança atrelada ao QR Code
merchantCategoryCode	Número de quatro dígitos, listado na ISO 18245
transactionCurrency	Código da moeda corrente
transactionAmount	Valor da transação
countryCode	Código do país
merchantName	Nome do emissor da cobrança
merchantCity	Cidade do emissor da cobrança
postalCode	CEP
initiationMethod	Representa o tipo de pagamento
transactionIdentification	Identificação da transação

Caso você não tenha um EMV, para realizar os testes, basta criar um com a API da Celcoin Criar um QR Code estático.

Abaixo deixo um modelo de request para criar o QR Code:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/brcode/static' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "key": "[email protected]",
  "amount": 10.55,
  "transactionIdentification": "testqrcodestaticcelcoin",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": 0,
    "name": "Celcoin"
  },
  "tags": [
    "string"
  ],
  "additionalInformation": "Referente ao pagamento de...",
  "withdrawal": false
}'

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 Estático

JSON de exemplo

{
  "amount": 25.55,
  "clientCode": "1458854",
  "transactionIdentification": "dc8cf02b81b54bd59323453b207e704a",
  "endToEndId": "E3030629420200808185300887639654",
  "initiationType": "STATIC_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": "STATIC_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	Dados do pagador
account*	Número da conta de origem (Quem irá pagar).
creditParty	Objeto	Dados do recebedor
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.
PBE7055	Instituição recebedora não está respondendo

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 Estático

Por que usar um QR Code estático?

Passos para Integrar

📘
Glossário

Decodificando QR Code

Consultar chaves Pix Externa (DICT)

👍
Sucesso 200

❗
Error 400

Transferência Pix Cash-Out a partir de QR Code Estático

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 estático?

Passos para Integrar

📘Glossário

Decodificando QR Code

Consultar chaves Pix Externa (DICT)

👍Sucesso 200

❗Error 400

Transferência Pix Cash-Out a partir de QR Code Estático

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)

📘
Glossário

👍
Sucesso 200

❗
Error 400

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

🚧
Atenção!!

👍
Sucesso 200

❗
Error 400