Client API Documentation for Transaction Anomaly Monitoring System

1. API Specifications

1.1 Endpoint URL

  • API Endpoint URL: You will provide us with a secure HTTPS endpoint where our system can send requests to retrieve transaction data.

  • Example: https://api.yourcompany.com/stats

1.2 Request Method

  • HTTP Method: GET

  • Content-Type: application/json

1.3 Request Parameters

Our system will send a JSON payload containing the following parameters:

Parameter
Type
Description
Example

start_time

String

Start of the time interval in ISO 8601 format (UTC).

"2024-09-30T10:00:00Z"

end_time

String

End of the time interval in ISO 8601 format (UTC).

"2024-09-30T10:05:00Z"

groups

String

Comma-separated list of groups (e.g., merchants) to retrieve.

"merchant1,merchant2" "all"

signature

String

HMAC SHA-256 signature for authentication.

"a1b2c3d4e5f6g7h8i9j0..."

1.3.1 Parameter Details

  • start_time and end_time:

    • Represent the time window for which transaction data is requested.

    • Possible intervals are 5, 10, 15, or 30 minutes, depending on settings and agreed-upon configurations.

    • Must be in ISO 8601 format and in UTC timezone.

  • groups:

    • Specifies which groups or merchants the data should be retrieved for.

    • If set to "all", data for all available groups should be returned.

  • signature:

    • Used for request authentication.

    • Generated using HMAC SHA-256 with a secret key.

1.4 Authentication

1.4.1 Signature Generation

The signature parameter is generated by concatenating the values of start_time, end_time, and groups, then applying HMAC SHA-256 encryption using the secret key.

Example in Python:

import hmac
import hashlib

data = "2024-09-30T10:00:00Z2024-09-30T11:00:00Zmerchant1,merchant2"
secret_key = "your_secret_key"
signature = hmac.new(secret_key.encode(), data.encode(), hashlib.sha256).hexdigest()

Important Notes:

  • The shared secret key will be provided to you securely.

  • Ensure that the signature is correctly calculated to avoid authentication errors.

1.5 Response Structure

Your API should return a JSON response with the following structure:

Field
Type
Description

status

String

"success" or "error".

error_code

Integer

Numeric code (0 for success, other codes for specific errors).

error_message

String

Description of the error (if any).

start_time

String

Echoes the start_time from the request.

end_time

String

Echoes the end_time from the request.

groups

Array

Contains data objects for each group and metric.

1.5.1 Group Data Object

Each element in the groups array should have the following fields:

Field
Type
Description

group

String

Name of the group (e.g., merchant identifier).

metric

String

Name of the metric (e.g., "transaction_count").

count

Integer

Transaction count for the specified period.

1.6 Requests and Responses Examples

1.6.1 Request Example

{
  "start_time": "2024-09-30T10:00:00Z",
  "end_time": "2024-09-30T10:05:00Z",
  "groups": "merchant1,merchant2",
  "signature": "a1b2c3d4e5f6g7h8i9j0..."
}

1.6.2 Successful Response

{
  "status": "success",
  "error_code": 0,
  "error_message": null,
  "start_time": "2024-09-30T10:00:00Z",
  "end_time": "2024-09-30T10:05:00Z",
  "groups": [
    {
      "group": "merchant1",
      "metric": "transactions_all",
      "count": 150
    },
    {
      "group": "merchant2",
      "metric": "deposits",
      "count": 200
    }
  ]
}

1.6.3 Error Response - Invalid Signature

{
  "status": "error",
  "error_code": 1,
  "error_message": "Invalid authentication signature",
  "start_time": null,
  "end_time": null,
  "groups": null
}

1.7 Error Codes

Error Code
Description

0

Success

1

Invalid signature

2

Missing or invalid parameters

3

Internal server error

4

Too many requests (rate limiting)

1.8 HTTP Status Codes

  • 200 OK: Successful requests.

  • 400 Bad Request: Invalid request format or parameters.

  • 401 Unauthorized: Authentication failed.

  • 429 Too Many Requests: Rate limiting applied.

  • 500 Internal Server Error: Server-side errors.

2. Groups and Metrics

  • Groups: Typically represent identifiers such as merchant IDs, store IDs, or any other logical grouping relevant to your business.

  • Metrics: Currently, the system focuses on the number of transactions in the specified interval. It can be one of transaction types like “deposits” or “withdrawals”, and also the whole transaction amount without types differentiation, for example “all transactions”.

3. Initial Training and Missing Data Recovery Procedure

The anomaly detection service will automatically recover missing data in cases where the client's system was unresponsive or there were issues with the monitoring service itself. It will sequentially request data for the missing period, at a rate of 5 requests per second. These requests are identical to those used during normal operation.

Initial training happens in the same way as Missing Data Recovery Procedure but will be applied for 6 weeks time period.

4. Limits

  • In current version the maximum response size should not exceed 500 KB. Please contact Anomalis team if you predict larger responses.

  • Maximum length of the requested interval between start_time and end_time from Anomalis Service is not supposed to be larger than 30 minutes.

  • The requested stats are not supposed to be older than 2 months ago.

  • In case of missing data recovery procedure, you will receive 5 requests per second maximum.

5. Notifications

5.1 Anomaly Notification

When an anomaly is detected, the system sends a Telegram message containing the following parameters:

  • Incident ID: Unique identifier for the incident, used to link information about this anomaly with other events.

  • Type: Type of anomaly, currently always set to "Statistical". More types will be added in future versions.

  • Group: Logical grouping of incidents, such as merchant ID or other relevant business identifiers.

  • Metric: A specific name or designation for the metric used to detect the anomaly. It can include transaction types like "deposits" or "withdrawals" or the total transaction volume, such as "all transactions".

  • Detected: The specific moment in time when the anomaly was detected.

  • Layers affected: Time intervals where anomalies were detected (e.g., 5 minutes, 15 minutes, 2 hours, 8 hours, etc.). Describes the time layers where deviations were observed, including expected and actual metric values.

Example:

[Anomaly Detected]
Incident ID: 12345
Type: Statistical
Group: merchant1
Metric: deposits
Detected: 2024-08-23 08:15:00
Layers affected:
  - 5 minutes (expected: 200, actual: 150)
  - 15 minutes (expected: 600, actual: 500)

5.2 Normalization Notification

Sent when the anomaly is resolved.

Example:

[Anomaly Resolved]
Incident ID: 12345
Group: merchant1
Metric: deposits
Incident Start: 2024-08-23 08:00:00
Incident End: 2024-08-23 09:00:00

Last updated