Pagamento de um QR Code Estático

Pré requisitos para implementação:

• Possuir uma chave api da Celcoin, para mais informações acessar esse link

• Ter familiaridade com apis Rest usando o protocolo OAuth 2.0.

• Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

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

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.

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

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": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/pixqrcode/v2/bafd37238fa15e769be8584610caf15904000753039065802BR5823FORTUNA INSTITUICAO DE6007Barueri62070503***630475F1",
  "payerId": "01548965954",
  "endToEndId": "E3030629420200808185300887639654",
  "codMun": "1302405",
  "dpp": "2023-06-02",
  "estatisticasChave": true
}'

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:

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
}'

Consulta no 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.

O campo payerId é obrigatório devido a uma solicitação do Banco Central e deve ser preenchido com um CPF ou CNPJ, sem os caracteres especiais, da sua instituição. Para testar essa consulta em sandbox recomendamos o uso da propriedade key populada com o valor [email protected], pois nosso ambiente está preparado para retornar a consulta deste e-mail.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/dict/v2/key' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "payerId": "33188542046",
  "key": "[email protected]",
  "ownerTaxId": "0001234567890"
}'

Modelo de retorno:

{
    "key": "[email protected]",
    "keyType": "EMAIL",
    "account": {
        "openingDate": "2014-01-22T03:00:00Z",
        "participant": "60701190",
        "branch": "**",
        "accountNumber": "****",
        "accountType": "CACC"
    },
    "owner": {
        "taxIdNumber": "05216208000166",
        "type": "LEGAL_PERSON",
        "name": "TESTE DE RAZAO SOCIAL"
    },
    "endtoendid": "E1393589320220302185301269155842",
    "isSameTaxId": false
}

Note que no retorno é apresentado no objeto account as propriedades branch(agência) e accountNumber(número da conta) de forma mascarada, além da propriedade accountType(tipo da conta), representando os dados bancários da chave que foi consultada de uma pessoa física ou empresa que irá receber a transferência. A propriedade participant representa o código da instituição financeira participante no ISPB (Instituição de Sistema de Pagamentos Brasileiros), ou seja, para onde será enviado o dinheiro.

No objeto owner será apresentado informações sobre o dono da chave, como taxindNumber(tipo do documento CPF, ou CNPJ), type(tipo de pessoa), sendo LEGAL_PERSON(pessoa jurídica) e NATURAL_PERSON(pessoa física) e name(o nome do dono). Caso o proprietário da chave seja o mesmo que o informado no campo ownerTaxId da requisição, o campo isSameTaxId (boolean) retornará o valor true. Note que caso o dono da chave seja uma pessoal física (NATURAL_PERSON) o campo taxIdNumber virá mascarado.

Por fim, mas não menos importante, é apresentado a propriedade endtoend que seria o identificador de ponta a ponta da transação de consulta que também é utilizado para transferências com QR Code.

Pagar QR Code

Após realizar a consulta da chave no DICT, deve ser realizado o pagamento do QR Code, para isso é necessário realizar uma chamada na API Iniciar pagamento Pix.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/payment' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "amount": 25.55,
    "clientCode": "145885412",
    "transactionIdentification": "testqrcodestaticcelcoin",
    "debitParty": {
        "account": "3794245",
        "branch": 30,
        "taxId": "13935893000109",
        "accountType": "CACC",
        "name": "IS2B - Integrated Solutions to Business S.A"
    },
    "creditParty": {
        "key": "[email protected]",
        "bank": "30306294",
        "accountType": "CACC",
        "name": "Fulano de Tal"
    },
    "endtoendid": "E1393589320220302185301269155842"
    "initiationType": "STATIC_QRCODE",
    "remittanceInformation": "Texto de mensagem",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH",
    "transactionType": "TRANSFER"
}'

Perceba que o pagamento de um QR Code também é uma transferência, para uma conta bancária, porém o corpo da requisição tem algumas alterações.

A propriedade amount, deve ser preenchido o valor a ser transferido, já na clientCode, deve ser utilizado um identificador único da sua aplicação.

O campo transactionIdentification deve ser preenchido com o dado retornado da consulta de decodificação do QR Code.

O objeto debitParty, deve ser preenchido com os dados da conta bolsão da Celcoin e o objeto creditParty, deve ser populado com os dados da conta que vai receber o valor, retornados na chamada Retorna as informações do DICT utilizando uma chave cadastrada no Pix, onde a propriedade participant é igual a bank, accountNumber igual a account, taxIdNumber igual a taxId.

A propriedade initiationType, deve ser populado com o valor STATIC_QRCODE, para que a Celcoin entenda que sua aplicação está executando o pagamento de um QR Code estático.

A propriedade urgency, deve ser populada com o valor HIGH para ser executada na hora.

A propriedade transactionType, deve ser populada com valor TRANSFER, pois estamos executando uma transferência de valores.

