P2p param

[!info] Overview The P2P Param REST API manages peer-to-peer payment parameters and routing configurations in the pkbillms billing system. P2P parameters define how transactions are routed between different payment processors, commission structures, limits, and conditions for sender and recipient parties.

📋 Table of Contents

• Quick Reference

• Data Models

• API Endpoints

• Request & Response Examples

• Error Handling

• Validation Rules

• Business Logic

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: pkbillmsP2PParam

• Controller: P2pParamResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

Method	Endpoint	Description	Status
POST	/api/p-2-p-params	Create P2P param (V1)	201
POST	/api/p-2-p-params/v1	Create P2P param (V1)	201
POST	/api/p-2-p-params/v2	Create P2P param (V2)	201
PUT	/api/p-2-p-params/{id}	Full update (V1)	200
PUT	/api/p-2-p-params/v1/{id}	Full update (V1)	200
PUT	/api/p-2-p-params/v2/{id}	Full update (V2)	200
PATCH	/api/p-2-p-params/{id}	Partial update	200
GET	/api/p-2-p-params	Get all with criteria	200
GET	/api/p-2-p-params/{id}	Get by ID	200
GET	/api/p-2-p-params/count	Count by criteria	200
DELETE	/api/p-2-p-params/{id}	Delete P2P param	204
POST	/api/p-2-p-params/info	Get P2P info by request	200
GET	/api/p-2-p-params/types	Get all payment types	200

---

Data Models

Field Specifications

Field	Type	Required	Max/Range	Description
id	Long	❌ Auto	-	Primary key
priority	Integer	✅	-	Routing priority
active	Boolean	✅	-	Active/Inactive status
senderPc	P2pProcessorType	✅	ENUM	Sender payment processor
recipientPc	P2pProcessorType	✅	ENUM	Recipient payment processor
value	String	❌	LOB	JSON configuration parameters
name	String	❌	64	Parameter name
senderCondition	P2pCondition	✅	-	Sender matching condition
recipientCondition	P2pCondition	✅	-	Recipient matching condition
senderPercent	P2pCommissionDTO	❌	-	Sender commission config
recipientPercent	P2pCommissionDTO	❌	-	Recipient commission config
senderCommissionGroup	P2pCommissionGroupDTO	❌	-	Sender commission group
recipientCommissionGroup	P2pCommissionGroupDTO	❌	-	Recipient commission group
p2pLimit	P2pLimit	❌	-	Transaction limits
promo	String	❌	128	Promotional code

P2pProcessorType Enum

public enum P2pProcessorType {
    HUMO,
    UZCARD,
    VISA,
    SQB_WAY4,
    SQB_ABS,
    MASTERCARD,
}

Audit Fields (Inherited)

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

---

API Endpoints

Create P2P Param V1

POST /api/p-2-p-params or /api/p-2-p-params/v1

Creates a new P2P parameter configuration using V1 format.

Request Body:

{
  "priority": 1,
  "active": true,
  "senderPc": "HUMO",
  "recipientPc": "UZCARD",
  "name": "HUMO to UZCARD Transfer",
  "value": "{\"timeout\": 30, \"retries\": 3}",
  "senderConditionId": 1,
  "recipientConditionId": 2,
  "senderPercentId": 5,
  "recipientPercentId": 6,
  "p2pLimitId": 15,
  "promo": "PROMO2024"
}

Response (201 Created):

{
  "id": 1,
  "priority": 1,
  "active": true,
  "senderPc": "HUMO",
  "recipientPc": "UZCARD",
  "name": "HUMO to UZCARD Transfer",
  "createdDate": "2024-01-29T10:30:00Z"
}

---

Create P2P Param V2

POST /api/p-2-p-params/v2

Creates a new P2P parameter using V2 format with enhanced features.

Request Body:

{
  "priority": 2,
  "active": true,
  "senderPc": "VISA",
  "recipientPc": "MASTERCARD",
  "name": "VISA to MASTERCARD International",
  "senderConditionId": 3,
  "recipientConditionId": 4,
  "p2pLimitId": 16
}

---

Update P2P Param V1

PUT /api/p-2-p-params/{id} or /api/p-2-p-params/v1/{id}

Updates existing P2P parameter using V1 format.

Path Parameters: id (Long)

Request Body:

{
  "id": 1,
  "priority": 1,
  "active": true,
  "senderPc": "HUMO",
  "recipientPc": "UZCARD",
  "name": "Updated HUMO to UZCARD",
  "senderConditionId": 1,
  "recipientConditionId": 2
}

---

Update P2P Param V2

PUT /api/p-2-p-params/v2/{id}

Updates existing P2P parameter using V2 format.

---

Partial Update

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

Updates only specified fields.

Request Body (toggle active):

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

Request Body (update priority):

{
  "id": 1,
  "priority": 5,
  "promo": "NEWPROMO2024"
}

---

Get All P2P Params

GET /api/p-2-p-params

Retrieves paginated list with filtering.

Query Parameters:

• page - Page number (default: 0)

