Cobrança imediata com QR Code dinâmico (immediate)

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.
Ter uma chave Pix cadastrada - caso sua empresa não tenha, basta entrar em contato com o nosso suporte, solicitando a criação. Não realizamos o cadastro de chaves do tipo: CNPJ, e-mail, ou telefone, devido a possibilidade de fraudes.

❗
Para possibilitar o recebimento do QR Code, você deve usar a chave acima vinculada a sua credencial.

Por que usar um QR Code de cobrança imediata (immediate)?

Pode receber APENAS UM pagamento;
Além do valor, permite a inserção de mais informações, como tempo de expiração e dados do devedor;
Conciliação via identificador, possibilitando associar a transação Pix à cobrança correlata;
Em sua estrutura interna, é configurada uma URL que é acessada no momento de sua leitura. Assim, as informações trazidas pela URL podem variar em função de diversos parâmetros;
O QR Code dinâmico contém somente as informações básicas do usuário recebedor. As demais estão em um webservice da instituição do recebedor, com base nessa URL.

Essa funcionalidade deve ser utilizada para realizar a criação de um QR Code de cobrança imediata. Desta forma, o caso de uso poderia ser:

Como fintech, quero disponibilizar aos meus usuários, a possibilidade de cobrar de forma imediata através de sua chave Pix, onde ele deverá apenas preencher o valor da operação e será apresentado um QR Code e seu código "Pix Copia e Cola" para pagamento da cobrança.

Existem duas opções de fluxo para a criação de uma cobrança QRCode imediata, sendo elas:

Em duas etapas confirme o fluxograma anterior (Criação do location + Criação da Cobrança)
Em uma unica chamada, onde realizaremos internamente e criação do Location e a vinculação com a cobrança imediata (Dynamic).

Criando um QR Code

Para criar uma nova cobrança, é necessário gerar um QR Code e atrelar a ele os dados da cobrança que deseja executar, desta forma, o primeiro passo seria criar um QR Code, utilizando a API Criar um QR Code (Location).

Modelo de request:

curl --location 'https://sandbox.openfinance.celcoin.dev/pix/v1/location' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "clientRequestId": "ed66c35f-65d7-4a5f-8ebe-9b7eb7f2e6e3",
  "type": "COB",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": "0000", 
    "name": "Celcoin Pagamento"
  }
}'

Perceba que, no campo type, deve ser preenchido o valor COB e que o objeto merchant, precisa ser preenchido com o CEP, cidade e nome da sua empresa. A propriedade merchantCategoryCode, pode ser preenchida com valor 0000.

Regras do campo Amount

Para transferências: Os objetos withdrawal e change não devem ser preenchidos

Para saque: O objeto "withdrawal" deve ser preenchido e o campo 'amount.original' deve ser 0.

Para troco: O objeto 'change' não deve ser preenchido

Os objetos withdrawal e change não podem ser preenchidos simultaneamente

Modelo de retorno:

{
    "locationId": 4000178749,
    "status": "CREATED",
    "clientRequestId": "ed66c35f-65d7-4a5f-8ebe-9b7eb7f2e6e3",
    "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/cc6f977be3892de5460247e979f261",
    "emv": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/pixqrcode/v2/cc6f977be3892de5460247e979f2615204000053039865802BR5918Celcoin Pagamentos6007Barueri62070503***63041400",
    "type": "COB",
    "merchant": {
        "postalCode": "01201005",
        "city": "Barueri",
        "merchantCategoryCode": "0000",
        "name": "Celcoin Pagamentos"
    }
}

Se a sua requisição for recebida com sucesso, o retorno da propriedade status será CREATED.

Sugerimos que seja armazenado em sua aplicação o locationId (código do QR Code), EMV, pois você precisará desses valores para as próximas requisições.

Criando uma cobrança Pix imediata

Em seguida, deve ser realizada a requisição na API Criar cobrança imediata, para vincular o QR Code criado na requisição de location, a uma cobrança imediata Pix.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/immediate' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
    "clientRequestId": "14232341231",
    "payerQuestion": "Não pagável após vencimento.",
    "key": "[email protected]",
    "locationId": 12730559,
    "debtor": {
        "name": "Fulano de Tal",
        "cnpj": "33188542046"
    },
    "amount": {
        "original": 15.00,
        "changeType": 0
    },
    "calendar": {
        "expiration": 86400
    },
    "additionalInformation": [
        {
            "value": "Assinatura de serviço",
            "key": "Produto 1"
        }
    ]
}'

A propriedade clientRequestId deve ser populada com um id único, fornecido por sua aplicação.

Dentro do objeto debtor, deve ser informado o nome e CPF/CNPJ de quem irá pagar os valores.

