---
title: "Cadastrar uma nova cobrança"
method: POST
path: "/escrow/api/v1/wallets/{wallet_id}/charges"
tags: ["Carteiras > Cobranças"]
---

# Cadastrar uma nova cobrança

`POST /escrow/api/v1/wallets/{wallet_id}/charges`

## Request

- Base URL: `https://sandbox.platform.credit.celcoin.com.br`
- URL: `https://sandbox.platform.credit.celcoin.com.br/escrow/api/v1/wallets/{wallet_id}/charges`
- Auth: none declared

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

## Path parameters

- `wallet_id` string, required

## Headers

- `Content-Type` string
- `Accept` string

## Request body

- object

## Response `200`

OK

- object

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found

---

[API](https://skmtc.dev/celcoin/apis/celcoin-escrow.md) - [All operations](https://skmtc.dev/celcoin/apis/celcoin-escrow/llms.txt) - [OpenAPI document](https://skmtc.dev/celcoin/apis/celcoin-escrow/revisions/5d55a35a6d51?raw)