• size - Page size (default: 20)

• sort - Sort criteria

• priority.equals, priority.greaterThan

• active.equals

• senderPc.equals, senderPc.in

• recipientPc.equals

• name.contains

Example Requests:

GET /api/p-2-p-params?active.equals=true
GET /api/p-2-p-params?senderPc.equals=HUMO&recipientPc.equals=UZCARD
GET /api/p-2-p-params?priority.greaterThan=5&sort=priority,asc

Response (200 OK):

[
  {
    "id": 1,
    "priority": 1,
    "active": true,
    "senderPc": "HUMO",
    "recipientPc": "UZCARD",
    "name": "HUMO to UZCARD Transfer"
  }
]

---

Get Single P2P Param

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

Retrieves single P2P parameter by ID.

Response (200 OK):

{
  "id": 1,
  "priority": 1,
  "active": true,
  "senderPc": "HUMO",
  "recipientPc": "UZCARD",
  "name": "HUMO to UZCARD Transfer",
  "value": "{\"timeout\": 60}",
  "senderCondition": {...},
  "recipientCondition": {...},
  "p2pLimit": {...},
  "createdDate": "2024-01-29T10:30:00Z"
}

---

Count P2P Params

GET /api/p-2-p-params/count

Returns count matching criteria.

Example:

GET /api/p-2-p-params/count?active.equals=true

Response: 25

---

Delete P2P Param

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

Permanently deletes P2P parameter.

Response: 204 No Content

---

Get P2P Param Info

POST /api/p-2-p-params/info

Retrieves P2P parameter info based on transaction details.

Request Body:

{
  "senderCardNumber": "9860123456789012",
  "recipientCardNumber": "8600987654321098",
  "amount": 500000,
  "currency": "UZS"
}

Response (200 OK):

{
  "p2pParam": {
    "id": 1,
    "priority": 1,
    "senderPc": "HUMO",
    "recipientPc": "UZCARD"
  },
  "calculatedCommission": 7500,
  "availableLimit": 9500000,
  "message": "Match found"
}

---

Get Pay Types

GET /api/p-2-p-params/types

Returns all payment processor types.

Response (200 OK):

["HUMO", "UZCARD", "VISA", "MASTERCARD", "MIR", "UNION_PAY"]

---

Examples

Example 1: Create Domestic Route

curl -X POST http://localhost:8080/api/p-2-p-params/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "priority": 1,
    "active": true,
    "senderPc": "HUMO",
    "recipientPc": "UZCARD",
    "name": "Domestic Transfer",
    "senderConditionId": 1,
    "recipientConditionId": 2,
    "p2pLimitId": 10
  }'

Example 2: Query Route

curl -X POST http://localhost:8080/api/p-2-p-params/info \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "senderCardNumber": "9860123456789012",
    "recipientCardNumber": "8600987654321098",
    "amount": 500000
  }'

Example 3: Toggle Active Status

curl -X PATCH http://localhost:8080/api/p-2-p-params/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"id": 1, "active": false}'

---

Error Handling

Error Response Format

{
  "type": "https://www.jhipster.tech/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "detail": "Detailed error message",
  "message": "error.validation"
}

HTTP Status Codes

Code	Type	Description	Common Causes
400	Bad Request	Invalid request	Validation failure
401	Unauthorized	Auth required	Missing token
404	Not Found	Resource missing	Invalid ID
500	Server Error	Internal error	Database error

---

Validation Rules

Required Fields

[!check] Mandatory Fields

• ✅ priority - Routing priority

• ✅ active - Active status

• ✅ senderPc - Sender processor

• ✅ recipientPc - Recipient processor

• ✅ senderCondition - Sender condition (via ID)

• ✅ recipientCondition - Recipient condition (via ID)

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"cannot.have.id"
id	Not null for PUT/PATCH	"not.null"
priority	@NotNull	"must not be null"
active	@NotNull	"must not be null"
senderPc	@NotNull, ENUM	"must not be null"
recipientPc	@NotNull, ENUM	"must not be null"
name	@Size(max=64)	"size must be 0 to 64"
promo	@Size(max=128)	"size must be 0 to 128"

---

Business Logic

Priority Routing

[!info] How Priority Works When multiple P2P params match a transaction:

1. System filters by active status

2. Matches sender/recipient conditions

3. Sorts by priority (lower = higher priority)

4. Returns first match

Commission Calculation

Total Commission = Sender Commission + Recipient Commission

Limit Validation

System checks:

• Minimum amount

• Maximum amount

• Daily limit

• Monthly limit

---

🔧 cURL Commands

Create

curl -X POST http://localhost:8080/api/p-2-p-params \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{...}'

Update

curl -X PUT http://localhost:8080/api/p-2-p-params/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{...}'

Partial Update

curl -X PATCH http://localhost:8080/api/p-2-p-params/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"id": 1, "active": false}'

Get All

curl -X GET "http://localhost:8080/api/p-2-p-params?active.equals=true" \
  -H "Authorization: Bearer TOKEN"

Delete

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

---

---