> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Boleto Payments

> Create and retrieve boleto bill payments (Brazil only).

<Warning>This service is not yet available in v3. Available in **v2** only.</Warning>

## What is the Boleto Payments?

The **Boleto Payments API (v2)** allows you to programmatically manage and execute boleto bancário payments (bank slips) in Brazil, including both:

* **Manual boletos** (initiated via barcode)
* **DDA (Débito Direto Autorizado)** pre-authorized invoices retrieved automatically from financial institutions

You can use this API to:

* Fetch and display pending DDA bills
* Initiate boleto payments (DDA or manual)
* Retrieve a complete payment history

## Available Endpoints

| Operation               | Endpoint                  | Method |
| ----------------------- | ------------------------- | ------ |
| Get all DDA invoices    | `/v2/payments/dda`        | GET    |
| Get DDA invoice by UUID | `/v2/payments/dda/{uuid}` | GET    |
| Create boleto payment   | `/v2/payments`            | POST   |
| Get all boleto payments | `/v2/payments`            | GET    |

<br />

## Get all DDA invoices

Use this endpoint to **retrieve all DDA invoices** (pending or unpaid) available to your company. These invoices are issued by suppliers or creditors and automatically associated with your account by the banking network.

### Endpoint

`GET /v2/payments/dda`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments/dda" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
[
  {
    "uuid": "dda-uuid-001",
    "issuer": "Empresa XYZ",
    "amount": 350.75,
    "dueDate": "2025-07-20",
    "status": "PENDING"
  }
]
```

<br />

## Get DDA Invoice by UUID

Use this endpoint to retrieve detailed information for a specific DDA invoice using its uuid.

### Endpoint

`GET /v2/payments/dda/{uuid}`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments/dda/dda-uuid-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
{
  "uuid": "dda-uuid-001",
  "issuer": "Empresa XYZ",
  "amount": 350.75,
  "dueDate": "2025-07-20",
  "status": "PENDING",
  "barcodeDigitableLine": "23791887700000350758091001100123456789000000000"
}

```

<br />

## Create a Boleto Payment

Use this endpoint to initiate a boleto payment using a valid barcodeDigitableLine. This works for both DDA and manually obtained boletos.

You can optionally attach metadata to link this payment to specific internal processes.

### Endpoint

`POST /v2/payments`

### cURL Request

```curl cURL theme={null}
curl -X POST \
"https://public-api.mx.clara.com/api/v2/payments" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "barcodeDigitableLine": "23791887700000350758091001100123456789000000000"
}'
```

### Sample JSON Response

```json JSON theme={null}
{
  "uuid": "payment-uuid-001",
  "status": "PROCESSING",
  "amount": 350.75,
  "dueDate": "2025-07-20",
  "executedAt": "2025-07-18T12:00:00Z"
}
```

<br />

## Get All Boleto Payments

Use this endpoint to retrieve the list of all boleto payments initiated from your account, including both DDA and manual payments.

You can apply filters such as status, startDate, or endDate.

### Endpoint

`GET /v2/payments`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments?status=SUCCESS&startDate=2025-07-01" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
[
  {
    "uuid": "payment-uuid-001",
    "barcodeDigitableLine": "23791887700000350758091001100123456789000000000",
    "amount": 350.75,
    "status": "SUCCESS",
    "executedAt": "2025-07-18T12:00:00Z"
  },
  {
    "uuid": "payment-uuid-002",
    "barcodeDigitableLine": "00193373700000001000500940144816060652304638300",
    "amount": 100.00,
    "status": "FAILED",
    "executedAt": "2025-07-15T10:30:00Z"
  }
]
```

<br />

\*\*💡 Tip: \*\*Use the DDA endpoints to show users their pre-approved invoices. You can pay them by simply passing the barcodeDigitableLine to the /v2/payments endpoint.

\*\*⚠️ Note: \*\*All payments must comply with due dates and available balance. Payment execution is not guaranteed if validation fails or if the boleto is expired.

***

## Endpoint Reference

### `GET /api/v2/payments`

List payments (v2)

### `POST /api/v2/payments`

Create payment (v2)

**Request Body (`PaymentRequest`):**

| Field     | Type                   | Example |
| --------- | ---------------------- | ------- |
| `boletos` | array of BoletoRequest |         |

### `GET /api/v2/payments/dda`

List DDA payments (v2)

### `GET /api/v2/payments/{barcode_digitableline}`

Get payment by barcode or digitable line (v2). Returns merged payment data from all matching payment attempts. Path parameter must be numeric only.

**Parameters:**

| Parameter               | In   | Type   | Required | Description                                                          |
| ----------------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `barcode_digitableline` | path | string | ✅        | Numeric barcode or digitable line (digits only, pattern: `^[0-9]+$`) |

**Response Schema (`PaymentMergedV2`):**

| Field                       | Type                      | Description                           | Example                                                    |
| --------------------------- | ------------------------- | ------------------------------------- | ---------------------------------------------------------- |
| `barcode`                   | string                    | Boleto barcode                        | `"23793381286000000003281000108399191460000010000"`        |
| `digitableLine`             | string                    | 47/48-digit digitable line            | `"23793.38128 60000.000038 28100.010839 9 19146000001000"` |
| `amount`                    | number (decimal)          | Payment amount                        | `100.0`                                                    |
| `beneficiaryDocumentNumber` | string                    | Beneficiary CPF/CNPJ                  | `"45690845000194"`                                         |
| `beneficiaryName`           | string                    | Beneficiary name                      | `"EMPRESA EXEMPLO LTDA"`                                   |
| `paid`                      | boolean                   | Whether any attempt has status `PAID` | `true`                                                     |
| `externalId`                | string                    | External reference ID                 |                                                            |
| `transactionId`             | string                    | Associated transaction ID             |                                                            |
| `paymentDatetime`           | string (date-time)        | Payment execution datetime            |                                                            |
| `attempts`                  | array of `PaymentAttempt` | History of payment attempts           |                                                            |

**`PaymentAttempt` fields:**

| Field          | Type               | Description                         |
| -------------- | ------------------ | ----------------------------------- |
| `externalId`   | string             | External identifier for the attempt |
| `status`       | string             | Attempt status (e.g., `PAID`)       |
| `errorMessage` | string \| null     | Error message if attempt failed     |
| `timestamp`    | string (date-time) | When the attempt was made           |