# Transaction History API

Verestro Transaction History Core API for external clients.

# Introduction

The document describes a set of technical requirements for the Verestro Transaction History Core API for external clients.

THC (Transaction History Core) is a service of Verestro dedicated to store, manage and deliver information about performed financial and loyalty transactions.

## How to connect with us?

Verestro provides Transaction History API which is implemented according to the REST model. This API offers methods that allow managing information about transactions. Verestro team actively supports Customers with integration.

To connect with the THC Verestro team need a new customer to deliver:

1. URL endpoint (for outbound method).
2. Choose authorization method:  
    
    - Mutual TLS (preferred by Verestro).
    - Basic Auth (deliver - user name, password).

# Overview

Service is designed to work in cooperation with other services from Verestro product line. Each integrated client can put, get or modify transactions in THC saved for determined project.

## Access levels:

- mobile - to be used by mobile application, directly to cardholder,
- admin - to be used by client services or Issuer Panel.

## Unique transactions

Each of transaction has its unique identifier (set by client), type and status. Payment systems, for REFUND type transaction, has same identifier as PURCHASE type transaction. Because of that unique key is id determined by client and transaction type.

## Transaction amounts

Transaction amounts are stored in database as minor (1.25 is stored as 125).

Transaction amounts of type REFUND and PAYMENT are stored as negative value (with minus).

## Transaction status

THC stores transaction information in various states. When transaction is performed, it can get one of states:

- AUTHORIZED - transaction was succesfully authorized. Resources on Cardholde's account was blocked, and amount is "promised" to merchant. At this moment none of resources transfer was performed.
- DECLINED - transaction was rejected. None of funds was blocked or transfered from Cardholder's account.

For transactions AUTHORIZED succesfully following scenarios are possiblem. It can change status to:

- REVERSED - transaction was withdrawed, for example as error reported by Merchant. Block was removed and resources on Cardholder account stay unmoved. None of transfers is performed.
- CLEARED - transaction was settled succesfully. Resources on Cardholder's account gets unblocked and trasnfered to Merchant's account. Block on Cardholder account becomes charge, and "promised" amount becomes income on Merchant's account.

[![image-1676378262715.png](https://developer.verestro.com/uploads/images/gallery/2023-02/scaled-1680-/image-1676378262715.png)](https://developer.verestro.com/uploads/images/gallery/2023-02/image-1676378262715.png)

For a detailed list please see the technical documentation.

# Technical Documentation THC External API

Technical Documentation THC External API

@swagger="https://services.upaidtest.pl/thc/doc.yaml/external"

# Quick Start - load transaction history to your app

The **Transaction History Core (THC)** service enables seamless access to a user's transaction history performed across Verestro-powered products.

By connecting to the server via a REST API, you can retrieve well-structured data representing end-user financial operations. THC itself does **not generate transactions** — instead, it **aggregates them from multiple sources**, such as:

- Card issuing platforms
- E-commerce payments
- Contactless transactions
- Many others

[![thc-basic.drawio.png](https://developer.verestro.com/uploads/images/gallery/2025-05/scaled-1680-/thc-basic-drawio.png)](https://developer.verestro.com/uploads/images/gallery/2025-05/thc-basic-drawio.png)

### Real-Time Access and Integration

Once connected, your application gains **live access to current transaction data**. You can use this data in numerous ways, including:

- Rendering transaction lists in mobile or web apps
- Triggering real-time user notifications
- Generating activity reports or analytics dashboards
- Many others

### Flexible Data Retrieval

You can fetch transaction data in a flexible way:

- Retrieve **a single transaction** by ID
- Retrieve **multiple transactions** in bulk, filtered by user, date, or other parameters
- Define input parameters to get set of desired data

### Example

Loading transactions data is as simple as on example below below:

```bash
curl -X 'GET' \
  'https://services.upaidtest.pl/thc/external/transactions?userId=1&timestampFrom=2022-01-01&timestampTo=2025-01-01' \
  -H 'accept: */*'
```