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

# Digital Account

> Access digital account transactions including PIX, TED, and bill payments (Brazil only).

<Note>This service is available in **v3** only.</Note>

## How to get Transactions from digital account via Clara API

This guide explains how to use the `GET /api/v3/digital-accounts` endpoint to retrieve transactions in the Clara API system.

***

## Authentication Requirements

To access this endpoint, ensure the following:

* Use **mutual TLS (MTLS)** for secure two-way certificate validation.
* Obtain an **OAuth2 access token** via the `/oauth/token` endpoint.
* Include the **Bearer token** in the `Authorization` header of your request.

***

## Endpoint

```
GET /v3/digital-accounts
```

***

## Query Parameters (Optional)

This section lists the optional filters available for the Digital Account endpoint. All parameters can be **combined** and are intended to narrow results by **date range** and **transaction types**:

* Dates are supplied in local **`yyyy-MM-dd`** format; the SDK **normalizes them to end-of-day UTC** before building the URL.
* Validation (format, list size, and date ordering) happens **client-side** before the request is sent.
* <br />

| Parameter             | Type          | Format / Allowed values                   | Description                                                                                                                  | Example                   |
| --------------------- | ------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `startDate`           | string        | `yyyy-MM-dd`                              | Start of the date range (local). The SDK normalizes it to **end‑of‑day UTC** before sending the request.                     | `startDate=2025-08-01`    |
| `endDate`             | string        | `yyyy-MM-dd`                              | End of the date range (local). The SDK normalizes it to **end‑of‑day UTC**; must be **≥ `startDate`**.                       | `endDate=2025-08-10`      |
| `transactionTypeName` | string (enum) | `PIX` \| `TED` \| `BILL` \| `TRANSACTION` | Human-friendly alias. The SDK maps it to one or more `transactionTypes` codes; if mapping yields no codes, nothing is added. | `transactionTypeName=PIX` |

### Client‑side validation rules

These rules are applied by `DigitalAccountTransactionFilter` before the request is built:

* `startDate`, `endDate`: `@Pattern("\d{4}-\d{2}-\d{2}")` — error: *Date must be in ISO format (yyyy-MM-dd).*
* `transactionTypeName`: `@Pattern("PIX|TED|BILL|TRANSACTION")` — error: *transactionTypeName must be one of: PIX, TED, BILL, TRANSACTION.*
* Date range: `@AssertTrue` ensures `startDate <= endDate` when both dates are present and parsable — error: *startDate must be less than or equal to endDate.*

> **Note:** End‑of‑day UTC normalization happens **after** the ISO date format check.

***

## Examples

### 1. Filter by date range

**Request (query):**

```
GET /v3/digital-accounts?startDate=2025-08-01&endDate=2025-08-10
```

### 2. Filter by type alias (`transactionTypeName`)

**Request (query):**

```
GET /v3/digital-accounts?transactionTypeName=PIX
```

### 3. Combined

**Request (query):**

```
GET /v3/digital-accounts?startDate=2025-08-03&endDate=2025-08-10&transactionTypeName=PIX
```

<br />

## Validation messages (client)

* `Date must be in ISO format (yyyy-MM-dd)`
* `transactionTypeName must be one of: PIX, TED, BILL, TRANSACTION`
* `startDate must be less than or equal to endDate`

> The backend may return additional validation errors.

> ⚠️ **Important Notes:**
>
> * Response is a JSON array (no envelope with totalElements).
> * Keep paging until an empty page or a page with \< size items is returned.

## Successful Response

| Status | Meaning                            |
| ------ | ---------------------------------- |
| 200    | OK - List of transactions returned |

***

## Error Responses

| Status | Meaning      |
| ------ | ------------ |
| 400    | Bad Request  |
| 401    | Unauthorized |
| 403    | Forbidden    |

***

## Example cURL Request

```bash theme={null}
curl --location --request GET 'https://public-api.br.clara.com/api/v3/digital-accounts?page=0&size=50' \
--header 'Authorization: Bearer {your_access_token}' \
--cert {client_cert_path} \
--key {client_key_path}
```

Replace `{your_access_token}`, `{client_cert_path}`, and `{client_key_path}` with actual values.

***

## Example Response Object

```json General Response theme={null}
{
    "data": [
        {
            "id": 2317547016,
            "transactionDate": "2025-09-09T00:00:00",
            "amount": 0.01,
            "method": "PIX",
            "type": "Reversal of sent transfer",
            "source": {
                "name": "ABCD EJAF ",
                "taxId": "123.038.XSJ",
                "institution": "18236301"
            },
            "beneficiary": {
                "name": "CLARA PARTICIPACOES LTDA",
                "taxId": "42367512309812",
                "institution": "14290914"
            }
        }
    ],
    "meta": {
        "totalPages": 39,
        "totalItems": 388,
        "itemsPerPage": 10,
        "currentPage": 0
    }
}
```

```json Bill Response theme={null}
{
  "data": [
			{
        "id": 3925095764,
        "transactionDate": "2025-07-03T00:00:00",
        "amount": 9.00,
        "method": "Bill",
        "type": "Transfer sent",
        "source": {
            "name": "CLARA INSTITUIÇÃO DE PAGAMENTO LTDA",
            "taxId": "41818339000586",
            "institution": "BTG Pactual"
        },
        "beneficiary": {
            "name": "CLARA INSTITUICAO DE PAGAMENTO LTDA",
            "taxId": "41818339000586",
            "institution": null
        },
        "description": "Boleto integral",
        "digitableLine": null,
        "charges": {
            "discount": 0.0,
            "fee": 0.0,
            "interest": 0.0,
            "totalFees": null
        }
			}
	],
    "meta": {
        "totalPages": 39,
        "totalItems": 388,
        "itemsPerPage": 10,
        "currentPage": 0
    }
}
```

***

## Field reference

| Field             | Type                        | Description                                                                     | Example                                                                                        |
| ----------------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `id`              | number                      | Unique transaction identifier.                                                  | `3671272250`                                                                                   |
| `transactionDate` | string (ISO-8601 date-time) | Transaction date/time.                                                          | `2025-08-25T00:00:00`                                                                          |
| `amount`          | number (decimal)            | Currency amount in **units** (not cents). In typed languages, use `BigDecimal`. | `0.10`                                                                                         |
| `method`          | string (enum)               | Payment method.                                                                 | `PIX` · `TED` · `Bill` · `Transfer` · `Undefined`                                              |
| `type`            | string                      | Business label describing the transaction.                                      | `Transfer sent` · `Deposit in account` · `Reversal of sent transfer`                           |
| `description`     | string \| null              | Optional description (mostly for bills).                                        | `"Boleto integral"`                                                                            |
| `digitableLine`   | string \| null              | Bill (bank slip) digitable line when available.                                 | `"23793.38127 60000.000123 45000.567890 1 23450000010000"`                                     |
| `charges`         | object \| null              | Bill fee breakdown: `discount`, `fee`, `interest`, `totalFees`.                 | `{ "discount": 0.0, "fee": 0.0, "interest": 0.0, "totalFees": null }`                          |
| `source`          | object \| null              | Origin party: `{ name, taxId, institution }`.                                   | `{ "name": "CLARA PARTICIPACOES LTDA", "taxId": "45690845000194", "institution": "41538335" }` |
| `beneficiary`     | object \| null              | Destination party: `{ name, taxId, institution }`.                              | `{ "name": "CLARA PAGAMENTOS LTDA", "taxId": "41538335000145", "institution": null }`          |

> ⚠️ Note: some fields may be `null` depending on the `method`/`type`.

***

## Endpoint Reference

### `GET /api/v3/digital-accounts`

List digital account transactions (v3, Brazil only)