Carat - Unified Transaction Query

Overview

The Unified Transaction Query provides a main endpoint for transaction lookup with support for filters via headers and query params, plus pagination.

Purpose

Allows transaction lookup to provide a unified transaction/payment-link query across the Carat ecosystem, enabling the Fiserv Acquiring portal to query all transactions for a store regardless of the transaction origin channel.

Request

`GET /v1/transactions`

Queries transactions using filters provided through headers and query params.

Summary: Query transactions

OperationId: findAllTransactions

Request example

GET /v1/transactions?merchant_id_query=LOJAMTRG2&start_date=01/06/2026&end_date=30/06/2026&status=AUTORIZADA&page=0&limit=20
merchant_id: LOJAMTRG1
merchant_key: F19DE00177C301DF24A865F11AA9B256
group_id: 123

`curl` example

curl -X GET "http://localhost:8080/v1/transactions?merchant_id_query=LOJAMTRG2&start_date=01/06/2026&end_date=30/06/2026&status=AUTORIZADA&page=0&limit=20" \
  -H "merchant_id: LOJAMTRG1" \
  -H "merchant_key: F19DE00177C301DF24A865F11AA9B256" \
  -H "group_id: 123"

Parameters

Headers

Nome	Local	Obrigatório	Tipo	Descrição	Exemplo
`merchant_id`	header	No	string	Authenticated store code	`LOJAMTRG1`
`merchant_key`	header	No	string	Encrypted store key	`F19DE00177C301DF24A865F11AA9B256`
`group_id`	header	No	string	Store group identifier	`123`

Query params

Nome	Local	Obrigatório	Tipo	Descrição	Exemplo
`merchant_id_query`	query	No	string	Target merchant id for the query	`LOJAMTRG2`
`start_date`	query	No	string	Start date in `dd/MM/yyyy` format	`01/06/2026`
`end_date`	query	No	string	End date in `dd/MM/yyyy` format	`30/06/2026`
`status`	query	No	string	Transaction status	`AUTORIZADA`
`payment_link`	query	No	boolean	Filters payment link transactions	`true`
`page`	query	No	integer	Page number, starting at `0`	`0`
`limit`	query	No	integer	Number of records per page	`20`
`size`	query	No	integer	`limit` alias for backward compatibility	`20`

Responses

`200 OK`

Query executed successfully.

Content is returned as application/json with the TransactionsPageResponse schema.

`400 Bad Request`

Invalid request.

`401 Unauthorized`

Unauthorized.

`500 Internal Server Error`

Internal error.

Response example

{
  "code": "200",
  "message": "Query executed successfully",
  "transactions": [
    {
      "status": "AUTORIZADA",
      "merchant_id": "LOJAMTRG1",
      "order_id": "123456",
      "amount": "100.00"
    }
  ],
  "current_page": "0",
  "total_pages": "1",
  "count": "1"
}