🔄 Digital Account API: How to Use It (Only Brazil)

This guide explains how to fetch Digital Account Transactions. There is a single endpoint and it returns transactions bound to the account associated with the access token (no accountId parameter is required).

🧾 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

Bash

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,
            "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
    }
}

Bill Response

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