DocumentaçãoAPIStatus PageSuporteCelcoin Corp

Cobrança imediata com QR code dinâmico

Suggest Edits

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.

  • Ter uma chave Pix cadastrada - caso sua empresa não tenha, basta entrar em contato com o nosso suporte,solicitando esse cadastro. Não realizamos o cadastro de chaves do tipo: CNPJ, e-mail, ou telefone devido a possibilidade de fraudes.

Essa funcionalidade deve ser utilizada para realizar a criação de um QR code de cobrança imediata com, ou sem valor definido. 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 Qrcode, utilizando a API Criar um Qrcode (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, precisa ser preenchido com o CEP, cidade e nome da sua empresa. 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": "14232341231",
    "payerQuestion": "Não pagável após vencimento.",
    "key": "[email protected]",
    "locationId": 12730559,
    "debtor": {
        "name": "Fulano de Tal",
       // "cpf": "11122233366",
        "cnpj": "71609694000107"
    },
    "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.

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": "14232341231",
    "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": "71609694000107"
    },
    "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": "testqrcodestaticcelcoin",
    "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.

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

Caso o pagamento ocorra com sucesso, a Celcoin dispara um gatilho (RECEIVEPIX) em seu webhook.

Modelo de webhook RECEIVEPIX: 

{
    "RequestBody": {
        "TransactionType": "RECEIVEPIX",
        "TransactionId": 56762766,
        "Amount": 150.55,
        "DebitParty": {
            "Account": "416781236",
            "Bank": "18236120",
            "Branch": "1",
            "PersonType": "NATURAL_PERSON",
            "TaxId": "01234567890",
            "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 QRCode gerado e o transactionIdentification. Ambos podem ser utilizados para validar o pagamento do QRCode.

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.

Updated about 2 months ago

Did this page help you?