Transaction History

There are two methods to retrieve a list of transactions that occurred associated to an entity in our API:

List Transactions by Card

POSThttps://api.sandbox.sovera.io/cards/v2/transactions

This POST call retrieves all transactions of a particular cardId provided.

{
  "cardId": "904ee16a-db84-4120-9714-0180892341b3",
  "startDate": "2023-01-23T18:21:02.157Z"
}

{
  "success": true,
  "data": [
    {
      "type": "PeticionAutorizacion",
      "cardId": "904ee16a-db84-4120-9714-0180892341b3",
      "processingCode": "000000",
      "amount": 116,
      "transactionDateTime": "2023-02-03T19:45:12Z",
      "systemTraceAuditNumber": "000088058",
      "merchantCategoryCode": "4111",
      "acquirerCountryCode": "724",
      "authorizationCode": "169",
      "terminalId": "00004001",
      "merchantId": "000000047219191",
      "merchantName": "TRANVIA DE MURCIA CHURRA-MURCIA",
      "chainId": "0102020963010037725"
    },
    {
      "type": "PeticionAutorizacion",
      "cardId": "904ee16a-db84-4120-9714-0180892341b3",
      "processingCode": "000000",
      "amount": 2266,
      "transactionDateTime": "2023-03-17T13:55:13Z",
      "systemTraceAuditNumber": "000099870",
      "merchantCategoryCode": "5813",
      "acquirerCountryCode": "724",
      "authorizationCode": "171",
      "terminalId": "90315259",
      "merchantId": "000000175240563",
      "merchantName": "BULEVAR CAFE EL RANERO MURCIA",
      "chainId": "0102020963010037725"
    }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

data is a native array of transaction objects (no stringified payload). Each transaction follows the same structure as all transaction notifications (see Transaction Webhooks), with English field names and the chainId field for traceability.

List Transactions by Wallet

POSThttps://api.sandbox.sovera.io/cards/v2/wallet/transactions

The TransactionDetailListByWallet endpoint offers a detailed view of all transactions linked to a specific wallet. This encompasses wallet-specific transactions like pay-ins, pay-outs, and transfers, as well as card transactions tied to the specified wallet ID.

{
  "walletId": "string",
  "startDate": "Start Date in ISO Format",
  "toDate": "End Date in ISO Format",
  "limit": "Maximum Number of Transactions",
  "skip": "Number of Transactions to Skip",
  "merchantName": "Optional merchant name filter"
}

{
  "success": true,
  "data": [
    {
      "type": "PeticionAutorizacion",
      "cardId": "904ee16a-db84-4120-9714-0180892341b3",
      "processingCode": "000000",
      "amount": 116,
      "transactionDateTime": "2023-02-03T19:45:12Z",
      "systemTraceAuditNumber": "000088058",
      "merchantCategoryCode": "4111",
      "acquirerCountryCode": "724",
      "authorizationCode": "169",
      "terminalId": "00004001",
      "merchantId": "000000047219191",
      "merchantName": "TRANVIA DE MURCIA CHURRA-MURCIA",
      "chainId": "0102020963010037725",
      "transactionCurrencyCode": "840",
      "cardholderBillingAmount": 116,
      "isSettled": true
    }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06",
    "pagination": {
      "records": {
        "skip": 125,
        "limit": 25,
        "total": 320,
        "hasPrevious": true,
        "hasNext": true
      }
    }
  }
}

data is a native array of transaction objects. Each one follows the Transaction Notification Webhook structure with English field names and three additional fields (transactionCurrencyCode, cardholderBillingAmount, isSettled), plus the standard chainId key present in all webhook events:

{
  "type": "string",
  "cardId": "string",
  "processingCode": "string",
  "amount": 0,
  "transactionDateTime": "string",
  "systemTraceAuditNumber": "string",
  "merchantCategoryCode": "string",
  "acquirerCountryCode": "string",
  "authorizationCode": "string",
  "terminalId": "string",
  "merchantId": "string",
  "merchantName": "string",
  "chainId": "string",
  "transactionCurrencyCode": "string",
  "cardholderBillingAmount": 0,
  "isSettled": true
}

chainId: Links a ComunicacionAnulacion (cancellation) to its original PeticionAutorizacion (authorization). It is a 15-24-digit numeric string in auth/cancellation events and "0" in batch confirmations.
transactionCurrencyCode: ISO 4217 numeric code of the currency used for the transaction at the POS.
cardholderBillingAmount: Transaction amount, in cents, in the currency used at the POS.
isSettled: Settlement status of the transaction. false means unsettled or in transit; true means settled.

Since Sovera abstracts the settlement process for its clients, this field is particularly pertinent to specific use cases like reversals and offline cancellations.

The retrieved transaction list will encompass all transactions whose type impacts the wallet's balance. Other type values such as denied transactions won't be included.

Transactions from the Batch Process with type values of transaccionCorregidaNegativa and transaccionCorregidaPositiva will be incorporated in the retrieved list, aligning with the expected logic in the webhooks.

Each wallet transaction will be presented in their standard 200 response payload:

Parameter Explanation:

Request

Field	Description
walletId	The unique ID for the wallet, essential for fetching associated transactions.
startDate & toDate	Set the date range for transaction retrieval. To fetch and paginate all transactions, use the current date for both fields.
limit	Maximum number of transactions to return. If more exist within the date range, they're excluded.
skip	Number of transactions to skip, fetched in reverse chronological order — the pagination offset.
merchantName	An optional filter based on a specific merchant. For instance, "UBER" fetches all transactions with "UBER" in their merchant name.

Response

Field	Description
data	Native array of transaction objects in reverse chronological order.
meta.pagination.records.total	Total transactions within the requested date range.
meta.pagination.records.skip / limit	Echo of the request's `skip` and `limit`.
meta.pagination.records.hasPrevious / hasNext	Whether there are records before / after the current set.

Pagination

To manage pagination, adjust the limit and skip parameters in your request. This ensures a controlled exploration of historical transactions, maintaining a swift UX/UI performance.

Pagination lives in meta.pagination.records: total is the full count in the date range, while skip and limit echo the request. hasPrevious is skip > 0 and hasNext is skip + limit < total. A page number, if needed, is floor(skip / limit) + 1.

For instance, with skip = 125 and limit = 25 over a date range with total = 320, you're on page 6, displaying transactions numbered 126 to 150 in reverse chronological order, with both hasPrevious and hasNext set to true.