A propriedade paymentType, deve ser populada com IMMEDIATE para ser executada na hora.

A propriedade endToEndId, deve ser populada com o endToEndId da Consulta DICT (/pix/v1/dict/v2/key).

Ao realizar a chamada de payments a Celcoin irá retirar o dinheiro da sua conta bolsão e irá executar a tentativa de transferência. Caso tudo ocorra como esperado, será enviado via webhook uma notificação, porém se por algum motivo ocorrer uma falha, sua aplicação também será notificada via webhook, mas nesse cenário a Celcoin devolve o saldo retirado da conta, para ser usado em possíveis transações futuras.

Modelo de retorno:

{
    "transactionId": 9155084,
    "code": "SUCCESS",
    "slip": "     COMPROVANTE TRANSFERENCIA PIX      \n            03/03/2022 14:29            \n           TERM 11 AGENTE 999           \n                CONTROLE                \n    E1393589320220303172901514346392    \n----------------------------------------\n                PAGADOR                 \n\n                Contrato                \n            AG:1 CC:100548925           \n        CPF/CNPJ:23694719000175         \n----------------------------------------\n               RECEBEDOR                \n\n        30306294 AG:20 CC:42161         \n          CPF/CNPJ:09958359006          \n     CHAVE:[email protected]      \n----------------------------------------\n   DATA DO PAGAMENTO 03/03/2022 14:29   \n\n            VALOR R$ 25,5500            \n----------------------------------------\n              AUTENTICACAO              \nDE.79.D3.EC.7D.2E.C3.55.46.44.A6.48.4D.80.21.C5\n",
    "slipAuth": "DE.79.D3.EC.7D.2E.C3.55.46.44.A6.48.4D.80.21.C5",
    "endToEndId": "E1393589320220303172901514346392"
}

Note que será retornado o id da transação Celcoin (transactionID) e a propriedade endToEndId que seria o id fim a fim da transação Pix, recomendamos que esses campos sejam armazenados em sua aplicação, pois a Celcoin irá enviar um gatilho em seu webhook, informando se a transação ocorreu com sucesso, ou não e através desses campos é possível realizar validações em sua aplicação.

O campo code exibe se a requisição ocorreu com sucesso ou não conforme abaixo:

• SUCCESS = Pagamento realizado com sucesso;
• SUCCESSFUL_WITH_ERROR = Pagamento realizado com sucesso, porém tivemos algum erro interno na hora de gerar comprovante;
• ALREADY_PAID = Pagamento já foi realizado anteriormente (mesmo clientCode ou endToEndId);
• ALREADY_PAYD_WITH_ERROR = Pagamento já foi realizado anteriormente (mesmo clientCode ou endToEndId), porém aconteceu algum erro como geração de comprovante.

Nos casos de retornos "SUCCESS" e "SUCCESSFUL_WITH_ERROR", o webhook será disparado confirmando a transação ou o erro ocorrido.

A propriedade slip devolve o comprovante do pagamento.

🚧

Recomendamos que essas informações sejam persistidas do lado da sua aplicação, para o seu usuário confirmar se deseja realizar o pagamento.

Ele optando por realizar o pagamento deve ser realizado os processos abaixo, caso contrário basta encerrar a operação.

Recebendo status do pagamento via webhook

O webhook é uma forma de receber informações de maneira assíncrona, onde geralmente são disparados gatilhos, no formato JSON, quando um evento acontece. Após a Celcoin realizar a tentativa de transferência do valor para instituição bancária solicitada, ela irá disparar um gatilho (PAYMENT), no webhook de seu aplicativo, ou sistema, configurado pelo nosso time de suporte.

❗

Para realizar a configuração de um webhook é necessário entrar em contato com a nossa equipe de suporte informando a url de seu webhook, senha e usuário, no formato BASIC, desta forma eles irão realizar o cadastro em nossa plataforma, para que seja possível o envio dos gatilhos.

Uma vez que a propriedade RequestBody.StatusCode.StatusId for igual a 2, seu usuário final pode ser notificado que a transferência ocorreu com sucesso, qualquer coisa diferente de 2, deve ser validado o retorno, tratado e apresentado ao usuário, criamos uma tabela que mostra quais são os possíveis retornos que podemos apresentar, para acessar basta clicar nesse link.

Para realizar testes em sandbox e receber o webhook de PAYMENTS com status igual 2(sucesso), deve ser utilizado o payload informado no começo do artigo.

Caso você queira simular o pagamento com status rejeitado, basta alterar o payload alterando o objeto creditParty da seguinte forma:

"creditParty": {
        "bank": "30306294",
        "account": "10545584",
        "branch": 0,
        "taxId": "11122233344",
        "accountType": "CACC",
        "name": "Celcoin"
    }

Exemplo de aplicação

Criamos o protótipo de um aplicativo para exemplificar a utilização da API: