Skip to main content
Start for free

Bank Transactions - 5 Minutes Tutorial - API Integration

Prerequisites

The following information is required to be able to integrate with Authologic:

  • Developer portal credentials,
  • API Keys.

Developer Portal Credentials

The developer portal address and credentials were provided during onboarding.

Passwords And API Keys

During the onboarding you have received the API keys:

  • API key allowing communication with Authologic.
  • The key used to verify the data sent by Authologic by the callback mechanism.

Integration Overview

Authologic provides a simple and effective way to verify a user’s identity. The API process involves three key steps: initiating the verification through an external system, redirecting the user to the appropriate page, and receiving the verification results.

The entire process is called conversation. The following diagram represents the process logical flow:

  1. Start of the identity verification process. Your server calls the API method called: POST /api/conversations
  2. The response returns information about the address to which the user should be redirected
  3. Your system redirects the user's browser to the above URL
  4. The user verifies himself
  5. Authologic redirects the user's browser to a predefined page of your system
  6. Your server displays the return page
  7. Authologic calls a callback on your server's side with the result of the verification and the status of the bank transactions
  8. After the callback with bank transaction status FINISHED is received your system may start fetching the bank transactions via the API
Sometimes Authologic is able to send the verification information before the user is redirected to the return page. However, many types of verification require additional time. When creating your system, it should be taken into account in the process that the verification result will be available to the user only after some time.
We use the curl tool to show the API operation. If you have not dealt with it, you can find a short guide on it here(opens in new tab). Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the link: here, or any other tool, such as Postman or Insomnia.

Creating a Conversation

In order to retrieve information about the user's bank transactions, a conversation must be created. In this example we will use two products together - the bankTransactions and identity. When using the bankTransactions product it is necessary to specify which lists should be checked and provide the data that should be checked. Example:

The conversation creation API does not have any mandatory fields. This is because your account may have default values for all fields configured. Thanks to this, possible changes in the requirements are not connected with your code.
The Authologic API uses the Basic Auth based authentication described, among others, at here(opens in new tab). Username and API key should be used as data. By using the curl tool we use the -u option which is responsible for the use of Basic Auth.
curl -X POST -u my_login "https://sandbox.authologic.com/api/conversations" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json" \
-d '{
    "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
    "returnUrl": "https://id.sandbox.uthologic.com/c/{conversationId}/thankYou",
    "callbackUrl": "my_callback_url_here",
    "query": {
        "identity": {
            "requireOneOf": [
                [ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
            ]
        },
        "bankTransactions": {
            "type": "ALL",
            "flags": [ "INCLUDE_TAGS" ]
        }
    }
}'

The bankTransactions may include additional properties defining its behavior:

  • type - the type of transactions you are interested in, can take the value of ALL, CREDIT or DEBIT.
  • flags - array of additional flags that can include values INCLUDE_SCHEDULED to include scheduled transaction and INCLUDE_TAGS to include tags.

Of course, instead of my_login enter your login. You should be prompted for a password - at that point you should enter the API key (do not confuse it with the password to the customer panel).

For my_callback_url_here you could use https://webhook.site/(opens in new tab) to generate callback url which will be responsible for receiving user information from Authologic. Whether you will use webhook.site or other similar tool it is crucial that it will correctly receive http request since it is required for the process of identification.

Conversation defined this way, in response to a query about its status, returns an additional section:

{
  "id": "c12c1adc-3ff0-4d32-b95c-c593135c903e",
  "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
  "url": "https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
  "status": "CREATED",
  "result": {
    "identity": {
      "status": "IN_PROGRESS",
      "user": {}
    },
    "bankTransactions": {
      "status": "IN_PROGRESS"
    }
  }
}

Info: status behaves identically to the identity section.