A propriedade key, deve ser preenchida com a chave Pix do usuário recebedor, ou seja a chave Pix da sua conta Celcoin, essa chave é gerada pela nossa equipe de suporte, uma vez que você tem sua conta homologada. No exemplo acima, utilizamos a chave "[email protected]"

Dentro do objeto amount, deve ser informado o valor da cobrança e, por último, o objeto calendar deve ser populado com a data de expiração do QR Code. É importante ressaltar que todo QR Code dinâmico tem um tempo determinado para expirar. Caso esta data não seja informada na criação, será assumida a duração de 86400 segundos, que corresponde a 24 horas.

Modelo de retorno:

{
  "revision": 9267254,
  "transactionId": 9267254,
  "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
  "status": "ACTIVE",
  "lastUpdate": "2021-04-29",
  "payerQuestion": "Esta cobrança é referente a...",
  "additionalInformation": [
    {
      "value": "Assinatura de serviço",
      "key": "Produto 1"
    }
  ],
  "debtor": {
    "name": "Fulano de Tal",
    "cpf": "11122233366",
    "cnpj": "1112223300100"
  },
  "amount": {
    "original": 0,
    "changeType": 0,
    "withdrawal": {
      "vldnAmount": 10,
      "agentMode": "AGTEC",
      "withdrawalServiceProvider": "13935893",
      "changeType": 0
    },
    "change": {
      "vldnAmount": 10,
      "vlcpAmount": 15.55,
      "agentMode": "AGTEC",
      "withdrawalServiceProvider": "13935893",
      "changeType": 0
    }
  },
  "location": {
    "merchant": {
      "postalCode": "01201005",
      "city": "Barueri",
      "merchantCategoryCode": "0000",
      "name": "Celcoin Pagamentos"
    },
    "url": "string",
    "emv": "string",
    "type": "string",
    "locationId": "string",
    "id": "string"
  },
  "key": "5d000ece-b3f0-47b3-8bdd-c183e8875862",
  "calendar": {
    "expiration": 86400
  },
  "createAt": "2021-04-29",
  "transactionIdentification": "kk6g232xel65a0daee4dd13kk479195205"
}

Sugerimos que seja armazenada, em sua aplicação, as propriedades transactionId e transactionIdentification, para conseguir receber da Celcoin o status da cobrança via webhook, createAt e expiration, para avaliar se o QR Code ainda é válido.

O campo Revision indica quantas revisões ocorreram no QR Code e campo Status, informa o status atual da cobrança imediata, podendo ser:

"ACTIVE": ativo, mas ainda não teve pagamento;
"CONCLUDED": quando o pagamento já ocorreu;
"DELETED_BY_RECEIVING_USER": deletado por solicitação do usuário final;
"DELETED_BY_PSP": deletado por solicitação do participante do Pix.

Consulta de status de uma cobrança Pix imediata (Immediate)

É possivel consultar o status de uma cobrança imediata (Immediate) através do endpoint Buscar dados de uma cobrança dinâmica. Esta chamada é indicada apenas para o fluxo de exceções, principalmente após o gatilho webhook apresentado ao fim desta página.

🚧
A seguir o fluxo alternativo resumido (Dynamic):

Criando uma cobrança Pix imediata (Dynamic)

Esta chamada resume as duas chamadas anteriores em uma unica requisição Dynamic da mesma forma criando uma cobrança imediata Pix.

Modelo de request:

curl --location 'https://sandbox.openfinance.celcoin.dev/pix/v1/brcode/dynamic' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "key": "[email protected]",
  "amount": "10.00",
  "merchant": {
    "merchantCategoryCode": "5651",
    "postalCode": "06519435",
    "city": "barueri",
    "name": "Teste Celcoin"
  },
  "debtor": {
    "name": "Fulano de Tal",
    "cnpj": "33188542046"
  },
  "expiration": 30000,
  "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52208",
  "payerName": "Teste Celcoin",
  "payerCPF": "13935893000370",
  "payerQuestion": "Criacao do QRCode immediate teste"
}'

A propriedade clientRequestId deve ser populada com um id único, fornecido por sua aplicação.

Dentro do objeto debtor, deve ser informado o nome e CPF/CNPJ de quem irá pagar os valores.

A propriedade key, deve ser preenchido com a chave Pix cadastrada na conta BaaS para a qual você deseja receber a cobrança. No exemplo acima, utilizamos a chave ""

Modelo de retorno:

{
    "version": "1.0.0",
    "status": 201,
    "body": {
        "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52208",
        "pactualId": null,
        "transactionId": "4000095510",
        "createTimestamp": "2024-09-04T02:05:42.5489802Z",
        "lastUpdateTimestamp": "0001-01-01T00:00:00",
        "entity": "DynamicBRCode",
        "status": "ACTIVE",
        "tags": null,
        "transactionIdentification": "kk6g232xel65a0daee4dd13kk4000095510",
        "body": {
            "key": "[email protected]",
            "revision": "0",
            "location": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/69e2bd66eecb47dfc632a5c7fcbcac",
            "debtor": {
                "name": "Teste Celcoin",
                "cpf": "13935893000370",
                "cnpj": null
            },
            "amount": {
                "original": 10.00
            },
            "calendar": {
                "expiration": 30000,
                "dueDate": "2024-09-04T07:25:42.5489826"
            },
            "dynamicBRCodeData": {
                "pointOfInitiationMethod": "12",
                "payloadFormatIndicator": "01",
                "countryCode": "BR",
                "merchantName": "Teste Celcoin",
                "merchantCity": "barueri",
                "transactionIdentification": "***",
                "transactionAmount": "10.00",
                "emvqrcps": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/pixqrcode/v2/69e2bd66eecb47dfc632a5c7fcbcac5204000053039865802BR5913Teste Celcoin6007barueri62070503***63045967",
                "merchantCategoryCode": 5651,
                "transactionCurrency": 986,
                "merchantAccountInformation": {
                    "url": "qrcode-h.pix.celcoin.com.br/pixqrcode/v2/69e2bd66eecb47dfc632a5c7fcbcac"
                }
            },
            "additionalInformation": null
        }
    }
}

O campo Revision indica quantas revisões ocorreram no QR Code e campo Status, informa o status atual da cobrança imediata, podendo ser:

"ACTIVE": ativo, mas ainda não teve pagamento;
"CONCLUDED": quando o pagamento já ocorreu;
"DELETED_BY_RECEIVING_USER": deletado por solicitação do usuário final;
"DELETED_BY_PSP": deletado por solicitação do participante do Pix.

Consulta de status de uma cobrança Pix imediata (Dynamic)

É possivel consultar o status de uma cobrança imediata (Dynamic) através do endpoint Buscar dados de uma cobrança dinâmica. Esta chamada é indicada apenas para o fluxo de exceções, principalmente após o gatilho webhook a seguir.

Recebendo o status da cobrança com gatilho

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. Caso o pagamento ocorra com sucesso, a Celcoin dispara um gatilho (RECEIVEPIX) em seu webhook.

❗
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.
No ambiente Sandbox é possível testar o recebimento do webhook para o Cash-out e o webhook para o Cash-in.

Modelo de webhook RECEIVEPIX:

{
    "RequestBody": {
        "TransactionType": "RECEIVEPIX",
        "TransactionId": 56762766,
        "Amount": 150.55,
        "DebitParty": {
            "Account": "416781236",
            "Bank": "18236120",
            "Branch": "1",
            "PersonType": "NATURAL_PERSON",
            "TaxId": "33188542046",
            "AccountType": "CACC",
            "Name": "Fulano de Tal"
        },
        "CreditParty": {
            "Bank": "13935893",
            "Branch": "1",
            "Account": "123456789",
            "PersonType": "NATURAL_PERSON",
            "TaxId": "09876543210",
            "AccountType": "CACC",
            "Name": "Cicrano de Outro",
            "Key": "8ea152b1-ddee-ssaa-aass-ce98245349aa"
        },
        "EndToEndId": "E18236120202001199999s0149012FPC",
        "transactionIdentification": "kk6g232xel65a0daee4dd13kk54578675",
        "transactionIdBRCode": "54578675"
    }
}

No webhook (RECEIVEPIX ) retornarmos o campo transactionIdBrCode que se refere ao transactionid do QR Code gerado e o transactionIdentification. Ambos podem ser utilizados para validar o pagamento do QR Code.

❗️
É muito importante que o parceiro realize a validação entre o valor da cobrança e o valor informado no campo "Amount" do webhook de recebimento, com intuito de conciliar o montante esperado com o que efetivamente foi pago e evitar possíveis prejuízos.

Exemplo de aplicação

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

Pré-requisitos para implementação

❗

Por que usar um QR Code de cobrança imediata (immediate)?

Criando um QR Code

Regras do campo Amount

Criando uma cobrança Pix imediata

Consulta de status de uma cobrança Pix imediata (Immediate)

🚧A seguir o fluxo alternativo resumido (Dynamic):

Criando uma cobrança Pix imediata (Dynamic)

Consulta de status de uma cobrança Pix imediata (Dynamic)

Recebendo o status da cobrança com gatilho

❗

❗️

Exemplo de aplicação

🚧
A seguir o fluxo alternativo resumido (Dynamic):