Setting

[!info] Overview The Setting REST API manages payment transaction settings and configurations in the pkbillms billing system. Settings define terminal properties, merchant configurations, and system parameters required for processing payments through various payment gateways (UZCARD, PAYNET, HUMO, WAY4).

📋 Table of Contents

• Quick Reference

• Data Models

• API Endpoints

  • Create Setting

  • Update Setting

  • Partial Update

  • Get All Settings

  • Get Single Setting

  • Count Settings

  • Delete Setting

• Error Handling

• Validation Rules

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: Setting

• Controller: SettingResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

Method	Endpoint	Description	Status
POST	/api/settings	Create new setting	201
PUT	/api/settings/{id}	Full update	200
PATCH	/api/settings/{id}	Partial update	200
GET	/api/settings	Get all with pagination	200
GET	/api/settings/{id}	Get by ID	200
GET	/api/settings/count	Count by criteria	200
DELETE	/api/settings/{id}	Delete setting	204

---

Data Models

Setting Specifications

Field	Type	Required	Max/Range	Description
id	Long	❌ Auto	-	Primary key
shortName	String	✅	64	Short name to show in UI
ord	Integer	❌	-	Display order
active	Boolean	✅	-	Activation status
props	Map<Prop, SettingProperty>	✅	-	Configuration properties map

SettingProperty Specifications

Field	Type	Required	Max/Range	DB Column	Description
id	Long	❌ Auto	-	id	Primary key
key	Prop	✅	ENUM	key	Property key identifier
type	PropType	✅	ENUM	type	Property value type
value	String	✅	5000	value	Property value

Prop Enum

public enum Prop implements Serializable {
    UZCARD_TERMINAL,      // UZCARD terminal ID
    UZCARD_MERCHANT,      // UZCARD merchant ID
    UZCARD_PORT,          // UZCARD connection port
    PAYNET_TERMINAL,      // PAYNET terminal ID
    PAYNET_USERNAME,      // PAYNET username
    PAYNET_PASSWORD,      // PAYNET password
    HUMO_MERCHANT,        // HUMO merchant ID
    HUMO_TERMINAL,        // HUMO terminal ID
    EPOS_EX,              // EPOS extended settings
    TERMINAL_PURPOSE,     // Terminal purpose code
    MULTI_TRAN,           // Multi-transaction flag
    WAY4_MERCHANT,        // WAY4 merchant ID
    WAY4_TERMINAL         // WAY4 terminal ID
}

PropType Enum

public enum PropType {
    TEXT,     // Plain text value
    JSON,     // JSON object/array
    BOOLEAN   // Boolean flag (true/false)
}

---

API Endpoints

Create Setting

POST /api/settings

Creates a new payment setting configuration.

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "shortName": "UZCARD_TERMINAL_01",
  "ord": 1,
  "active": true,
  "props": {
    "UZCARD_TERMINAL": {
      "key": "UZCARD_TERMINAL",
      "type": "TEXT",
      "value": "TERM001"
    },
    "UZCARD_MERCHANT": {
      "key": "UZCARD_MERCHANT",
      "type": "TEXT",
      "value": "MERCH001"
    },
    "UZCARD_PORT": {
      "key": "UZCARD_PORT",
      "type": "TEXT",
      "value": "8080"
    },
    "MULTI_TRAN": {
      "key": "MULTI_TRAN",
      "type": "BOOLEAN",
      "value": "true"
    }
  }
}

[!warning] Validation Rules

• id must be null (auto-generated)

• shortName and active are required

• shortName max length is 64 characters

• props map must contain valid Prop keys

• Each property must have valid key, type, and value

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/settings/1

{
  "id": 1,
  "shortName": "UZCARD_TERMINAL_01",
  "ord": 1,
  "active": true,
  "props": {
    "UZCARD_TERMINAL": {
      "id": 1,
      "key": "UZCARD_TERMINAL",
      "type": "TEXT",
      "value": "TERM001",
      "createdBy": "admin",
      "createdDate": "2026-01-29T14:30:00Z"
    },
    "UZCARD_MERCHANT": {
      "id": 2,
      "key": "UZCARD_MERCHANT",
      "type": "TEXT",
      "value": "MERCH001",
      "createdBy": "admin",
      "createdDate": "2026-01-29T14:30:00Z"
    },
    "UZCARD_PORT": {
      "id": 3,
      "key": "UZCARD_PORT",
      "type": "TEXT",
      "value": "8080",
      "createdBy": "admin",
      "createdDate": "2026-01-29T14:30:00Z"
    },
    "MULTI_TRAN": {
      "id": 4,
      "key": "MULTI_TRAN",
      "type": "BOOLEAN",
      "value": "true",
      "createdBy": "admin",
      "createdDate": "2026-01-29T14:30:00Z"
    }
  }
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "detail": "A new setting cannot already have an ID",
  "message": "error.idexists",
  "entityName": "pkbillmsSetting",
  "errorKey": "idexists"
}

