Pagamento de um Qrcode 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 Qrcode Pix estático.

Por que usar um Qrcode 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 QRcodes 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 Qrcode.

Decodificando Qr code

Para iniciar o processo de pagamento de um Qrcode é necessário realizar sua leitura, portanto, é preciso decodificar ele, onde é gerado um código EMV (padrão criado para leitura de qrcodes pix no Brasil, nos sistemas financeiros geralmente é nomeado de pix copia e cola). Para isso, basta utilizar API Retorna as informações do QRCode 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": "[email protected]ente 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 Qrcode, 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 Qrcodes estáticos. No caso de Qrcodes 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.

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

Abaixo deixo um modelo de request para criar o Qrcode:

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 Qrcode é 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": "11223344556",
  "key": "[email protected]"
}'

Modelo de retorno:

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

Note que no retorno é apresentado no objeto account nas propriedades branch(agência), accountNumber(número da conta), accountType(tipo da conta), os dados bancários da chave que foi consultada, no caso 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).

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

Pagar Qr code

Após realizar a consulta da chave no DICT, deve ser realizado o pagamento do Qrcode, 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",
        "account": "42161",
        "branch": 20,
        "taxId": "07693440704",
        "accountType": "CACC",
        "name": "Celcoin"
    },
    "initiationType": "STATIC_QRCODE",
    "remittanceInformation": "Texto de mensagem",
    "paymentType": "IMMEDIATE",
    "urgency": "HIGH",
    "transactionType": "TRANSFER"
}'

Perceba que o pagamento de um Qrcode 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 Qrcode 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.

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:07693440704          \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. 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

Para conseguir receber da Celcoin os status das transferências, pagamentos e cobranças, deve ser realizada a configuração de um webhook.

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.

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

Did this page help you?