P2p commission
[!info] Overview The P2P Commission REST API manages commission rules for peer-to-peer payment transactions in the pkbillms billing system. P2P commissions define fee structures, transaction amount ranges, and percentage-based charges that are applied to P2P transfers.
📋 Table of Contents
Quick Reference
[!abstract] API Configuration
Base URL:
/apiEntity Name:
pkbillmsP2PCommissionController:
P2pCommissionResourceFramework: Spring Boot + JHipster
Auth: Required (Spring Security)
Content-Type:
application/json
Endpoints Summary
POST
/api/p-2-p-commissions
Create new commission
201
POST
/api/p-2-p-commissions/v1
Create (versioned)
201
PUT
/api/p-2-p-commissions/{id}
Full update
200
PUT
/api/p-2-p-commissions/v1/{id}
Full update (versioned)
200
PATCH
/api/p-2-p-commissions/{id}
Partial update
200
GET
/api/p-2-p-commissions
Get all with criteria
200
GET
/api/p-2-p-commissions/{id}
Get by ID
200
GET
/api/p-2-p-commissions/count
Count by criteria
200
DELETE
/api/p-2-p-commissions/{id}
Delete commission
204
Data Models
Field Specifications
id
Long
❌ Auto
-
Primary key
name
String
✅
-
Unique commission name
commissionDetails
String
❌
-
JSON string for detailed commission
fromAmount
Long
❌
-
Minimum transaction amount
toAmount
Long
❌
-
Maximum transaction amount
up
Double
❌
0-100
Commission added on top (percentage)
down
Double
❌
0-100
Commission deducted from amount (%)
fee
Double
❌
0-100
Service fee (percentage)
description
String
❌
-
Commission description
commissionPartGroup
Object
❌
-
Associated commission part group
P2pCommissionDTO
[!note] Data Transfer Object Used for API responses and data exchange.
P2pCommissionCriteria
[!note] Query Criteria Used for filtering and searching P2P commissions.
Available Filters:
id.equals,id.in,id.greaterThan,id.lessThanname.equals,name.contains,name.specifiedfromAmount.equals,fromAmount.greaterThan,fromAmount.lessThantoAmount.equals,toAmount.greaterThan,toAmount.lessThanup.equals,up.greaterThan,up.lessThandown.equals,down.greaterThan,down.lessThanfee.equals,fee.greaterThan,fee.lessThan
Audit Fields (Inherited)
[!success] Auto-managed These fields are automatically populated by the system.
createdBy
String
Creator username
createdDate
Instant
Creation timestamp
lastModifiedBy
String
Last modifier
lastModifiedDate
Instant
Last modification
API Endpoints
Create P2P Commission
POST
/api/p-2-p-commissionsor/api/p-2-p-commissions/v1Creates a new P2P commission rule.
Request
Headers:
Body:
[!warning] Validation Rules
idmust be null (auto-generated)
namemust be unique
nameis required
up,down,feemust be between 0 and 100
Response
✅ Success (201 Created):
❌ Error (400 - Has ID):
❌ Error (400 - Duplicate Name):
Update P2P Commission
PUT
/api/p-2-p-commissions/{id}or/api/p-2-p-commissions/v1/{id}Completely updates an existing P2P commission.
Path Parameters
id(Long) - P2P commission identifier
Request
Headers:
Body:
[!warning] Validation
Body
idmust not be nullPath
idmust match bodyidP2P commission must exist in database
namemust remain unique (excluding current record)
up,down,feemust be between 0 and 100
Response
✅ Success (200 OK):
❌ Errors:
400
Invalid id
error.not.null
400
ID mismatch
error.not.equal.id
400
Entity not found
error.entity.not.found
400
Duplicate name
error.existed.name
Partial Update
PATCH
/api/p-2-p-commissions/{id}Updates only specified fields. Null fields are ignored.
Path Parameters
id(Long) - P2P commission identifier
Request
Headers:
Body (Example - update fee only):
Body (Example - update description and up):
[!tip] Partial Update Behavior
Only non-null fields are updated
Other fields remain unchanged
Perfect for single field updates
Name uniqueness is still enforced
Percentage validations still apply (0-100)
Response
✅ Success (200 OK):
Get All P2P Commissions
GET
/api/p-2-p-commissionsRetrieves 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.,name,asc)unPaged- Boolean for unpaged results
Filters (P2pCommissionCriteria):
id.equals,id.in,id.greaterThan,id.lessThanname.equals,name.contains,name.specifiedfromAmount.equals,fromAmount.greaterThan,fromAmount.lessThantoAmount.equals,toAmount.greaterThan,toAmount.lessThanup.equals,up.greaterThan,up.lessThandown.equals,down.greaterThan,down.lessThanfee.equals,fee.greaterThan,fee.lessThan
Example Requests
Response
✅ Success (200 OK):
Get Single P2P Commission
GET
/api/p-2-p-commissions/{id}Retrieves a single P2P commission by ID.
Path Parameters
id(Long) - P2P commission identifier
Request
Response
✅ Success (200 OK):
❌ Error (404 Not Found):
Count P2P Commissions
GET
/api/p-2-p-commissions/countReturns the count of P2P commissions matching criteria.
Query Parameters
Same filters as "Get All P2P Commissions"
Example Requests
Response
✅ Success (200 OK):
Delete P2P Commission
DELETE
/api/p-2-p-commissions/{id}Deletes a P2P commission if not related to any commission part group.
Path Parameters
id(Long) - P2P commission identifier
Request
Response
✅ Success (204 No Content):
❌ Error (400 - Related to Group):
[!danger] Delete Warning Permanently deletes:
P2P commission entity
Cannot delete if commission is associated with a commission part group
Check group relationships before deletion
Use with caution! This cannot be undone.
Examples
Example 1: Create Tiered Commission Structure
Setup Commission Tiers Request - Small Transactions:
Request - Medium Transactions:
Request - Large Transactions:
Example 2: Create Commission with Deduction
Commission Deducted from Amount Request:
Example 3: Update Commission Rates
Adjust Commission Percentages Request:
Response:
Example 4: Search by Amount Range
Find Commissions for Amount Range Request:
Response:
Example 5: Check Commission Count
Count Active Commissions Request:
Response:
Error Handling
Error Response Format
[!failure] RFC 7807 Problem Details All errors follow standardized format.
HTTP Status Codes
201
Created
Resource created
Successful POST
200
OK
Success
Successful GET/PUT/PATCH
204
No Content
Deleted
Successful DELETE
400
Bad Request
Invalid request
Validation failure, ID mismatch, duplicate name
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 name
500
Server Error
Internal error
Database error, foreign key constraint
Validation Error Examples
[!bug] Field Validation Errors
Duplicate Name:
Invalid Percentage Range:
Related to Group Error:
Validation Rules
Field Constraints
id
Null for POST
"cannot.have.id"
id
Not null for PUT/PATCH
"not.null"
id
Must match path ID
"not.equal.id"
name
Required
"name is required"
name
Must be unique
"existed.name"
up
0 ≤ value ≤ 100
"must be between 0 and 100"
down
0 ≤ value ≤ 100
"must be between 0 and 100"
fee
0 ≤ value ≤ 100
"must be between 0 and 100"
fromAmount
Optional
-
toAmount
Optional
-
commissionDetails
Optional (JSON format)
-
description
Optional
-
Business Rules
[!info] Business Validation
namemust be unique across all commissions
fromAmountdefines the minimum transaction amount for this commission
toAmountdefines the maximum transaction amount for this commission
upis commission added on top of the transaction amount (percentage)
downis commission deducted from the transaction amount (percentage)
feeis an additional service fee (percentage)
commissionDetailsstores JSON string with additional configurationCannot delete commission if it's associated with a commission part group
All percentage fields (
up,down,fee) must be between 0 and 100
Business Logic
Commission Structure
[!info] How Commissions Work
P2P commissions define the fee structure for peer-to-peer transfers:
Commission Types
[!tip] Three Commission Components
1. UP Commission (up):
Added on top of transaction amount
Sender pays more than the transaction amount
Example: 100,000 transfer with 2% up = 102,000 charged
2. DOWN Commission (down):
Deducted from transaction amount
Recipient receives less than the transaction amount
Example: 100,000 transfer with 2% down = 98,000 received
3. Service Fee (fee):
Additional flat percentage fee
Usually combined with up or down
Example: 100,000 transfer with 1% fee = 1,000 additional charge
Amount Range Matching
[!note] Transaction Routing
Commissions are selected based on transaction amount:
Commission Part Groups
[!info] Grouping Commissions
Commissions can be organized into groups:
Group Relationship:
A commission can belong to one commission part group
Groups organize related commissions together
Cannot delete commission if associated with a group
Groups are used in P2P parameters for routing
Commission Details JSON
[!note] Extended Configuration
The commissionDetails field stores JSON for additional settings:
Use Case Scenarios
Common Scenarios
Scenario 1: Standard Transfer
Amount: 100,000 UZS
Commission: up = 2.5%, fee = 1.0%
Total charged: 103,500 UZS
Scenario 2: Large Transfer (Lower Rate)
Amount: 5,000,000 UZS
Commission: up = 1.0%, fee = 0.5%
Total charged: 5,075,000 UZS
Scenario 3: Deduction Commission
Amount: 50,000 UZS
Commission: down = 3.0%
Recipient receives: 48,500 UZS
🔧 cURL Command Reference
Create
Create (Versioned)
Update
Partial Update
Get All
Get All (Filtered)
Get Single
Count
Delete
Last updated