Cobrança com vencimento Qr code dinâmico

Criar uma cobrança Pix única, com data de vencimento e expiração, e opção de aplicar multas, juros, descontos e/ou abatimentos

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 com valor e data de vencimento definidos, com possibilidade de aplicação de juros, multa, abatimento e descontos. Desta forma, o caso de uso poderia ser:

Como fintech, quero disponibilizar aos meus usuários a possibilidade de criar uma cobrança que aceite pagamento após a data de vencimento, onde ele preenche o valor, multa, juros e desconto para pagamento antecipado. E, então, será apresentado um QR code e seu código "Pix Copia e Cola" para pagamento da cobrança.

Criando QR code (location)

Para criar uma nova cobrança, é necessário a gerar um QR code e atrelar a ele os dados da cobrança que deseja executar. Desta forma, o primeiro passo seria criar um BR Code location, 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": "COBV",
  "merchant": {
    "postalCode": "01201005",
    "city": "Barueri",
    "merchantCategoryCode": "0000",
    "name": "Celcoin Pagamentos"
  }
}'

Perceba que o campo type, deve ser preenchido com o valor COBV (cobrança com vencimento) e que o objeto merchant, precisa ser preenchido com CEP, cidade e nome da sua empresa. A propriedade merchantCategoryCode é um número de quatro dígitos, listado na ISO 18245. Caso não a utilize, deve ser preenchida com 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/cobv/02277860a77a48009ac99c6678a304c8",
    "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/v1/p/v2/cobv/02277860a77a48009ac99c6678a304c85204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***63048BE5",
    "type": "COBV",
    "locationId": 12730563
}

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 cobrança com vencimento

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

Para esta chamada é obrigatório preencher alguns campos:
clientRequestId - identificador único da sua aplicação para esse QR code;
expirationAfterPayment - define a quantidade de dias, após o vencimento, até a expiração da cobrança;
debtor - esse objeto deve ser populado com os dados do pagador da cobrança, informando as propriedades name, cnpj, cpf, postalCode, city e e-mail;
receiver - esse objeto deve ser populado com os dados de quem irá receber o pagamento, informando as propriedades, name ou fantasyName, cnpj ou cpf, postalCode, city e e-mail;
locationId - esse id é gerado na chamada de Criar um BRCode (location);
amount - valor original da cobrança; e
key - chave Pix da sua conta celcoin, essa chave é gerada pela nossa equipe de suporte, uma vez que você tem sua conta homologada.

Essa API possibilita a criação de cobranças com descontos, abatimentos, multas e juros. Abaixo vou explicar como aplicar essas configurações dentro da requisição.

Desconto


Para configurar um desconto, é necessário definir a propriedade hasDiscount como true e definir qual será a modalidade do desconto na propriedade modality, que pode ser preenchida com as seguintes opções:

Valor

Descrição

FIXED_VALUE_UNTIL_THE_DATES_INFORMED

Valor fixo até a data informada

PERCENTAGE_DATE_REPORTED

Percentual até a data informada

AMOUNT_PER_CALENDAR_DAY_ADVANCE

Valor por dia corrido de antecipação

AMOUNT_ADVANCE_BUSINESS_DAY

Valor por dia útil de antecipação

PERCENTAGE_ADVANCE_CURRENT_DAY

Percentual por dia corrido de antecipação

PERCENTAGE_ADVANCE_BUSINESS_DAY

Percentual por dia útil de antecipação

Além disso, é necessário popular o array discountDateFixed com até 3 objetos amountDicount, onde é preciso informar duas propriedades: date (data da aplicação do desconto no formato yyyy-mm-dd) e amountPerc (valor ou porcentagem que será descontada do valor original, conforme a modalidade).

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/duedate' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
  "expirationAfterPayment": 10,
  "duedate": "2022-03-15 00:00:00",
  "debtor": {
    "name": "Fulano de Tal",
    "cnpj": "61360961000100",
    "city": "Barueri",
    "publicArea": "Avenida Brasil",
    "state": "SP",
    "postalCode": "01202003",
    "email": "[email protected]"
  },
  "receiver": {
    "name": "João da Silva",
    "cnpj": "60904237000129",
    "postalCode": "01202003",
    "city": "Barueri",
    "publicArea": "Avenida Brasil",
    "state": "SP",
    "fantasyName": "Nome de Comercial"
  },
  "locationId": 12730587,
  "amount": 15.63,
  "amountDicount": {
    "discountDateFixed": [
      {
        "date": "2022-03-10",
        "amountPerc": "1.00"
      }
    ],
    "hasDicount": true,
    "modality": "FIXED_VALUE_UNTIL_THE_DATES_INFORMED"
  },
  "key": "[email protected]"
}'

Modelo de retorno:

{
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk9165237",
    "transactionId": 9165237,
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "status": "ACTIVE",
    "lastUpdate": "2022-03-08T16:47:17.2473478+00:00",
    "payerQuestion": null,
    "additionalInformation": null,
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": null,
        "cnpj": "61360961000100"
    },
    "amount": {
        "original": 15.63,
        "discount": {
            "discountDateFixed": [
                {
                    "date": "2022-03-10T00:00:00",
                    "amountPerc": "1.00"
                }
            ],
            "modality": "FIXED_VALUE_UNTIL_THE_DATES_INFORMED"
        },
        "abatement": null,
        "fine": null,
        "interest": null
    },
    "location": {
        "merchant": {
            "postalCode": "01201005",
            "city": "Barueri",
            "merchantCategoryCode": "0000",
            "name": "Celcoin Pagamentos"
        },
        "url": "api-h.developer.btgpactual.com/v1/p/v2/cobv/ae8c45d5684d4692880781d3eaf84d46",
        "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/v1/p/v2/cobv/ae8c45d5684d4692880781d3eaf84d465204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***63043B3B",
        "type": "COBV",
        "locationId": "12730587",
        "id": null
    },
    "key": "[email protected]",
    "receiver": {
        "name": "João da Silva",
        "fantasyName": "Nome de Comercial",
        "cpf": null,
        "cnpj": "60904237000129"
    },
    "calendar": {
        "expirationAfterPayment": "10",
        "createdAt": "0001-01-01T00:00:00",
        "dueDate": "2022-03-15T00:00:00"
    },
    "createAt": "2022-03-08T16:47:17.2473478+00:00"
}

Abatimento

O abatimento é uma dedução no valor original da cobrança, informado pelo recebedor.

Para aplicar um abatimento, é necessário popular o objeto amountAbatement, definindo a propriedade hasAbatement (informa se haverá ou não dedução) como true ,e informar qual será a modalidade do abatimento na propriedade modality, que pode assumir FIXED_VALUE (valor fixo) ou PERCENT (percentual). O total do abatimento deverá ser informado em amountPerc (valor ou percentual de abatimento, conforme a modalidade escolhida).

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/duedate' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "expirationAfterPayment": 10,
    "duedate": "2022-04-29 00:00:00",
    "debtor": {
        "name": "Fulano de Tal",
        "cnpj": "61360961000100",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "postalCode": "01202003",
        "email": "[email protected]"
    },
    "receiver": {
        "name": "João da Silva",
        "cnpj": "60904237000129",
        "postalCode": "01202003",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "fantasyName": "Nome de Comercial"
    },
    "locationId": 12730590,
    "amount": 15.63,
    "amountAbatement": {
        "hasAbatement": true,
        "amountPerc": "5.00",
        "modality": "FIXED_VALUE"
    },
    "key": "[email protected]"
}'

Modelo de response:

