e-bak Integration Guide

Overview

The e-bak API provides secure, programmatic access to condominium-fee debt retrieval and payment services. Through these REST endpoints you can:

• Query outstanding debts for a given estate or owner.
• Calculate commissions before processing payments.
• Repay debts in bulk or individually with idempotent requests.
• Retrieve a previously processed payment by its outer payment ID.
• Discover reference data: cities, districts, buildings, condominium associations, and estates.

Environments

Tip: Complete all integration testing against the Test environment before switching to Production.

Language Support

Include an Accept-Language header with every request. Supported values:

Send exactly one of these values (for example hy-AM, not hy-AM,hy;q=0.9). If the header is missing or contains any other value, the API uses the platform's default language.

Authentication

All endpoints (except Ping) require a valid access token.

Obtaining a Token

Send your credentials to the Login endpoint. A successful response returns an accessToken and its expirationDate.

Using the Token

Include the token in the Authorization header of every subsequent request:

Authorization: {accessToken}

Token Lifecycle

• Fixed lifetime: A token is valid until the expirationDate returned by Login. Using the token does not extend it.
• Reuse: Calling Login while your token is still valid may return the same token.
• Expiration: If you receive a 401 Unauthorized response, your token has expired or was revoked. Call the Login endpoint again to obtain a fresh token, then retry.

Important: Do NOT call login before every API request. This is a common integration mistake. The login endpoint uses Argon2ID password hashing, which adds ~300ms of overhead per call. Instead, cache your token and implement a middleware/pipeline that intercepts 401 responses, re-authenticates once, and replays the failed request. This keeps your calls fast and avoids unnecessary load on the auth service.

Response Codes and Error Handling

Standard HTTP Response Codes

Error Response Structure

All errors follow a consistent JSON format:

{
  "requestId": "Unique request ID",
  "traceId": "Unique trace ID",
  "instance": "POST /api/v2/integration/debts/payments",
  "statusCode": 400,
  "type": "BadRequestException",
  "errors": {
    "field": "Error message"
  },
  "message": "transaction_already_processed"
}

Tip: Always log requestId and traceId. When contacting support, provide both values for faster resolution.

Common Models

These enums are referenced across multiple endpoints.

Note: All enums are serialized as their numeric values in JSON responses (e.g., "estateType": 0, "checkCommission": 1, "bank": 2), not as string names. The names listed below are for reference only.

Estate Types

Check Commission

Bank

Note: Value 9 is intentionally missing from the Bank enum.

API Endpoints

Ping

Health check endpoint. Returns "pong" if the service is reachable.

Login

Authenticates a service user and returns an access token.

Request:

{
  "login": "[email protected]",
  "password": "your-password"
}

Response (200):

{
  "accessToken": "opaque-access-token",
  "expirationDate": "2026-12-21T08:34:20.996Z"
}

Wrong credentials, or a disabled user or partner, return 400 with "message": "wrong_credentials".

Note: Store the token securely. Never expose it in client-side code or logs. Cache it and reuse until it expires (see Token Lifecycle).

Debt Retrieval by Estate

Retrieves all outstanding debts for a specific estate.

Path Parameters:

Response (200):

{
  "partnerId": 8,
  "partnerName": "Sample Condominium LLC",
  "estateId": 1000270,
  "estateType": 5,
  "estateAddress": "Tumanyan 33, 1",
  "primaryEstateOwnerFullName": "John Doe",
  "checkCommission": 1,
  "balance": -4900,
  "bank": 2,
  "bankAccount": "1500016548794561",
  "debts": [
    {
      "debtId": 75,
      "balance": -4900,
      "date": "2024-04-01T00:00:00Z"
    }
  ]
}

Response fields:

If the estate does not exist or is not available, the endpoint returns 404.

Debt Retrieval by Owner

Retrieves all outstanding debts across all estates owned by a person, identified by SSN or Tax Code.

Path Parameters:

Response (200):