{
  "id": "c12c1adc-3ff0-4d32-b95c-c593135c903e",
  "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
  "url": "https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
  "status": "FINISHED",
  "result": {
    "identity": {
      "status": "FINISHED",
      "user": {
        "person": {
          "name": {
            "firstName": "Maria",
            "lastName": "Sochacka"
          }
        }
      }
    },
    "bankTransactions": {
      "status": "FINISHED"
    }
  },
  "info": [
    {
      "country": "PL",
      "method": "PSD2"
    }
  ]
}

Downloading Transactions

After finishing the conversation, we can retrieve the list of transactions using the query:

curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"

In the response we are getting the first page of results:

{
  "more": true,
  "items": [
    {
      "id": "34df2bd6-b790-4560-9fc9-f86c86d87990",
      "date": "2020-08-27T10:40:28.348Z",
      "bank": "BREXPLPW",
      "accountId": "PL68249000050000400075212326",
      "type": "DEBIT",
      "amount": 10030,
      "currency": "PLN",
      "title": "Zasilenie konta",
      "sender": "Jan Kowalski",
      "senderAccountId": "PL68249000050000400075212326",
      "recipient": "Jan Kowalski",
      "recipientAccountId": "PL32114020040000320250132522",
      "tags": ["internal"]
    }
  ]
}

The key information here is the: more. If it has the value: true, then we can query for another page of results by adding the parameter: page:

curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions?page=1" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"

By modifying the page parameter we can retrieve subsequent pages of results until the response shows more set to false.

Retrieving information about bank accounts

Another element is the possibility of additional information about the returned accounts for which the user has given us permissions.

curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions/accounts" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"

The response is a list of items for each account given to us, e.g .:

{
  "items": [
    {
      "date": "2020-09-17T11:18:21.999Z",
      "balance": 10030,
      "bank": "BREXPLPW",
      "accountId": "PL68249000050000400075212326",
      "currency": "PLN",
      "activationDate": "2014-11-19"
    }
  ]
}

Retrieving Transaction Statistics

Authologic also provides a number of transaction-related statistics. Here you can see the simplest form, without e.g. specifying a date range. Details are traditionally described in Transaction Statistics.

curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions/stats" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"

An example response of the above command looks as follows:

{
  "dateFrom": "2020-09-16T10:44:51.544Z",
  "dateTo": "2020-09-16T10:44:51.544Z",
  "items": [
    {
      "dateFirst": "2020-06-16T00:00:00.000Z",
      "dateLast": "2020-09-16T00:00:00.000Z",
      "numberOfCreditTransactions": 12,
      "numberOfDebitTransactions": 12,
      "avgCreditPerMonth": 300000,
      "avgDebitPerMonth": 258000,
      "avgCredit": 30000,
      "avgDebit": 40000,
      "maxCredit": 110000,
      "maxDebit": 132000,
      "accountId": "PL68249000050000400075212326",
      "currency": "PLN"
    }
  ]
}
That's it. You managed to use API and get data.

What's Next

Combining Products

Combining multiple products together in a single request.

Testing

Learn how to test your integration.

Productionize

What to do before going to production.

WebSDK

Embedding the verification process within your website.

Embedding the verification process within your website is completely optional. Using redirection in your process if sufficient and more than enough to start working with Authologic. You can consider it when you would like the process to be a part of the web application.

Additional Information

Bank Transactions Data

Detailed description of the bank transactions data retrieval.

Account Information Retrieval

Description of the bank transactions account data information retrieval.

Statistics Retrieval

Detailed description of the bank transactions statistics retrieval.

Troubleshooting

Callbacks

Not being able to receive callbacks.

Errors

Verification failure reasons.

Statuses

Handling various conversation statuses.

FAQ

Frequently asked questions.

Deprecations

Deprecated features and options list.

Despite our sincere intentions, it is difficult to create perfect technical documentation. If you have an idea on how to improve this documentation, or you have trouble understanding any section, please email us at tech-support@authologic.com
Was this page helpful?
Powered by Authologic Nisaba