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.

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.

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 --request POST '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-raw '{
  "clientRequestId": "string",
  "key": "string",
  "amount": decimal,
  "payerCPF": "srting",
  "payerCNPJ": "string",
  "payerQuestion": "string",
  "payerName": "string",
  "expiration": 86400,
  "merchant": {
    "postalCode": "string",
    "city": "string",
    "merchantCategoryCode": decimal,
    "name": "Celcoin"
  },
  "additionalInformation": "string"
}}'

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.

Modelo de retorno:

{
  "version": "1.0.0",
  "status": 200,
  "body": {
    "clientRequestId": "a20413ac-b053-45a1-9ba3-2d6d8a56bfc0",
    "pactualId": "a20413ac-b053-45a1-9ba3-2d6d8a56bfc0",
    "transactionId": "a20413ac-b053-45a1-9ba3-2d6d8a56bfc0",
    "createTimestamp": "2020-10-16T23:56:00",
    "lastUpdateTimestamp": "2020-10-16T23:56:00",
    "entity": "DynamicBRCode",
    "status": "200",
    "tags": [
      "string"
    ],
    "transactionIdentification": "a20413ac-b053-45a1-9ba3-2d6d8a56bfc0",
    "body": {
      "key": "a20413ac-b053-45a1-9ba3-2d6d8a56bfc0",
      "revision": "02",
      "location": "api.dev.developer.celcoin.com/v1/07071e551d224008baabfc54b7a4a5ab",
      "debtor": {
        "name": "Fulano de Tal",
        "cpf": "11122233366",
        "cnpj": "1112223300100"
      },
      "amount": {
        "original": 10.25
      },
      "calendar": {
        "expiration": 84600,
        "dueDate": "2023-10-16T23:56:00"
      },
      "dynamicBRCodeData": {
        "pointOfInitiationMethod": "12",
        "payloadFormatIndicator": "01",
        "countryCode": "BR",
        "merchantName": "Celcoin Pagamentos",
        "merchantCity": "Barueri",
        "transactionIdentification": "699264bdd47d4a5cb35234974dd5a634",
        "transactionAmount": "10.25",
        "emvqrcps": "00020101021226940014br.gov.bcb.pix2572api.dev.developer.btgpactual.com/v1/q/d/07071e551d224008baabfc54b7a4a5ab520400005303986540510.555802BR5912Merchant S/A6014Rio de Janeiro62360532699264bdd47d4a5cb35234974dd5a63463046839",
        "merchantCategoryCode": 0,
        "transactionCurrency": 986,
        "merchantAccountInformation": {
          "url": "https://api.dev.developer.celcoin.com/v1/07071e551d224008baabfc54b7a4a5ab"
        }
      },
      "additionalInformation": [
        {
          "value": "Assinatura de serviço",
          "key": "Produto 1"
        }
      ]
    }
  }
}

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.

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 apenas o recebimento do webhook para o Cash-out, o webhook para o Cash-in ainda não está disponível neste ambiente. Em produção será possível testar o webhook normalmente, basta cadastrá-lo.

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:

🚧

Em ambiente de sandbox não é disparado o gatilho (RECEIVEPIX). Para recebê-lo, é necessário executar os testes em ambiente produtivo, gerando um QR Code dinâmico imediato e efetuando o seu pagamento em um aplicativo outra instituição financeira. Desta forma, a Celcoin irá identificar que o pagamento ocorreu com sucesso e disparar o gatilho.