{
  "estates": [
    {
      "partnerId": 8,
      "partnerName": "Sample Condominium LLC",
      "estateId": 1000270,
      "estateType": 3,
      "estateAddress": "Tumanyan 1, 1",
      "primaryEstateOwnerFullName": "John Doe",
      "checkCommission": 1,
      "balance": -5000,
      "bank": 2,
      "bankAccount": "1500016548794561",
      "debts": [
        {
          "debtId": 1,
          "balance": -4900,
          "date": "2024-04-01T00:00:00Z"
        },
        {
          "debtId": 20,
          "balance": -100,
          "date": "2024-04-01T00:00:00Z"
        }
      ]
    },
    {
      "partnerId": 8,
      "partnerName": "Sample Condominium LLC",
      "estateId": 1000271,
      "estateType": 0,
      "estateAddress": "Tumanyan 2, 1",
      "primaryEstateOwnerFullName": "John Doe",
      "checkCommission": 1,
      "balance": -15000,
      "bank": 2,
      "bankAccount": "1500016548794561",
      "debts": [
        {
          "debtId": 7,
          "balance": -8000,
          "date": "2024-04-01T00:00:00Z"
        },
        {
          "debtId": 5,
          "balance": -7000,
          "date": "2024-04-01T00:00:00Z"
        }
      ]
    },
    {
      "partnerId": 8,
      "partnerName": "Sample Condominium LLC",
      "estateId": 1000272,
      "estateType": 4,
      "estateAddress": "Tumanyan 2, 3",
      "primaryEstateOwnerFullName": "John Doe",
      "checkCommission": 2,
      "balance": 0,
      "bank": 0,
      "bankAccount": "2200016548794561",
      "debts": []
    }
  ]
}

Each item in the estates array follows the same structure as the Debt Retrieval by Estate response.

Note: primaryEstateOwnerFullName may be null if the owner information is not available.

If no estates are found for the document ID, the endpoint returns 200 with { "estates": [] }.

Debt Commission Calculation

Calculates the total commission for the specified debts before processing payment. This is an informational endpoint; the backend does not enforce that you call it before paying. Use it to obtain the right commission amount for the payment request.

Note on commission: The commission belongs to the integrator (you). e-bak configures and calculates it on your behalf because commission rates vary by condominium association, and maintaining the full list on your side would be impractical. This endpoint gives you the correct value without needing to know the per-condominium rates.

Request:

{
  "debtCommissionRequestModels": [
    {
      "estateId": 1000182,
      "amount": 1000,
      "debtId": null
    }
  ]
}

Request fields:

Response (200):

{
  "commission": 10
}

Tip: Only call this endpoint when the debt's checkCommission value is 1 (Yes). If checkCommission is 2 (No), the commission is zero and you can skip this step.

Debt Payment

Processes debt payments. This endpoint is idempotent when accompanied by a unique outerPaymentId: a payment ID is processed once for your account, even when the same request arrives several times at once.

Important: Always pay at the estate level, not per individual debt. Do not build UI that allows users to select and pay specific debts. The system automatically repays debts from oldest to newest (FIFO), which is the correct behavior expected by condominium associations. Allowing per-debt selection leads to situations where users pay newer debts while older ones remain unpaid, which causes disputes with condominiums. The debtId field exists in the API but should not be exposed to end users.

Request:

{
  "debtPaymentRequestModels": [
    {
      "estateId": 1654896,
      "amount": 452.25,
      "debtId": null
    }
  ],
  "outerPaymentId": "9c98610b-1cd3-4f12-83e2-2a0b86ff4c2e",
  "commission": 10
}

Request fields:

Important: Generate a standard UUID with regular hyphens for outerPaymentId. Do not reuse this value across different payment operations.

Response (200 OK):

{
  "transactions": [
    {
      "estateId": 1654896,
      "debtId": null,
      "amount": 452.25,
      "transactionId": 443,
      "date": "2023-10-18T11:21:43.757Z",
      "bank": 2,
      "bankAccount": "1500016548794561"
    }
  ],
  "outerPaymentId": "9c98610b-1cd3-4f12-83e2-2a0b86ff4c2e",
  "commission": 10
}

