# Getting Started
Transactions of a given account can be retrieved by the client using the transactions API (opens new window).
But in some cases, clients may wish to receive a constant, realtime stream of their transactions, instead of polling them by their own, for instance in order to feed them into their ERP system, or any other form of propogation/aggregation.
Tillhub offers its clients such transactions streaming services, utilising Google Cloud's Pub/Sub streaming.
# Obtaining a service account key and subscription
Tillhub support will create for you a client account's dedicated Topic and Subscription.
Please Note: It is highly recommended to learn about Google Cloud's pub/sub infrastructure (opens new window) before implementing a client to tap on transactions.
The support team provides two deliverables (currently via mail, in future releases Tillhub will publish an API to create your own topic and subscriptions) consisting of:
- Subscription name
- Service Account Key (JSON) file
The subscription name is required to connect to the subscription, and the service account key file is containing the permissions to connect to such a subscription.
IMPORTANT: Make sure the service account key file is stored in a secured and safe manner. Any other party obtaining this key may tap on your transactional data and compromise your privacy and isolation! For further reading about Google Cloud's service accounts and their meintenance see here (opens new window).
Tillhub support can create for you multiple subscriptions for your transactions topic. This may come in handy in the case that more than one client is required to process the same transactions (each subscription can pull/push transactional data independently in a mutually exclusive manner).
# Push vs. Pull
The provided subscription by Tillhub support is requiring a client pulling the transactions by default. In case you wish the transactions will be pushed instead, you must provide an endpoint with a valid DNS name and the support team will configure it as the subscription push endpoint.
Note: In the case of a pull client, the messages must be manually acknowledged (see the implementation section in this tutorial). In the case of a push endpoint, the messages are acknowledged/rejected by returning either HTTP status code 200 or an error status code respectively.
# Transactional data structure
The transactions (opens new window) are sent through the subscription as a base64 encoded string. Each subscription message contains a single transaction, accompanied by metadata attributes, including the transaction ID and the client account ID.
For further information regarding the message structure see here (opens new window).
# Implementing a client
Tillhub offers transactional data streams set over standard Google Cloud pub/sub infrastructure. Google offer SDKs in various programming languages in order to cater for pub/sub clients.
Please find below some reading material to get you started with Google Cloud client libraries: