P2p condition

[!info] Overview The P2P Condition REST API manages conditions for peer-to-peer payment routing in the pkbillms billing system. P2P conditions define matching rules and criteria used by P2P parameters to determine transaction routing between different payment processors.

📋 Table of Contents

• Quick Reference

• Data Models

• API Endpoints

  • Create P2P Condition

  • Update P2P Condition

  • Partial Update

  • Get All P2P Conditions

  • Get Single P2P Condition

  • Count P2P Conditions

  • Delete P2P Condition

• Request & Response Examples

• Error Handling

• Validation Rules

• Business Logic

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: P2PCondition

• Controller: P2pConditionResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

Method	Endpoint	Description	Status
POST	/api/p-2-p-conditions	Create new condition	201
PUT	/api/p-2-p-conditions/{id}	Full update	200
PATCH	/api/p-2-p-conditions/{id}	Partial update	200
GET	/api/p-2-p-conditions	Get all with criteria	200
GET	/api/p-2-p-conditions/{id}	Get by ID	200
GET	/api/p-2-p-conditions/count	Count by criteria	200
DELETE	/api/p-2-p-conditions/{id}	Delete condition	204

---

Field Specifications

Field	Type	Required	Max/Range	DB Column	Description
id	Long	❌ Auto	-	id	Primary key
value	String	❌	-	value	Unique condition value
description	String	❌	-	description	Human-readable description

P2pConditionCriteria

[!note] Query Criteria Used for filtering and searching P2P conditions.

public class P2pConditionCriteria {
    private LongFilter id;
    private StringFilter value;
    private StringFilter description;
}

Available Filters:

• id.equals, id.in, id.greaterThan, id.lessThan

• value.equals, value.contains, value.specified

• description.equals, description.contains, description.specified

Audit Fields (Inherited)

[!success] Auto-managed These fields are automatically populated by the system.

Field	Type	Description
createdBy	String	Creator username
createdDate	Instant	Creation timestamp
lastModifiedBy	String	Last modifier
lastModifiedDate	Instant	Last modification

---

API Endpoints

Create P2P Condition

POST /api/p-2-p-conditions

Creates a new P2P condition entity.

Request

Headers:

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

Body:

{
  "value": "HUMO_DOMESTIC",
  "description": "Condition for domestic HUMO card transactions"
}

[!warning] Validation Rules

• id must be null (auto-generated)

• value should be unique

• Both fields are optional but recommended

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/p-2-p-conditions/1

{
  "id": 1,
  "value": "HUMO_DOMESTIC",
  "description": "Condition for domestic HUMO card transactions",
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T10:30:00Z"
}

❌ Error (400 - Has ID):

{
  "status": 400,
  "detail": "A new p2pCondition cannot already have an ID",
  "message": "error.cannot.have.id"
}

---

Update P2P Condition

PUT /api/p-2-p-conditions/{id}

Completely updates an existing P2P condition.

Path Parameters

• id (Long) - P2P condition identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "value": "HUMO_DOMESTIC_UPDATED",
  "description": "Updated condition for domestic HUMO transactions"
}

[!warning] Validation

• Body id must not be null

• Path id must match body id

• P2P condition must exist in database

• value must remain unique

Response

✅ Success (200 OK):

{
  "id": 1,
  "value": "HUMO_DOMESTIC_UPDATED",
  "description": "Updated condition for domestic HUMO transactions",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T14:20:00Z"
}

❌ Errors:

Status	Detail	Message
400	Invalid id	error.not.null
400	Invalid ID	error.not.equal.id
400	Entity not found	error.entity.not.found

---

Partial Update

PATCH /api/p-2-p-conditions/{id}

Updates only specified fields. Null fields are ignored.

Path Parameters

• id (Long) - P2P condition identifier

Request

Headers:

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

Body (Example - update description only):

{
  "id": 1,
  "description": "New description for the condition"
}

Body (Example - update value only):

{
  "id": 1,
  "value": "NEW_VALUE"
}

[!tip] Partial Update Behavior

• Only non-null fields are updated

• Other fields remain unchanged

• Perfect for single field updates

• Value uniqueness is still enforced

Response

✅ Success (200 OK):