Response fields:

Duplicate Request (400 Bad Request):

{
  "requestId": "Unique request ID",
  "traceId": "Unique trace ID",
  "instance": "POST /api/v2/integration/debts/payments",
  "statusCode": 400,
  "type": "BadRequestException",
  "errors": null,
  "message": "transaction_already_processed"
}

Important: A 400 response with "transaction_already_processed" means the original payment was already completed successfully. Treat this as a success. Do not retry with a different outerPaymentId or charge the user again.

Payment Lookup

Retrieves a previously processed payment by its outer payment ID. Useful for verifying payment status or reconciliation. Only payments made with your own account are returned.

Path Parameters:

Response (200):

Returns the same structure as the Debt Payment response, with one entry in transactions for every estate the payment covered. commission is calculated with the current commission settings, so it can differ from the value sent with the payment if those settings changed since.

If no payment with this ID exists for your account, the endpoint returns 400 with "message": "transaction_is_not_found".

Typical Payment Flow

Below is the recommended sequence for processing a payment:

1. Retrieve debts using Debt Retrieval by Estate or by Owner.
2. Check the checkCommission field on the debt response.
   • If 1 (Yes): call Debt Commission Calculation to get the total commission amount.
   • If 2 (No): commission is 0, skip the calculation.
3. Submit payment via Debt Payment with the total amount for the estate, the commission, and a unique outerPaymentId. Pass debtId as null to let the system repay debts from oldest to newest automatically.
4. Handle the response:
   • 200: payment successful.
   • 400 with "transaction_already_processed": payment was already processed. Treat as success.
   • Other errors: inspect and handle accordingly.

Search Endpoints

These endpoints provide reference data for navigating the condominium hierarchy: City > District > Condominium Association > Building > Estate.

Search Cities

Retrieves all cities that have registered buildings.

Response (200):

[
  {
    "id": 1,
    "name": "Yerevan"
  },
  {
    "id": 2,
    "name": "Abovyan"
  },
  {
    "id": 3,
    "name": "Agarak"
  },
  {
    "id": 4,
    "name": "Alaverdi"
  }
]

Note: This endpoint returns a JSON array directly, not wrapped in an object.

Search Districts

Retrieves all districts within a given city.

Query Parameters:

Response (200):

[
  {
    "id": 13548785,
    "name": "Arabkir"
  }
]

Note: This endpoint returns a JSON array directly, not wrapped in an object.

Search Condominium Associations

Retrieves condominium associations filtered by city, with pagination.

Query Parameters:

Response (200):

{
  "values": [
    {
      "id": 1,
      "name": "A LLC"
    },
    {
      "id": 2,
      "name": "B LLC"
    },
    {
      "id": 3,
      "name": "C LLC"
    }
  ],
  "totalCount": 78
}

Search Buildings

Retrieves buildings based on filters. Supports pagination. Filters are combinable: you can pass multiple to narrow results.

Query Parameters:

* At least one of partnerId, cityId, or districtId is required; without any of them the endpoint returns 400. They can be combined for more specific queries.

Example requests:

• /api/v2/integration/search/buildings?partnerId=1&page=1&pageSize=1
• /api/v2/integration/search/buildings?cityId=1&page=1&pageSize=1
• /api/v2/integration/search/buildings?cityId=1&districtId=5&page=1&pageSize=10

Response (200):

{
  "values": [
    {
      "id": 3,
      "name": "Tumanyan 27"
    }
  ],
  "totalCount": 746
}

Search Estates

Retrieves estates within a specific building. Supports pagination.

Query Parameters:

Example request: /api/v2/integration/search/estates?buildingId=1&page=1&pageSize=1

Response (200):

{
  "values": [
    {
      "type": 0,
      "id": 13548785,
      "name": "21/2"
    }
  ],
  "totalCount": 150
}

The type field maps to the Estate Types enum.

Support

For integration questions or issues, email [email protected]. Include the requestId and traceId from the error response.