Emitir Boleto/Cobrança com Split de Pagamento

Essa funcionalidade permite que os clientes da Celcoin consigam criar cobranças para seus clientes, essas cobranças são em Boleto Registrado e em Pix Cobrança (Bolepix) e possuem split.**

Um Bolepix poderá ser configurado para ser dividido em até 5 contas no momento do recebimento do valor.
Os recursos serão divididos entre as contas automaticamente no momento do recebimento, independente se a liquidação ocorrer via Qr Code Pix ou código de barras, respeitando as informações definidas no momento da emissão do bolepix com split.

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link
Ter familiaridade com o padrão REST usando o protocolo OAuth 2.0.
Ter o produto/solução contratado e habilitado em produção.
- 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.
Possuir uma conta no BaaS da Celcoin (Conta essa responsável por receber o valor da cobrança)

Passos para Integrar

Realizar autenticação na API - [API Reference]
Criar uma Cobrança - [API Reference]
Receber o Webhook com dados da Cobrança

Caso seja necessário você pode consultar a cobrança manualmente.

Consultar Cobrança - [API Reference]

cURL da chamada

curl --location 'https://sandbox.openfinance.celcoin.dev/baas/v2/Charge' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ' \
--data '{
  "externalId": "TesteSandbox_123",
  "expirationAfterPayment": 1,
  "dueDate":"2023-12-30",
  "amount": 10,
  "debtor": {
    "number": "123",
    "neighborhood": "Alphaville Residencial Um",
    "name": "Erick Augusto Farias",
    "document": "42318970858",
    "city": "Barueri",
    "publicArea": "Alameda Holanda",
    "state": "SP",
    "postalCode": "06474320"
  },
  "receiver": {
    "account" : "300543550143",
    "document": "46532252573"
  },
  "instructions": {
    "fine": 10,
    "interest": 5,
    "discount": {
      "amount": 1,
      "modality": "fixed",
      "limitDate": "2023-12-20T00:00:00.0000000"
    }
  },
  "split": [
    {
      "account": "300543550150",
      "document": "61865163341",
      "percent": 5,
      "aggregatePayment": false
    }
  ]
}'

JSON de exemplo

{
  "externalId": "TesteSandbox_123",
  "expirationAfterPayment": 1,
  "dueDate":"2023-12-30",
  "amount": 10,
  "debtor": {
    "number": "123",
    "neighborhood": "Alphaville Residencial Um",
    "name": "Erick Augusto Farias",
    "document": "42318970858",
    "city": "Barueri",
    "publicArea": "Alameda Holanda",
    "state": "SP",
    "postalCode": "06474320"
  },
  "receiver": {
    "account" : "300543550143",
    "document": "46532252573"
  },
  "instructions": {
    "fine": 10,
    "interest": 5,
    "discount": {
      "amount": 1,
      "modality": "fixed",
      "limitDate": "2023-12-20T00:00:00.0000000"
    }
  },
  "split": [
    {
      "account": "300543550150",
      "document": "61865163341",
      "percent": 5,
      "amount": 4
      "aggregatePayment": false
    }
  ]
}

Descrição dos campos

Campo	Descrição	Tipo Campo
externalId	Identificador do cliente.	string
expirationAfterPayment	Define o período adicional permitido para pagamento após o vencimento da cobrança. Precisa ser entre 0 a 59. Não enviando o parâmetro, como default, assumirá o valor 0. Nota:_ Apesar do nome sugerir que o período ocorre após o pagamento, este campo define a janela de tolerância para pagamento após o vencimento. Caso o pagamento não seja efetuado dentro deste prazo, a cobrança será automaticamente cancelada.	string
duedate	Data de vencimento da cobrança.	string($date-time) example: 2023-12-30T00:00:00.0000000
amount	Valor da cobrança.	number
key	Chave pix da conta BaaS.	string
debtor.name	Nome do Pagador.	string
debtor.document	CNPJ ou CPF do pagador.	string
debtor.city	Cidade do pagador.	string
debtor.publicArea	Nome da rua do pagador.	string
debtor.state	Estado do pagador.	string
debtor.postalCode	CEP do pagador.	string
debtor.number	Número da Residência	string
debtor.complement	Complemento	string
debtor.neighborhood	Bairro	string
receiver.document	CNPJ ou CPF do beneficiário.	string
receiver.account	Número da conta BaaS do beneficiário.	string
instructions.fine	Multa aplicada após o vencimento - formato decimal (Porcentagem)	number example: 10 Valores aceitos: 0,1 a 100
instructions.interest	Juros aplicado após o vencimento - formato decimal (Porcentagem)	number example: 5 Valores aceitos: 0,1 a 100
discount.modality	fixed ou percent fixed para dar um desconto em valor ex: R$ 2,50 percent para dar um desconto em porcentagem ex: 10.00%	string
discount.amount	O valor do desconto	number
discount.limitDate	Data máxima para aplicação do desconto, ex: vencimento da cobrança dia 25 e desconto até o dia 20	string($date-time) example: 2023-12-20T00:00:00.0000000
split.account	Número da conta BaaS do beneficiário parcial.	string
split.document	CNPJ ou CPF do beneficiário parcial.	string
split.percent	Porcentagem de recebimento parcial.	number
split.amount	Valor fixo de recebimento parcial.	number
split.aggregatePayment	Indicador para recebimento de valor fixo com acréscimo de porcentagem.	boolean

