Digital Account

This service is available in v3 only.

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.

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

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

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

General Response

{
    "data": [
        {
            "id": 2317547016,
            "endToEndId": "D6070119020250909120000000000002",
            "originalTransaction": {
                "id": 2317547015,
                "endToEndId": "E6070119020250909120000000000001",
                "transactionDate": "2025-09-09T00:00:00",
                "transactionDateTime": "2025-09-09T11:00:00Z",
                "amount": 0.01,
                "method": "PIX",
                "type": "Transfer sent"
            },
            "transactionDate": "2025-09-09T00:00:00",
            "transactionDateTime": "2025-09-09T14:32:05Z",
            "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
    }
}

Bill Response

{
  "data": [
			{
        "id": 3925095764,
        "transactionDate": "2025-07-03T00:00:00",
        "transactionDateTime": "2025-07-03T13:08:41Z",
        "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`
`endToEndId`	string \| null	PIX end-to-end identifier.	`"E6070119020250825143205000000001"`
`originalTransaction`	object \| null	Full original transaction when this row is a reversal.	`{ "id": 2317547015, "endToEndId": "E6070119020250909120000000000001", "method": "PIX" }`
`transactionDate`	string (ISO-8601 date-time)	Transaction date at start of day (legacy field, UTC).	`2026-10-28T00:00:00`
`transactionDateTime`	string (ISO-8601 date-time)	Full transaction date/time including timezone (UTC).	`2026-10-28T22:06:02.917Z`
`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.

Get the digital account balance

Returns the available balance of the authenticated company’s checking and collateral accounts. The company is resolved from the taxId on the token — the endpoint takes no parameters. This endpoint is Brazil only and requires the read:digital-account scope.

The two balances use different units.

checkingAccount.available is in cents: 703575.00 means R$ 7,035.75.
collateralAccount.available is in decimal currency units: 30.20 means R$ 30.20.

A future balance endpoint will return both values in decimal currency units. Until then, this endpoint keeps its current behavior.

Endpoint

GET /v3/digital-accounts/balance

Successful Response

Status	Meaning
200	OK - Digital account balance returned

Field	Type	Unit	Description	Example
`checkingAccount.available`	number (cents)	Cents (BRL)	Available balance of the company’s checking account, in cents. Divide by `100` to display BRL.	`703575.00`
`collateralAccount.available`	number (decimal)	Currency units (BRL)	Available balance of the collateral account, in decimal units. `0.00` when the company has none.	`30.20`

Error Responses

Status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden — the token lacks the `read:digital-account` scope, or carries no company `taxId`
404	Digital account not found
503	Digital account service unavailable — a downstream dependency failed; retry later

Example cURL Request

curl --location --request GET 'https://public-api.br.clara.com/api/v3/digital-accounts/balance' \
--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

{
    "checkingAccount": {
        "available": 703575.00
    },
    "collateralAccount": {
        "available": 30.20
    }
}

Endpoint Reference

`GET /api/v3/digital-accounts`

List digital account transactions (v3, Brazil only)

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

Get the authenticated company’s digital account balance (v3, Brazil only; requires the read:digital-account scope)

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

How to get Transactions from digital account via Clara API

Authentication Requirements

Endpoint

Query Parameters (Optional)

Client‑side validation rules

Examples

1. Filter by date range

2. Filter by type alias (`transactionTypeName`)

3. Combined

Validation messages (client)

Successful Response

Error Responses

Example cURL Request

Example Response Object

Field reference

Get the digital account balance

Endpoint

Successful Response

Error Responses

Example cURL Request

Example Response Object

Endpoint Reference

`GET /api/v3/digital-accounts`

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

​How to get Transactions from digital account via Clara API

​Authentication Requirements

​Endpoint

​Query Parameters (Optional)

​Client‑side validation rules

​Examples

​1. Filter by date range

​2. Filter by type alias (transactionTypeName)

​3. Combined

​Validation messages (client)

​Successful Response

​Error Responses

​Example cURL Request

​Example Response Object

​Field reference

​Get the digital account balance

​Endpoint

​Successful Response

​Error Responses

​Example cURL Request

​Example Response Object

​Endpoint Reference

​GET /api/v3/digital-accounts

​GET /api/v3/digital-accounts/balance

How to get Transactions from digital account via Clara API

Authentication Requirements

Endpoint

Query Parameters (Optional)

Client‑side validation rules

Examples

1. Filter by date range

2. Filter by type alias (`transactionTypeName`)

3. Combined

Validation messages (client)

Successful Response

Error Responses

Example cURL Request

Example Response Object

Field reference

Get the digital account balance

Endpoint

Successful Response

Error Responses

Example cURL Request

Example Response Object

Endpoint Reference

`GET /api/v3/digital-accounts`

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