Criar uma Cobrança Avulsa 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


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

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

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


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

CampoDescriçãoTipo Campo
externalIdIdentificador do cliente.string
expirationAfterPaymentDias após o vencimento que a cobraça pode ser paga.string
duedateData de vencimento da cobrança.string($date-time)
example: 2023-12-30T00:00:00.0000000
amountValor da cobrança.number
keyChave pix da conta BaaS.string
debtor.nameNome do Pagador.string
debtor.documentCNPJ ou CPF do pagador.string
debtor.cityCidade do pagador.string
debtor.publicAreaNome da rua do pagador.string
debtor.stateEstado do pagador.string
debtor.postalCodeCEP do pagador.string
debtor.numberNúmero da Residênciastring
debtor.complementComplementostring
debtor.neighborhoodBairrostring
receiver.documentCNPJ ou CPF do beneficiário.string
receiver.accountNúmero da conta BaaS do beneficiário.string
instructions.fineMulta aplicada após o vencimento - formato decimal (Porcentagem)number
example: 10
Valores aceitos: 0,1 a 100
instructions.interestJuros aplicado após o vencimento - formato decimal (Porcentagem)number
example: 5
Valores aceitos: 0,1 a 100
discount.modalityfixed 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.amountO valor do descontonumber
discount.limitDateData máxima para aplicação do desconto, ex: vencimento da cobrança dia 25 e desconto até o dia 20string($date-time)
example: 2023-12-20T00:00:00.0000000
split.accountNúmero da conta BaaS do beneficiário parcial.string
split.documentCNPJ ou CPF do beneficiário parcial.string
split.percentPorcentagem de recebimento parcial.number
split.amountValor fixo de recebimento parcial.number
split.aggregatePaymentIndicador 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

CodeMessage
CBE001O identificador externo é obrigatório.
CBE002Informar os dias de pagamento permitidos após o vencimento é obrigatório.
CBE003Tempo de expiração após vencimento deve ser entre 0 e 59.
CBE004A data de vencimento é obrigatória.
CBE005A data de vencimento precisa ser maior ou igual a data atual
CBE006O valor é obrigatório.
CBE007O valor precisa ser maior que 5.
CBE008Valor para recebimento parcial deve ser menor ou igual ao valor com desconto aplicado.
CBE009Valor para recebimento parcial deve ser menor ou igual ao valor original.
CBE010Não pode haver contas iguais para recebedores parciais.
CBE011Má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.
CBE016O 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.
CBE023Máximo de 20 caracteres permitido.
CBE024Máximo de 100 caracteres permitido.
CBE025Mínimo de 11 e máximo de 14 caracteres permitido.
CBE026Apenas 2 caracteres permitido.
CBE027Apenas 8 caracteres permitido.
CBE028Máximo de 200 caracteres permitido.
CBE029Documento recebedor não é válido.
CBE030Documento pagador não é válido.
CBE031O valor da multa deve estar entre 0.1 e 100.
CBE032O valor dos juros deve estar entre 0.1 e 100.
CBE033O valor de desconto precisa ser maior que 0.
CBE034O 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.
CBE036A modalidade do desconto deve ser fixed ou percent.
CBE037É necessário informar a data limite do desconto.
CBE038A 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.
CBE041Porcentagem e valor devem ser preenchidos para caso de pagamento agregado.
CBE042Apenas um dos campos de porcentagem ou valor deve estar preenchido.
CBE043Quando valor é nulo, porcentagem deve ser preenchida.
CBE044A porcentagem deve estar entre 0.1 e 100.
CBE045Quando porcentagem é nula, valor deve ser preenchido.
CBE046A quantidade deve ser maior que 0.
CBE047Account não localizada para um dos recebedores parciais.
CBE048Obrigatório o preenchimento do documento para todos os recebedores parciais.
CBE049A data limite de desconto precisa ser menor ou igual a data de vencimento e não deve ultrapassar 20 dias.
CBE050Número da conta do recebedor não localizada ou inativa.
CBE051Chave pix não localizada para a conta informada.

Webhooks de Cobranças

EventoDescrição
charge-createApós uma cobrança ser registrada, você receberá esse evento com os detalhes da cobrança
charge-inQuando 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"
      }
   }
}

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"
  },
  "createTimestamp": "2023-06-20T14:57:19.1007119",
  "entity": "charge-in",
  "error": null,
  "status": "CONFIRMED"
}