Exemplo de retorno

👍
Sucesso 201

{
    "body": {
        "transactionId": "fab2c9c0-3bfa-4cc1-b999-4e191a893387"
    },
    "version": "1.0.0",
    "status": 201
}

❗
Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CBE001",
    "message": "Ocorreu um erro interno durante a chamada da api."
  }
}

Tabela de errorCode

Code	Message
CBE001	O identificador externo é obrigatório.
CBE002	Informar os dias de pagamento permitidos após o vencimento é obrigatório.
CBE003	Tempo de expiração após vencimento deve ser entre 0 e 59.
CBE004	A data de vencimento é obrigatória.
CBE005	A data de vencimento precisa ser maior ou igual a data atual
CBE006	O valor é obrigatório.
CBE007	O valor precisa ser maior que 5.
CBE008	Valor para recebimento parcial deve ser menor ou igual ao valor com desconto aplicado.
CBE009	Valor para recebimento parcial deve ser menor ou igual ao valor original.
CBE010	Não pode haver contas iguais para recebedores parciais.
CBE011	Máximo de 5 recebedores parciais por cobrança.
CBE012	É obrigatório informar a cidade do pagador.
CBE013	É obrigatório informar o CPF ou CNPJ do pagador.
CBE014	É obrigatório informar o nome do pagador.
CBE015	É obrigatório informar o CEP do pagador.
CBE016	O Cep informado não é válido.
CBE017	É obrigatório informar o logradouro do pagador.
CBE018	É obrigatório informar o Número do endereço do pagador.
CBE019	É obrigatório informar o Bairro do pagador.
CBE020	É obrigatório informar o Estado do pagador.
CBE021	É obrigatório informar o número da conta do recebedor.
CBE022	É obrigatório informar o CPF ou CNPJ do recebedor.
CBE023	Máximo de 20 caracteres permitido.
CBE024	Máximo de 100 caracteres permitido.
CBE025	Mínimo de 11 e máximo de 14 caracteres permitido.
CBE026	Apenas 2 caracteres permitido.
CBE027	Apenas 8 caracteres permitido.
CBE028	Máximo de 200 caracteres permitido.
CBE029	Documento recebedor não é válido.
CBE030	Documento pagador não é válido.
CBE031	O valor da multa deve estar entre 0.1 e 100.
CBE032	O valor dos juros deve estar entre 0.1 e 100.
CBE033	O valor de desconto precisa ser maior que 0.
CBE034	O valor total, após o desconto por pagamento antecipado, não pode ser inferior a R$ 5,00.
CBE035	É necessário informar a modalidade do desconto.
CBE036	A modalidade do desconto deve ser fixed ou percent.
CBE037	É necessário informar a data limite do desconto.
CBE038	A data limite do desconto não pode ser menor que a data atual.
CBE039	É obrigatório informar o número da conta de todos os recebedores parciais.
CBE040	É obrigatório informar o número de documento de todos os recebedores parciais.
CBE041	Porcentagem e valor devem ser preenchidos para caso de pagamento agregado.
CBE042	Apenas um dos campos de porcentagem ou valor deve estar preenchido.
CBE043	Quando valor é nulo, porcentagem deve ser preenchida.
CBE044	A porcentagem deve estar entre 0.1 e 100.
CBE045	Quando porcentagem é nula, valor deve ser preenchido.
CBE046	A quantidade deve ser maior que 0.
CBE047	Account não localizada para um dos recebedores parciais.
CBE048	Obrigatório o preenchimento do documento para todos os recebedores parciais.
CBE049	A data limite de desconto precisa ser menor ou igual a data de vencimento e não deve ultrapassar 20 dias.
CBE050	Número da conta do recebedor não localizada ou inativa.
CBE051	Chave pix não localizada para a conta informada.

Webhooks de Cobranças

Evento	Descrição
charge-create	Após uma cobrança ser registrada, você receberá esse evento com os detalhes da cobrança
charge-in	Quando uma cobrança é paga
charge-canceled.	Quando uma cobrança é cancelada

charge-create

{
   "body":{
      "transactionId":"e7302f6b-7188-4379-8316-6c537d288596",
      "externalId":"EXT00001",
      "amount":10,
      "duedate":"2023-07-20 00:00:00",
      "status":"PENDING",
      "debtor":{
         "name":"Josea Joaquina veira",
         "document":"1234568909",
         "postalCode":"15000000",
         "publicArea":"Rua Cinco",
         "number":"123",
         "complement":"",
         "neighborhood":"Centro",
         "city":"São Paulo",
         "state":"SP"
      },
      "receiver":{
         "name":"Monue Krajcik",
         "document":"1234568909",
         "postalCode":"08827434",
         "publicArea":"Rua Nove",
         "city":"São Paulo",
         "state":"SP",
         "account":"30053913745629"
      },
      "instructions":{
         "fine":10.0,
         "interest":1.0,
         "discount":{
            "amount":3.1,
            "modality":"fixed",
            "limitDate":"2023-07-15T03:00:00Z"
         }
      },
      "boleto":{
         "transactionId":"31881",
         "status":"PENDING",
         "bankEmissor":"santander",
         "bankNumber":"4000176322",
         "bankAgency":"1004",
         "bankAccount":"0220060",
         "barCode":"03393941700000010009022006000040001763220101",
         "bankLine":"03399022070600004000317632201012394170000001000",
         "bankAssignor":"CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA"
      },
      "pix":{
         "transactionId":"816145081",
         "transactionIdentification":"kk6g232xel65a0daee4dd13kk816145081",
         "status":"PENDING",
         "key":"[email protected]",
         "emv":"00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/pc/p/v2/cobv/bf53a874ef9d4a0cb2e1226b5c2d5ed05204000053039865802BR5915Monique Krajcik6015West Marianabor61080882743462070503***630441FF"
      }
   }
}

🚧
Importante
O recebimento do webhook de charge-create não significa que o boleto foi registrado na Nuclea, pois o processo de registro é realizado de forma paralela.

📘
No charge-create retornam três IDs
body.transactionId → ID da cobrança
body.boleto.transactionId → ID do boleto.
body.pix.transactionId → ID da cobrança Pix.

charge-in

{
  "body": {
    "status": "Pago",
    "valorOriginal": 5,
    "dataVencimento": "2023-06-30 00:00:00",
    "transactionId": "e77adbbf-66ea-4749-987f-a5eb165fda94",
    "externalId": "TesteSandbox_43",
    "valorPago": 5,
    "dataPagamento": "2023-06-20",
    "result": [],
    "tipoPagamento": "Pix",
    "currentBalance": 95716.33,
    "oldBalance": 95003.75,
    "split": [
      {
        "account": "48033",
        "document": "63921674123",
        "percent": 5.0,
        "amount": 1.0,
        "aggregatePayment": true
      },
      {
        "account": "48041",
        "document": "52779183020",
        "percent": 3.0,
        "amount": 5.0,
        "aggregatePayment": true
      }
    ],
    "creditParty": {
      "taxId": "46085258000139",
      "account": "30053913747534"
    },
    "balances": [
      {
        "account": "48033",
        "document": "",
        "oldBalance": 0.0,
        "currentBalance": 0.0
      },
      {
        "account": "48041",
        "document": "",
        "oldBalance": 39.6,
        "currentBalance": 68.03
      }
    ]
  },
  "createTimestamp": "2023-06-20T14:57:19.1007119",
  "entity": "charge-in",
  "error": null,
  "status": "CONFIRMED"
}

📘
No charge-in retorna um transactionId no body que será o mesmo transactionId retornado no charge-create → se refere ao ID geral da cobrança.
O tipo de pagamento é diferenciado pelo campo tipoPagamento ("Pix" ou "Boleto").

Updated 6 days ago

Did this page help you?