{
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk9165344",
    "transactionId": 9165344,
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "status": "ACTIVE",
    "lastUpdate": "2022-03-08T17:48:56.6383606+00:00",
    "payerQuestion": null,
    "additionalInformation": null,
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": null,
        "cnpj": "61360961000100"
    },
    "amount": {
        "original": 15.63,
        "discount": null,
        "abatement": {
            "amountPerc": "5.00",
            "modality": "FIXED_VALUE"
        },
        "fine": null,
        "interest": null
    },
    "location": {
        "merchant": {
            "postalCode": "01201005",
            "city": "Barueri",
            "merchantCategoryCode": "0000",
            "name": "Celcoin Pagamentos"
        },
        "url": "api-h.developer.btgpactual.com/v1/p/v2/cobv/e81099f4e9844fa1bae0785a3503a88b",
        "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/v1/p/v2/cobv/e81099f4e9844fa1bae0785a3503a88b5204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***6304604C",
        "type": "COBV",
        "locationId": "12730590",
        "id": null
    },
    "key": "[email protected]",
    "receiver": {
        "name": "João da Silva",
        "fantasyName": "Nome de Comercial",
        "cpf": null,
        "cnpj": "60904237000129"
    },
    "calendar": {
        "expirationAfterPayment": "10",
        "createdAt": "0001-01-01T00:00:00",
        "dueDate": "2022-04-29T00:00:00"
    },
    "createAt": "2022-03-08T17:48:56.6383606+00:00"
}

Multa

A multa é um acréscimo no valor da cobrança, uma vez que a data do pagamento não foi atendida, ou seja, se o vencimento da fatura for no dia 09/03/2025 e ocorrer a tentativa de pagamento dias depois dessa data, será aplicada uma multa ao valor da cobrança. Esse valor pode ser um percentual do valor total ou um valor fixo.

Para atrelar a multa a um QR code, é necessário preencher o objeto amountFine, definindo a propriedade hasFine, igual a true, indicando que, após a data de vencimento, será aplicada uma multa para esta cobrança.

O campo amountPerc, deve ser preenchido com o valor ou percentual da multa e, a propriedade modality , com a modalidade FIXED_VALUE (valor fixo) ou PERCENT (percentual).

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/duedate' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "expirationAfterPayment": 10,
    "duedate": "2022-04-29 00:00:00",
    "debtor": {
        "name": "Fulano de Tal",
        "cnpj": "61360961000100",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "postalCode": "01202003",
        "email": "[email protected]"
    },
    "receiver": {
        "name": "João da Silva",
        "cnpj": "60904237000129",
        "postalCode": "01202003",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "fantasyName": "Nome de Comercial"
    },
    "locationId": 12730609,
    "amount": 15.63,
    "amountFine": {
        "hasFine": true,
        "amountPerc": "5.00",
        "modality": "FIXED_VALUE"
    },
    "key": "[email protected]"
}'

Modelo de retorno:

{
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk9166775",
    "transactionId": 9166775,
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "status": "ACTIVE",
    "lastUpdate": "2022-03-09T14:08:12.3807504+00:00",
    "payerQuestion": null,
    "additionalInformation": null,
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": null,
        "cnpj": "61360961000100"
    },
    "amount": {
        "original": 15.63,
        "discount": null,
        "abatement": null,
        "fine": {
            "amountPerc": "5.00",
            "modality": "FIXED_VALUE"
        },
        "interest": null
    },
    "location": {
        "merchant": {
            "postalCode": "01201005",
            "city": "Barueri",
            "merchantCategoryCode": "0000",
            "name": "Celcoin Pagamentos"
        },
        "url": "api-h.developer.btgpactual.com/v1/p/v2/cobv/d93a2125388049c5a434ec26f531717d",
        "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/v1/p/v2/cobv/d93a2125388049c5a434ec26f531717d5204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***6304278C",
        "type": "COBV",
        "locationId": "12730609",
        "id": null
    },
    "key": "[email protected]",
    "receiver": {
        "name": "João da Silva",
        "fantasyName": "Nome de Comercial",
        "cpf": null,
        "cnpj": "60904237000129"
    },
    "calendar": {
        "expirationAfterPayment": "10",
        "createdAt": "0001-01-01T00:00:00",
        "dueDate": "2022-04-29T00:00:00"
    },
    "createAt": "2022-03-09T14:08:12.3807504+00:00"
}

Juros

Para aplicar juros a uma cobrança, é necessário popular o objeto amountInterest, onde é preciso informar três propriedades:
hasInterest como true, para definir que serão aplicados juros após a data de vencimento;
amountPerc com o valor ou porcentagem que será somado ao valor original); e
modality com a modalidade de cálculo dos juros, que pode assumir uma das seguintes opções:

Valor

Descrição