{
  "id": 1,
  "value": "HUMO_DOMESTIC_UPDATED",
  "description": "New description for the condition",
  "lastModifiedDate": "2024-01-29T15:45:00Z"
}

---

Get All P2P Conditions

GET /api/p-2-p-conditions

Retrieves paginated list with filtering criteria.

Query Parameters

Pagination:

• page - Page number (0-indexed, default: 0)

• size - Items per page (default: 20)

• sort - Sort criteria (e.g., value,asc)

• unPaged - Boolean for unpaged results

Filters (P2pConditionCriteria):

• id.equals, id.in, id.greaterThan, id.lessThan

• value.equals, value.contains, value.specified

• description.equals, description.contains, description.specified

Example Requests

GET /api/p-2-p-conditions?page=0&size=10&sort=value,asc
GET /api/p-2-p-conditions?value.contains=HUMO
GET /api/p-2-p-conditions?description.contains=domestic
GET /api/p-2-p-conditions?value.specified=true
GET /api/p-2-p-conditions?unPaged=true

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 15
Link: </api/p-2-p-conditions?page=0&size=20>; rel="first",
      </api/p-2-p-conditions?page=1&size=20>; rel="next"

[
  {
    "id": 1,
    "value": "HUMO_DOMESTIC",
    "description": "Condition for domestic HUMO card transactions",
    "createdBy": "admin",
    "createdDate": "2024-01-29T10:30:00Z"
  },
  {
    "id": 2,
    "value": "UZCARD_DOMESTIC",
    "description": "Condition for domestic UZCARD transactions",
    "createdBy": "admin",
    "createdDate": "2024-01-29T11:00:00Z"
  },
  {
    "id": 3,
    "value": "VISA_INTERNATIONAL",
    "description": "Condition for international VISA transactions",
    "createdBy": "admin",
    "createdDate": "2024-01-29T12:00:00Z"
  }
]

---

Get Single P2P Condition

GET /api/p-2-p-conditions/{id}

Retrieves a single P2P condition by ID.

Path Parameters

• id (Long) - P2P condition identifier

Request

GET /api/p-2-p-conditions/1
Authorization: Bearer {token}

Response

✅ Success (200 OK):

{
  "id": 1,
  "value": "HUMO_DOMESTIC",
  "description": "Condition for domestic HUMO card transactions",
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T10:30:00Z"
}

❌ Error (404 Not Found):

{
  "status": 404,
  "detail": "P2P condition not found with id: 999"
}

---

Count P2P Conditions

GET /api/p-2-p-conditions/count

Returns count of P2P conditions matching criteria.

Query Parameters

Same filtering parameters as [[#Get All P2P Conditions]]

Example Requests

GET /api/p-2-p-conditions/count
GET /api/p-2-p-conditions/count?value.contains=HUMO
GET /api/p-2-p-conditions/count?description.contains=domestic
GET /api/p-2-p-conditions/count?value.specified=true

Response

✅ Success (200 OK):

15

---

Delete P2P Condition

DELETE /api/p-2-p-conditions/{id}

Permanently deletes a P2P condition from the database.

Path Parameters

• id (Long) - P2P condition identifier

Request

DELETE /api/p-2-p-conditions/1
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

[!danger] Delete Warning Permanently deletes:

• P2P condition entity

• May fail if condition is referenced by P2P parameters

• Check dependencies before deletion

Use with caution! This cannot be undone.

---

Examples

Example 1: Create Card Type Conditions

• Setup Card Type Conditions Request - HUMO Condition:

curl -X POST http://localhost:8080/api/p-2-p-conditions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "value": "HUMO_CARDS",
    "description": "Matches all HUMO card numbers starting with 9860"
  }'

Request - UZCARD Condition:

curl -X POST http://localhost:8080/api/p-2-p-conditions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "value": "UZCARD_CARDS",
    "description": "Matches all UZCARD card numbers starting with 8600"
  }'

Example 2: Create Amount-Based Conditions

• Setup Amount Ranges Request - Small Transactions:

curl -X POST http://localhost:8080/api/p-2-p-conditions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "value": "SMALL_AMOUNT",
    "description": "Transactions under 1,000,000 UZS"
  }'

Request - Large Transactions:

