Receber um Pix Cash-in por QR Code dinâmico (immediate)

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.

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.

Fluxo de integração

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 --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": "9b26edb7cf254db09f5449c94bf13abc",
  "type": "COB",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": "0000", 
    "name": "Celcoin Pagamentos"
  }
}'

Perceba que, no campo type, deve ser preenchido o valor COB e que o objeto merchant, você deve preencher os dados do recebedor, que incluem postalCode (CEP), city (cidade) e name (nome do recebedor). A propriedade merchantCategoryCode, pode ser preenchida com valor 0000.

Modelo de retorno:

{
    "status": "CREATED",
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "merchant": {
        "postalCode": "01201005",
        "city": "Barueri",
        "merchantCategoryCode": "0000",
        "name": "Celcoin Pagamentos"
    },
    "url": "api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f924",
    "emv": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f9245204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***63042570",
    "type": "COB",
    "locationId": 12730559
}

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": "e3434da1-b37e-43cd-97a9-df4d80d52207",
    "payerQuestion": "Não pagável após vencimento.",
    "key": "testepix@celcoin.com.br",
    "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 preenchido com a chave Pix cadastrada na conta BaaS para a qual você deseja receber a cobrança. No exemplo acima, utilizamos a chave "testepix@celcoin.com.br"

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": 0,
    "transactionId": 9163565,
    "clientRequestId": "e3434da1-b37e-43cd-97a9-df4d80d52207",
    "status": "ACTIVE",
    "lastUpdate": "2022-03-07T18:02:09.8646387+00:00",
    "payerQuestion": "Não pagável após vencimento.",
    "additionalInformation": [
        {
            "value": "Assinatura de serviço",
            "key": "Produto 1"
        }
    ],
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": null,
        "cnpj": "33188542046"
    },
    "amount": {
        "original": 15.00,
        "changeType": 0,
        "withdrawal": null,
        "change": null
    },
    "location": {
        "merchant": {
            "postalCode": "01201005",
            "city": "Barueri",
            "merchantCategoryCode": "0000",
            "name": "Celcoin Pagamentos"
        },
        "url": "api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f924",
        "emv": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/v1/p/v2/7af2f80f6c0c4442b486de15d5a5f9245204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***63042570",
        "type": "COB",
        "locationId": 12730559,
        "id": null
    },
    "key": "testepix@celcoin.com.br",
    "calendar": {
        "expiration": 86400
    },
    "createAt": "2022-03-07T18:02:09.8646387+00:00",
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk9163565"
}

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.

🚧
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": "testepix@celcoin.com.br",
  "amount": "10.00",
  "merchant": {
    "merchantCategoryCode": "5651",
    "postalCode": "06519435",
    "city": "barueri",
    "name": "Teste Celcoin"
  },
  "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": "testepix@celcoin.com.br",
            "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.

Recebendo notificações automáticas (Webhook)

Oferecemos a opção de configurar webhooks para receber notificações automáticas sempre que um pagamento via Pix Cash-in for recebido. Esses webhooks são um meio eficiente de receber atualizações em tempo real sobre as transações realizadas.

Para mais informações sobre a configuração e utilização dos webhooks, consulte a documentação específica disponível.

Evento: pix-payment-in

Link Documentação: Modelos de Webhooks do BaaS

Em caso de dúvidas adicionais, nossa equipe de suporte estará disponível para ajudar.

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

Fluxo de integração

Criando um QR Code

Criando uma cobrança Pix imediata

🚧A seguir o fluxo alternativo resumido (Dynamic):

Criando uma cobrança Pix imediata (Dynamic)

Recebendo notificações automáticas (Webhook)

🚧
A seguir o fluxo alternativo resumido (Dynamic):