VALUE_CALENDAR_DAYS

Valor por dia (dias corridos)

PERCENTAGE_PER_DAY_CALENDAR_DAYS

Percentual ao dia (dias corridos)

PERCENTAGE_PER_MONTH_CALENDAR_DAYS

Percentual ao mês (dias corridos)

PERCENTAGE_PER_YEAR_CALENDAR_DAYS

Percentual ao ano (dias corridos)

VALUE_WORKING_DAYS

Valor por dia (dias úteis)

PERCENTAGE_PER_DAYWORKING_DAYS

Percentual ao dia (dias úteis)

PERCENTAGE_PER_MONTH_WORKING_DAYS

Percentual ao mês (dias úteis)

PERCENTAGE_PER_YEAR_WORKING_DAYS

Percentual ao ano (dias úteis)

Note que é possível aplicar 8 maneiras diferentes de juros. Sendo assim, é necessário validar qual se aplica melhor ao seu modelo de negócio.

Modelo de request:

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/pix/v1/collection/duedate' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "expirationAfterPayment": 10,
    "duedate": "2022-04-29 00:00:00",
    "debtor": {
        "name": "Fulano de Tal",
        "cnpj": "61360961000100",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "postalCode": "01202003",
        "email": "[email protected]"
    },
    "receiver": {
        "name": "João da Silva",
        "cnpj": "60904237000129",
        "postalCode": "01202003",
        "city": "Barueri",
        "publicArea": "Avenida Brasil",
        "state": "SP",
        "fantasyName": "Nome de Comercial"
    },
    "locationId": 12730614,
    "amount": 15.63,
    "amountInterest": {
        "hasInterest": true,
        "amountPerc": "1.00",
        "modality": "VALUE_CALENDAR_DAYS"
    },
    "key": "[email protected]"
}'

Modelo de retorno:

{
    "transactionIdentification": "kk6g232xel65a0daee4dd13kk9167108",
    "transactionId": 9167108,
    "clientRequestId": "9b26edb7cf254db09f5449c94bf13abc",
    "status": "ACTIVE",
    "lastUpdate": "2022-03-09T14:54:58.6422915+00:00",
    "payerQuestion": null,
    "additionalInformation": null,
    "debtor": {
        "name": "Fulano de Tal",
        "cpf": null,
        "cnpj": "61360961000100"
    },
    "amount": {
        "original": 15.63,
        "discount": null,
        "abatement": null,
        "fine": null,
        "interest": {
            "amountPerc": "1.00",
            "modality": "VALUE_CALENDAR_DAYS"
        }
    },
    "location": {
        "merchant": {
            "postalCode": "01201005",
            "city": "Barueri",
            "merchantCategoryCode": "0000",
            "name": "Celcoin Pagamentos"
        },
        "url": "api-h.developer.btgpactual.com/v1/p/v2/cobv/3732b0967549431ba65dec199205e369",
        "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/v1/p/v2/cobv/3732b0967549431ba65dec199205e3695204000053039865802BR5918Celcoin Pagamentos6007Barueri61080120100562070503***6304A3FF",
        "type": "COBV",
        "locationId": "12730614",
        "id": null
    },
    "key": "[email protected]",
    "receiver": {
        "name": "João da Silva",
        "fantasyName": "Nome de Comercial",
        "cpf": null,
        "cnpj": "60904237000129"
    },
    "calendar": {
        "expirationAfterPayment": "10",
        "createdAt": "0001-01-01T00:00:00",
        "dueDate": "2022-04-29T00:00:00"
    },
    "createAt": "2022-03-09T14:54:58.6422915+00:00"
}

Recomendamos que seja armazenada na sua aplicação a propriedade transactionId , e transactionIdentification, para conseguir receber da Celcoin os status da cobrança, através do seu webhook. E, para saber se o QR code expirou ou não, as propriedades createAt e expirationAfterPayment.

O webhook é uma forma de receber informações de forma 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. Com o cadastro realizado em nossa plataforma, será 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 receber, é necessário executar os testes em ambiente produtivo, com uma transação e pagamento de QR code, usando saldo de sua conta bolsão Celcoin.


Did this page help you?