---

Update Setting

[!example] PUT /api/settings/{id} Updates an existing payment setting (full update).

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "shortName": "UZCARD_TERMINAL_01",
  "ord": 2,
  "active": true,
  "props": {
    "UZCARD_TERMINAL": {
      "key": "UZCARD_TERMINAL",
      "type": "TEXT",
      "value": "TERM001_UPDATED"
    },
    "UZCARD_MERCHANT": {
      "key": "UZCARD_MERCHANT",
      "type": "TEXT",
      "value": "MERCH001"
    }
  }
}

[!warning] Validation Rules

• id must match path parameter

• id must not be null

• Setting must exist in database

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "shortName": "UZCARD_TERMINAL_01",
  "ord": 2,
  "active": true,
  "props": {
    "UZCARD_TERMINAL": {
      "id": 1,
      "key": "UZCARD_TERMINAL",
      "type": "TEXT",
      "value": "TERM001_UPDATED",
      "lastModifiedBy": "admin",
      "lastModifiedDate": "2026-01-29T15:00:00Z"
    },
    "UZCARD_MERCHANT": {
      "id": 2,
      "key": "UZCARD_MERCHANT",
      "type": "TEXT",
      "value": "MERCH001"
    }
  }
}

❌ Error (400 - Invalid ID):

{
  "status": 400,
  "detail": "Invalid ID",
  "message": "error.idinvalid",
  "entityName": "pkbillmsSetting",
  "errorKey": "idinvalid"
}

❌ Error (400 - Not found):

{
  "status": 400,
  "detail": "Entity not found",
  "message": "error.idnotfound",
  "entityName": "pkbillmsSetting",
  "errorKey": "idnotfound"
}

---

Partial Update

[!example] PATCH /api/settings/{id} Partially updates setting properties.

Request

Headers:

Content-Type: application/merge-patch+json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "active": false,
  "ord": 5
}

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "shortName": "UZCARD_TERMINAL_01",
  "ord": 5,
  "active": false,
  "props": {
    "UZCARD_TERMINAL": {
      "key": "UZCARD_TERMINAL",
      "type": "TEXT",
      "value": "TERM001"
    }
  }
}

❌ Error (404 - Not Found):

HTTP/1.1 404 Not Found

---

Get All Settings

[!example] GET /api/settings Retrieves all payment settings with pagination and filtering.

Request

Headers:

Authorization: Bearer {token}

Query Parameters:

Parameter	Type	Required	Description
page	Integer	❌	Page number (default: 0)
size	Integer	❌	Page size (default: 20)
sort	String	❌	Sort field and direction
unPaged	Boolean	❌	Disable pagination

Example:

GET /api/settings?page=0&size=10&sort=ord,asc

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 5

[
  {
    "id": 1,
    "shortName": "UZCARD_TERMINAL_01",
    "ord": 1,
    "active": true,
    "props": {
      "UZCARD_TERMINAL": {
        "key": "UZCARD_TERMINAL",
        "type": "TEXT",
        "value": "TERM001"
      },
      "UZCARD_MERCHANT": {
        "key": "UZCARD_MERCHANT",
        "type": "TEXT",
        "value": "MERCH001"
      }
    }
  },
  {
    "id": 2,
    "shortName": "PAYNET_TERMINAL_01",
    "ord": 2,
    "active": true,
    "props": {
      "PAYNET_TERMINAL": {
        "key": "PAYNET_TERMINAL",
        "type": "TEXT",
        "value": "PTERM001"
      },
      "PAYNET_USERNAME": {
        "key": "PAYNET_USERNAME",
        "type": "TEXT",
        "value": "paynet_user"
      },
      "PAYNET_PASSWORD": {
        "key": "PAYNET_PASSWORD",
        "type": "TEXT",
        "value": "********"
      }
    }
  }
]

---

SettingCriteria - Advanced Filtering

[!abstract] JHipster Criteria Filtering SettingCriteria provides powerful filtering capabilities for querying payment settings. All filter parameters support multiple operators for precise data retrieval.