curl -X POST http://localhost:8080/api/p-2-p-conditions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "value": "LARGE_AMOUNT",
    "description": "Transactions over 10,000,000 UZS"
  }'

Example 3: Update Condition Description

• Update Description Request:

curl -X PATCH http://localhost:8080/api/p-2-p-conditions/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "description": "Updated: Matches HUMO cards for domestic transfers"
  }'

Response:

{
  "id": 1,
  "value": "HUMO_CARDS",
  "description": "Updated: Matches HUMO cards for domestic transfers",
  "lastModifiedDate": "2024-01-29T17:30:12.456Z"
}

Example 4: Search by Value

• Find Conditions Request:

curl -X GET "http://localhost:8080/api/p-2-p-conditions?value.contains=HUMO&sort=value,asc" \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": 1,
    "value": "HUMO_CARDS",
    "description": "Matches all HUMO card numbers"
  },
  {
    "id": 5,
    "value": "HUMO_DOMESTIC",
    "description": "HUMO domestic transfers"
  }
]

---

Error Handling

Error Response Format

[!failure] RFC 7807 Problem Details All errors follow standardized format.

{
  "type": "https://www.jhipster.tech/problem/{error-type}",
  "title": "Error Title",
  "status": 400,
  "detail": "Detailed error message",
  "path": "/api/p-2-p-conditions",
  "message": "error.code",
  "params": "additionalInfo"
}

HTTP Status Codes

Code	Type	Description	Common Causes
400	Bad Request	Invalid request	Validation failure, ID mismatch
401	Unauthorized	Auth required	Missing/invalid token
403	Forbidden	Access denied	Insufficient permissions
404	Not Found	Resource missing	Invalid ID, deleted entity
409	Conflict	Resource conflict	Duplicate value
500	Server Error	Internal error	Database error, foreign key conflict

Validation Error Example

[!bug] Field Validation Errors

{
  "type": "https://www.jhipster.tech/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "path": "/api/p-2-p-conditions",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "p2pCondition",
      "field": "value",
      "message": "must be unique"
    }
  ]
}

---

Validation Rules

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"cannot.have.id"
id	Not null for PUT/PATCH	"not.null"
value	Unique (recommended)	"value already exists"

Business Rules

[!info] Business Validation

• value should be unique across all conditions

• value typically contains identifiers or patterns (e.g., card prefixes, amount ranges)

• description provides human-readable explanation of the condition

• Conditions are referenced by P2P parameters for transaction routing

• Deleting a condition may fail if it's used by active P2P parameters

---

Business Logic

Condition Usage in P2P Routing

[!info] How Conditions Work

P2P conditions are used by P2P parameters to match transactions:

P2P Parameter
├── Sender Condition (e.g., "HUMO_CARDS")
└── Recipient Condition (e.g., "UZCARD_CARDS")

Matching Process:

1. Transaction arrives with sender/recipient details

2. System checks all active P2P parameters

3. Each parameter's conditions are evaluated

4. First matching parameter (by priority) is selected

5. Transaction routed according to selected parameter

Common Condition Types

[!tip] Typical Condition Categories

Card Type Conditions:

• HUMO_CARDS - HUMO card numbers (9860****)

• UZCARD_CARDS - UZCARD card numbers (8600****)

• VISA_CARDS - VISA card numbers (4****)

• MASTERCARD_CARDS - MasterCard numbers (5****)

Condition Value Format

[!note] Recommended Format

{CATEGORY}_{SUBCATEGORY}_{DETAIL}

Examples:
- ^9860
- ^8600

---

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/p-2-p-conditions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "value": "NEW_CONDITION",
    "description": "Description of the new condition"
  }'

Update

curl -X PUT http://localhost:8080/api/p-2-p-conditions/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "value": "UPDATED_CONDITION",
    "description": "Updated description"
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/p-2-p-conditions/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "description": "New description"}'

Get All

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

Get Single

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

Count

curl -X GET "http://localhost:8080/api/p-2-p-conditions/count?value.contains=HUMO" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

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

---

📝 Use Cases

Use Case 1: Setup Card Type Routing

Scenario: Configure conditions to route transactions based on card types.

Implementation:

1. Create condition for HUMO cards

2. Create condition for UZCARD cards

3. Use conditions in P2P parameters for routing

---

---