Skip to main content

​
Tier API Documentation

​
Overview

The Tier API provides endpoints for managing account tiers in the wallet service. It supports creating and updating tiers with daily and monthly transaction limits, and retrieving tier information.

​
Base URL

/api/v1/tiers

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key

​
Endpoints

​
Register Tier

Create a new tier configuration. Endpoint: POST /register Headers:
  • X-API-KEY: API key for authentication
Request Body: 
{
  "name": "string",
  "dailyLimit": "number",
  "monthlyLimit": "number",
  "tenantId": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "name": "string",
    "tierId": "string",
    "dailyLimit": "number",
    "monthlyLimit": "number",
    "tenantId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Update Tier

Update an existing tier configuration. Endpoint: POST /update/{tierId} Headers:
  • X-API-KEY: API key for authentication
Path Parameters:
  • tierId: The ID of the tier to update
Request Body: 
{
  "name": "string",
  "dailyLimit": "number",
  "monthlyLimit": "number",
  "tenantId": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "name": "string",
    "tierId": "string",
    "dailyLimit": "number",
    "monthlyLimit": "number",
    "tenantId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
View Tiers

Retrieve tiers with filtering and pagination. Endpoint: GET /get Headers:
  • X-API-KEY: API key for authentication
Query Parameters:
  • name: Tier name
  • tierId: Tier ID
  • dailyLimit: Daily transaction limit
  • monthlyLimit: Monthly transaction limit
  • tenantId: Tenant ID
  • page: Page number (default: 0)
  • size: Page size (default: 20)
  • sort: Sort field and direction (e.g., “createdAt,desc”)
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "id": "number",
        "name": "string",
        "tierId": "string",
        "dailyLimit": "number",
        "monthlyLimit": "number",
        "tenantId": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "pageable": {
      "pageNumber": "number",
      "pageSize": "number",
      "sort": {
        "sorted": "boolean",
        "unsorted": "boolean",
        "empty": "boolean"
      },
      "offset": "number",
      "paged": "boolean",
      "unpaged": "boolean"
    },
    "totalElements": "number",
    "totalPages": "number",
    "last": "boolean",
    "size": "number",
    "number": "number",
    "sort": {
      "sorted": "boolean",
      "unsorted": "boolean",
      "empty": "boolean"
    },
    "numberOfElements": "number",
    "first": "boolean",
    "empty": "boolean"
  }
}

​
Error Responses

401 Unauthorized 
{
  "statusCode": 401,
  "message": "user not authenticated",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "tier not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "tier already exists",
  "data": null
}

​
Notes

  • Tier Configuration:
    • Each tier has a unique name per tenant
    • Tiers have daily and monthly transaction limits
    • Tiers are associated with a specific tenant
  • Tier Limits:
    • Daily limit: Maximum transaction amount per day
    • Monthly limit: Maximum transaction amount per month
    • Limits are enforced per account
    • Limits are checked before each transaction
  • Tier Validation:
    • Duplicate tier names are prevented per tenant
    • Limits must be positive numbers
    • Tier name is required
    • Tenant ID is required
  • Tier Permissions:
    • Tenant admins can manage their tiers
    • Platform admins can manage all tiers
    • Regular users cannot manage tiers
  • Tier Tracking:
    • All tier changes are logged
    • Tier history is maintained
    • Limit violations are monitored
    • Failed operations are tracked
  • Tier Notifications:
    • Tier creation is notified
    • Tier updates are logged
    • Limit violations are reported
    • Status changes are notified
  • Tier Usage:
    • Tiers are assigned to accounts
    • Multiple accounts can use the same tier
    • Tier changes affect all associated accounts
    • Tier limits are enforced in real-time
  • Tier Management:
    • Tiers can be updated at any time
    • Updates affect future transactions only
    • Existing transactions are not affected
    • Tier changes require admin approval