Available Filter Types

String Filters:

Operator	Description	Example
equals	Exact match	shortName.equals=UZCARD_TERMINAL_01
notEquals	Not equal	shortName.notEquals=TEST_TERMINAL
in	Match any value	shortName.in=TERM01,TERM02
notIn	Not in list	shortName.notIn=OLD_TERM
contains	Partial match	shortName.contains=UZCARD
doesNotContain	Doesn't contain	shortName.doesNotContain=TEST
specified	Field exists/null	shortName.specified=true

Numeric Filters (Long, Integer):

Operator	Description	Example
equals	Exact match	id.equals=1
notEquals	Not equal	ord.notEquals=0
in	Match any value	id.in=1,2,3
notIn	Not in list	id.notIn=99,100
greaterThan	Greater than	ord.greaterThan=5
lessThan	Less than	ord.lessThan=10
greaterOrEqualThan	Greater or equal	ord.greaterOrEqualThan=1
lessOrEqualThan	Less or equal	ord.lessOrEqualThan=10
specified	Field exists/null	ord.specified=true

Boolean Filters:

Operator	Description	Example
equals	Exact match	active.equals=true
notEquals	Not equal	active.notEquals=false
specified	Field exists/null	active.specified=true

SettingCriteria Parameters

public class SettingCriteria implements Serializable, Criteria {
    private LongFilter id;
    private StringFilter shortName;
    private IntegerFilter ord;
    private BooleanFilter active;
    private LongFilter propId;         // Filter by property ID
}

Common Query Examples

Filter Active Settings:

GET /api/settings?active.equals=true

Filter by Name:

GET /api/settings?shortName.contains=UZCARD

Filter by Display Order:

GET /api/settings?ord.greaterThan=0&ord.lessThan=10

Search Specific Terminals:

GET /api/settings?shortName.in=UZCARD_TERMINAL_01,PAYNET_TERMINAL_01

Active Settings Only:

GET /api/settings?active.equals=true&sort=ord,asc

Complex Filter (AND operation):

GET /api/settings?active.equals=true&shortName.contains=TERMINAL&ord.greaterThan=0&sort=ord,asc

Combining Filters

[!tip] Multiple Criteria All criteria are combined with AND logic. Use .in operator for OR logic on same field.

Example:

# AND: Active=true AND Name contains UZCARD
GET /api/settings?active.equals=true&shortName.contains=UZCARD

# OR (same field): Name=TERM01 OR Name=TERM02
GET /api/settings?shortName.in=TERM01,TERM02

---

Get Single Setting

[!example] GET /api/settings/{id} Retrieves a single payment setting by ID.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/settings/1

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "UZCARD_TERMINAL_01",
  "ord": 1,
  "active": true,
  "props": {
    "UZCARD_TERMINAL": {
      "id": 1,
      "key": "UZCARD_TERMINAL",
      "type": "TEXT",
      "value": "TERM001",
      "createdBy": "admin",
      "createdDate": "2026-01-29T14:30:00Z",
      "lastModifiedBy": "admin",
      "lastModifiedDate": "2026-01-29T14:30:00Z"
    },
    "UZCARD_MERCHANT": {
      "id": 2,
      "key": "UZCARD_MERCHANT",
      "type": "TEXT",
      "value": "MERCH001"
    },
    "UZCARD_PORT": {
      "id": 3,
      "key": "UZCARD_PORT",
      "type": "TEXT",
      "value": "8080"
    },
    "MULTI_TRAN": {
      "id": 4,
      "key": "MULTI_TRAN",
      "type": "BOOLEAN",
      "value": "true"
    }
  }
}

❌ Error (404 - Not found):

HTTP/1.1 404 Not Found

---

Count Settings

[!example] GET /api/settings/count Counts payment settings matching criteria.

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Any SettingCriteria filters.

Example:

GET /api/settings/count?active.equals=true

Response

✅ Success (200 OK):

5

---

Delete Setting

[!example] DELETE /api/settings/{id} Deletes a payment setting.

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/settings/1

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

---

Error Handling

Error Response Format

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "path": "/api/settings",
  "message": "error.validation",
  "entityName": "pkbillmsSetting",
  "errorKey": "validation",
  "fieldErrors": [
    {
      "objectName": "settingDTO",
      "field": "shortName",
      "message": "must not be null"
    }
  ]
}

HTTP Status Codes

Code	Description	When
200	OK	Successful GET/PUT/PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation error
401	Unauthorized	Missing/invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
500	Internal Server Error	Server error

