Pagamento de um QR Code (estático ou dinâmico)

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 habilitada - caso queira contratar a funcionalidade, 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 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.

Decodificar 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 Codes 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.pix2571api-h.developer.celcoin.com.br/v1/p/v2/0223b7626a7247e58a35cfadb1c18ba85204000053039865802BR5907Celcoin6007Barueri61080120100562070503***6304CB07"
}'

Modelo de retorno:

{
    "type": "2",
    "collection": "1",
    "payloadFormatIndicator": "01",
    "merchantAccountInformation": {
  
}

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), fora isso, a propriedade collection determina se ele é immediate (imediato, representando pelo 1) ou duedate (com data de vencimento definida, representando pelo 2), é importante saber qual é o tipo e a collection do qrcode, pois isso irá definir como seguir com as integrações para a execução do pagamento.

Estrutura dos dados retornados:

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

🚧

Recomendamos que seja armazenado temporariamente, ou em sua aplicação a propriedade url do objeto merchantAccountInformation, pois o seu valor será utilizado em requisições futuras para executar o pagamento do QR Code.

Caso você não tenha um EMV de um QR Code dinâmico immediate, para realizar os testes, basta criar um QR Code dinâmico ou estático, conforme nossos roteiros.

📘

É importante ser usado a chave [email protected] em ambiente sandbox para conseguir finalizar seus testes, caso contrário será apresentado erro na hora de realizar a consulta da chave DICT.

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

Pagamento do QR Code dinâmico

Após realizar a consulta do EMV, 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",

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 dado retornadado no campo txid da API de consulta do payload, seja imediate, ou duedate.

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, taxId igual a taxindNumber.

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

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 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": 9162909,
    "code": "SUCCESS",
    "slip": "     COMPROVANTE TRANSFERENCIA PIX      \n            07/03/2022 09:58            \n           TERM 11 AGENTE 999           \n                CONTROLE                \n    E1393589320220307125800721814129    \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 07/03/2022 09:58   \n\n            VALOR R$ 25,5500            \n----------------------------------------\n              AUTENTICACAO              \n21.F8.55.97.74.6C.A7.3F.11.80.AA.21.CE.62.23.12\n",
    "slipAuth": "21.F8.55.97.74.6C.A7.3F.11.80.AA.21.CE.62.23.12",
    "endToEndId": "E1393589320220307125800721814129"
}

Note que será retornado o id da transação Celcoin (transactionID) e o endToEndId que seria o id da transação Pix fim a fim, esses campos devem ser 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 com eles é 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 dos pagamentos 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: