Cadastrar Cobrança

post

https://sandbox.platform.credit.celcoin.com.br/escrow/api/v1/wallets/{wallet_id}/charges-1

Este endpoint permite criar cobranças, processar pagamentos, consultar detalhes e receber notificações via Webhook sobre eventos do ciclo de vida de uma cobrança.

Autenticação

Authorization: Bearer {API_TOKEN}
Content-Type: application/json

Criar Cobrança

Cria uma nova cobrança com regras de desconto, juros, multa, split e dados completos do pagador.

POST `/charges`

Request Body — Parâmetros

Dados principais da cobrança

Campo	Tipo	Obrigatório	Descrição
`due_date`	datetime	Sim	Data de vencimento da cobrança (ISO 8601).
`amount`	float	Sim	Valor total da cobrança.
`fine`	float	Não	Percentual de multa por atraso.
`interest`	float	Não	Percentual de juros aplicado após o vencimento.
`discount_limit_date`	datetime	Não	Data limite para aplicação do desconto.
`discount_modality`	string	Não	Modalidade do desconto: `FIXED` ou `PERCENT`.
`discount_value`	float	Não	Valor do desconto, conforme a modalidade definida.

Objeto `charge_debtor` — Dados do Pagador

Campo	Tipo	Obrigatório	Descrição
`number`	string	Não	Número do endereço.
`neighborhood`	string	Não	Bairro.
`name`	string	Sim	Nome completo do pagador.
`document`	string	Sim	Documento do pagador (CPF ou CNPJ).
`city`	string	Não	Cidade.
`public_area`	string	Não	Logradouro (rua, avenida, etc.).
`state`	string	Não	Estado (UF).
`postal_code`	string	Não	CEP.
`country_code`	string	Não	Código do país (ex: `BR`).
`phone_code`	string	Não	Código do país para telefone (ex: `+55`).
`number_phone`	string	Não	Número do telefone.
`email`	string	Não	E-mail do pagador.

Objeto `charge_split` — Split de Pagamento

Campo	Tipo	Obrigatório	Descrição
`account_destination_id`	string	Sim	Identificador da conta recebedora do split.
`split_type`	string	Sim	Tipo de split: `PERCENTAGE` ou `AMOUNT`.
`split_percentage`	float	Não	Percentual do valor destinado ao split. Obrigatório quando `split_type = PERCENTAGE`.
`split_amount`	float	Não	Valor fixo destinado ao split. Obrigatório quando `split_type = AMOUNT`.

Response — Sucesso

{
  "id": "chg_123456"
}

Campo	Tipo	Descrição
`id`	string	Identificador único da cobrança.

Processamento da Cobrança

Após a criação, a cobrança é processada de forma assíncrona.

O resultado é enviado via Webhook conforme o status do processamento.

Webhook — Cobrança Criada com Sucesso

Evento disparado quando a cobrança é registrada com sucesso.

Event

charge.created

Payload — Parâmetros

Campo	Tipo	Descrição
`charge_id`	string	Identificador da cobrança.
`pix_code`	string	Código PIX para pagamento.
`digitable_line`	string	Linha digitável do boleto.
`bank_number`	string	Código do banco emissor.
`pix_base64`	string	QR Code PIX em Base64.
`client_code`	string	Código do cliente.
`link_boleto`	string	URL para acesso ao boleto.

Webhook — Erro na Criação da Cobrança

Evento disparado quando ocorre falha no processamento.

Event

charge.error

Payload — Parâmetros

Campo	Tipo	Descrição
`charge_id`	string	Identificador da cobrança.
`client_code`	string	Código do cliente.
`status`	string	Status do processamento (`ERROR`).
`error`	string	Mensagem detalhando o erro ocorrido.

Consultar Detalhes da Cobrança

Retorna todas as informações da cobrança, incluindo pagamento, boleto, PIX e splits.

GET `/charges/{charge_id}`

Response — Parâmetros

Dados gerais

Campo	Tipo	Descrição
`id`	string	Identificador da cobrança.
`amount`	number	Valor total da cobrança.
`charge_code`	number	Código interno da cobrança.
`due_date`	date	Data de vencimento.
`amount_paid`	number	Valor efetivamente pago.
`paid_amount`	number	Valor liquidado.
`fees`	number	Taxas aplicadas.
`interest`	number	Juros aplicados.
`discount_modality`	string	Modalidade do desconto.
`discount_value`	number	Valor do desconto.
`discount_limit_date`	date	Data limite para desconto.
`taxes_to_apply_after_payment`	number	Taxas aplicáveis após pagamento.

Dados de pagamento

Campo	Tipo	Descrição
`bar_code`	string	Código de barras do boleto.
`pix_code`	string	Código PIX.
`pix_detail`	string	Descrição do pagamento PIX.
`boleto_details`	object	Informações adicionais do boleto.
`charge_pdf_url`	string	URL do PDF do boleto.

Objeto `charge_receiver`

Campo	Tipo	Descrição
`account`	string	Conta recebedora.
`document`	string	Documento do recebedor.

Objeto `split` (array)

Campo	Tipo	Descrição
`account`	string	Conta beneficiária do split.
`document`	string	Documento do beneficiário.
`split_type`	string	Tipo do split (`PERCENTAGE` ou `AMOUNT`).
`split_percentage`	string	Percentual do split.
`split_amount`	string	Valor fixo do split.

Status da Cobrança

Status	Descrição
`CREATED`	Cobrança criada.
`PROCESSING`	Em processamento.
`PAID`	Cobrança paga.
`EXPIRED`	Cobrança vencida.
`ERROR`	Erro no processamento.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Cadastrar Cobrança

Cadastra uma nova cobrança vinculada a uma carteira (wallet), permitindo definição de vencimento, descontos, juros, multa e divisão de recebíveis.

Endpoint

POST /wallets/{walletId}/charges

Autenticação

Este endpoint requer autenticação via token.

Authorization: Bearer (access_token)

Headers

Header	Tipo	Obrigatório	Descrição
Content-Type	string	Sim	application/json
Authorization	string	Sim	Bearer Token

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
walletId	string	Sim	Identificador da wallet

Body Parameters

Objeto Raiz

Campo	Tipo	Obrigatório	Descrição
due_date	datetime	Sim	Data de vencimento da cobrança
amount	float	Sim	Valor total da cobrança
fine	float	Não	Multa por atraso (mínimo 0)
interest	float	Não	Juros por atraso (mínimo 0)
discount_limit_date	datetime	Sim	Data limite para aplicação do desconto
days_to_expire_after_payment	integer	Não	Dias para expiração após pagamento
discount_modality	string	Sim	Modalidade do desconto
discount_value	float	Não	Valor do desconto (mínimo 0)
charge_debtor	object	Sim	Dados do pagador
charge_receivers	array	Sim	Lista de recebedores da cobrança

discount_modality

Valores permitidos:

PERCENT
FIXED

Objeto `charge_debtor`

Campo	Tipo	Obrigatório	Descrição
number	string	Sim	Número do endereço
neighborhood	string	Sim	Bairro (máx. 200 caracteres)
name	string	Sim	Nome do pagador
document	string	Sim	Documento válido (CPF ou CNPJ)
city	string	Sim	Cidade (máx. 100 caracteres)
public_area	string	Sim	Logradouro
state	string	Sim	Estado (UF – 2 caracteres)
postal_code	string	Sim	CEP válido
phone	object	Não	Telefone
email	string	Não	E-mail válido

Objeto `phone`

Campo	Tipo	Obrigatório	Descrição
country_code	string	Não	Código do país
area_code	string	Não	DDD
number	string	Não	Número do telefone

Objeto `charge_receivers[]`

Campo	Tipo	Obrigatório	Descrição
account_destination_id	string	Sim	Conta de destino
split_type	string	Sim	Tipo de divisão
split_percentage	float	Não	Percentual do split
split_amount	float	Não	Valor fixo do split

split_type

Valores permitidos:

PERCENTAGE
AMOUNT

Regra:

Se split_type = PERCENTAGE, informe split_percentage
Se split_type = AMOUNT, informe split_amount

Exemplo de Requisição

{
  "due_date": "2026-02-10T23:59:59Z",
  "amount": 150.75,
  "fine": 2.0,
  "interest": 1.5,
  "discount_limit_date": "2026-02-05T23:59:59Z",
  "days_to_expire_after_payment": 5,
  "discount_modality": "PERCENT",
  "discount_value": 10,
  "charge_debtor": {
    "name": "João da Silva",
    "document": "12345678909",
    "public_area": "Rua das Flores",
    "number": "100",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01001000",
    "email": "[email protected]",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "999999999"
    }
  },
  "charge_receivers": [
    {
      "account_destination_id": "acc_123",
      "split_type": "PERCENTAGE",
      "split_percentage": 100
    }
  ]
}

Resposta de Sucesso

201 Created

{
  "id": "ch_abc123456"
}

Responses

Cadastrar Cobrança

Endpoint

Autenticação

Headers

Path Parameters

Body Parameters

discount_modality

Objeto charge_debtor

Objeto phone

Objeto charge_receivers[]

split_type

Exemplo de Requisição

Resposta de Sucesso

200OK

401Unauthorized

403Forbidden

404Not Found

Objeto `charge_debtor`

Objeto `phone`

Objeto `charge_receivers[]`