---

Validation Rules

Required Fields

[!check] Mandatory Fields

• ✅ shortName - Setting name

• ✅ active - Activation status

• ✅ props - Properties map (can be empty)

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"A new setting cannot already have an ID"
id	Not null for PUT/PATCH	"Invalid id"
shortName	@NotNull, @Size(max=64)	"must not be null", "size must be between 0 and 64"
active	@NotNull	"must not be null"
props	@NotNull	"must not be null"

SettingProperty Constraints

Field	Rules	Error Messages
key	@NotNull, Valid Prop enum	"must not be null", "must be valid Prop value"
type	@NotNull, Valid PropType	"must not be null", "must be valid PropType value"
value	@NotNull, @Size(max=5000)	"must not be null", "size must be between 0 and 5000"

Business Rules

[!info] Business Validation

• shortName identifies the setting in UI

• props is a Map with Prop enum as key and SettingProperty as value

• Each SettingProperty must have a unique key within the setting

• type determines how value should be parsed (TEXT, JSON, BOOLEAN)

• value max length is 5000 characters for JSON configurations

• Boolean values must be stored as strings: "true" or "false"

• JSON values must be valid JSON format

• active flag enables/disables the entire setting

---

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "shortName": "UZCARD_TERMINAL_01",
    "ord": 1,
    "active": true,
    "props": {
      "UZCARD_TERMINAL": {
        "key": "UZCARD_TERMINAL",
        "type": "TEXT",
        "value": "TERM001"
      },
      "UZCARD_MERCHANT": {
        "key": "UZCARD_MERCHANT",
        "type": "TEXT",
        "value": "MERCH001"
      },
      "MULTI_TRAN": {
        "key": "MULTI_TRAN",
        "type": "BOOLEAN",
        "value": "true"
      }
    }
  }'

Update

curl -X PUT http://localhost:8080/api/settings/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "shortName": "UZCARD_TERMINAL_01",
    "ord": 2,
    "active": true,
    "props": {
      "UZCARD_TERMINAL": {
        "key": "UZCARD_TERMINAL",
        "type": "TEXT",
        "value": "TERM001_UPDATED"
      }
    }
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/settings/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "active": false, "ord": 5}'

Get All

curl -X GET "http://localhost:8080/api/settings?page=0&size=10&sort=ord,asc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Criteria

curl -X GET "http://localhost:8080/api/settings?active.equals=true&shortName.contains=UZCARD" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

curl -X GET http://localhost:8080/api/settings/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Count

curl -X GET "http://localhost:8080/api/settings/count?active.equals=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

curl -X DELETE http://localhost:8080/api/settings/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

📊 Property Types Explained

[!info] PropType Usage Guide

TEXT Type

Used for simple string values:

{
  "key": "UZCARD_TERMINAL",
  "type": "TEXT",
  "value": "TERM001"
}

JSON Type

Used for complex configurations:

{
  "key": "EPOS_EX",
  "type": "JSON",
  "value": "{\"timeout\": 30, \"retries\": 3, \"endpoints\": [\"https://api.epos.uz\"]}"
}

BOOLEAN Type

Used for flags (stored as string):

{
  "key": "MULTI_TRAN",
  "type": "BOOLEAN",
  "value": "true"
}

[!warning] Important Notes

• JSON values must be properly escaped

• Boolean values are strings: "true" or "false"

• Value field max length is 5000 characters

• Invalid JSON will cause parsing errors

---

🔐 Security Considerations

[!warning] Sensitive Data Settings may contain sensitive information:

• Passwords: Store encrypted or hashed

• API Keys: Use secure vault when possible

• Credentials: Never log in plain text

• Access Control: Restrict who can view/modify settings

Best Practices:

• Encrypt sensitive values before storing

• Use environment variables for critical secrets

• Audit all setting modifications

• Implement role-based access control

• Mask passwords in API responses

---

📝 Notes

[!tip] Best Practices

• Use meaningful shortName values for easy identification

• Set appropriate ord values for UI display order

• Group related properties under single setting

• Use JSON type for complex configurations

• Always validate JSON values before saving

• Keep property values under 5000 characters

• Document each property's purpose

[!warning] Important

• Deleting settings may affect payment processing

• Inactive settings will not be used by payment gateways

• Changing terminal IDs requires gateway reconfiguration

• Props map uses Prop enum as key - case sensitive

• Boolean values must be strings: "true" or "false"

• JSON values must be valid and properly escaped

---

---