P2p commission part

[!info] Overview The P2P Commission Part REST API manages individual commission parts in the BMMS billing system. Commission parts define the components of transaction fees, including fixed amounts and percentage-based charges that can be combined into commission groups.

📋 Table of Contents

Quick Reference

[!abstract] API Configuration
Base URL: /api
Entity Name: P2PCommissionPart
Controller: P2pCommissionPartResource
Framework: Spring Boot + JHipster
Auth: Required (Spring Security)
Content-Type: application/json

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/p-2-p-commission-parts

Create new commission part

201

PUT

/api/p-2-p-commission-parts/{id}

Full update

200

PATCH

/api/p-2-p-commission-parts/{id}

Partial update

200

GET

/api/p-2-p-commission-parts

Get all with criteria

200

GET

/api/p-2-p-commission-parts/{id}

Get by ID

200

GET

/api/p-2-p-commission-parts/count

Count by criteria

200

DELETE

/api/p-2-p-commission-parts/{id}

Delete commission part

204

DELETE

/api/p-2-p-commission-parts/{partId}/{groupId}

Delete part from specific group

204

Data Models

P2pCommissionPartDTO Structure

[!note] Data Transfer Object Represents a commission part with amount and calculation type.

@Accessors(chain = true)
public class P2pCommissionPartDTO {
    private Long id;
    private String name;                          // Part name (unique)
    private String description;                   // Optional description
    private BigDecimal amount;                    // Amount (percent or fixed)
    private CommMultiplierType commMultiplierType;// Calculation type
    private String partDetails;                   // Additional details
    private String code;                          // Part code (max 16 chars)
    private Boolean isResidualReceiver;           // Residual receiver flag
}

Field Specifications

Field

Type

Required

Max/Range

DB Column

Description

id

Long

❌ Auto

Primary key

name

String

✅

name

Part name (unique)

description

String

❌

description

Optional description

amount

BigDecimal

✅

amount

Commission amount

commMultiplierType

CommMultiplierType

✅

ENUM

comm_multiplier_type

Calculation type

partDetails

String

❌

part_details

Additional details

code

String

❌

code

Part code (alphanumeric)

isResidualReceiver

Boolean

❌

is_residual_receiver

Residual receiver flag

CommMultiplierType Enum

[!info] Commission Calculation Types Defines how the commission amount is applied.

public enum CommMultiplierType {
    PERCENT,      // Percentage-based (e.g., 0.1% = 0.001)
    FIXED         // Fixed amount (e.g., 1000 UZS)
}

Usage Examples:

PERCENT with amount = 1.5 → 1.5% of transaction
FIXED with amount = 1000 → 1000 UZS fixed fee

API Endpoints

Create Commission Part

POST /api/p-2-p-commission-parts
Creates a new commission part entity.

Request

Headers:

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

Body:

{
  "name": "Transaction Fee",
  "description": "Standard transaction processing fee",
  "amount": 1.5,
  "commMultiplierType": "PERCENT",
  "partDetails": "Applied to all P2P transactions",
  "code": "TXN_FEE",
  "isResidualReceiver": false
}

[!warning] Validation Rules
id must be null (auto-generated)
name must be non-empty and unique
amount must be non-null
commMultiplierType must be non-null (PERCENT or FIXED)
code must match pattern ^[a-zA-Z0-9]{1,15}$ (max 16 chars)

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/p-2-p-commission-parts/1
X-bmmsP2PCommissionPart-alert: bmmsP2PCommissionPart.created
X-bmmsP2PCommissionPart-params: 1

{
  "id": 1,
  "name": "Transaction Fee",
  "description": "Standard transaction processing fee",
  "amount": 1.5,
  "commMultiplierType": "PERCENT",
  "partDetails": "Applied to all P2P transactions",
  "code": "TXN_FEE",
  "isResidualReceiver": false
}

❌ Error (400 - Name exists):

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Commission part with this name already exists",
  "entityName": "bmmsP2PCommissionPart",
  "errorKey": "existed.name",
  "params": "name",
  "message": "error.existed.name"
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "title": "Bad Request",
  "detail": "A new commission part cannot already have an ID",
  "entityName": "bmmsP2PCommissionPart",
  "errorKey": "cannot.have.id",
  "params": "id",
  "message": "error.cannot.have.id"
}

Update Commission Part

PUT /api/p-2-p-commission-parts/{id}
Completely updates an existing commission part.

Path Parameters

id (Long) - Commission part identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "name": "Updated Transaction Fee",
  "description": "Updated description for transaction processing fee",
  "amount": 2.0,
  "commMultiplierType": "PERCENT",
  "partDetails": "Updated details",
  "code": "TXN_FEE_V2",
  "isResidualReceiver": false
}

[!warning] Validation
Body id must not be null
Path id must match body id
Commission part must exist in database
New name must be unique (if changed)

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-bmmsP2PCommissionPart-alert: bmmsP2PCommissionPart.updated
X-bmmsP2PCommissionPart-params: 1

{
  "id": 1,
  "name": "Updated Transaction Fee",
  "description": "Updated description for transaction processing fee",
  "amount": 2.0,
  "commMultiplierType": "PERCENT",
  "partDetails": "Updated details",
  "code": "TXN_FEE_V2",
  "isResidualReceiver": false
}

❌ 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

400

Name already exists

error.existed.name

Partial Update Commission Part

PATCH /api/p-2-p-commission-parts/{id}
Updates only specified fields. Null fields are ignored.

Path Parameters

id (Long) - Commission part identifier

Request

Headers:

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

Body (Example - update only amount):

{
  "id": 1,
  "amount": 2.5
}

Body (Example - update name and description):

{
  "id": 1,
  "name": "Premium Transaction Fee",
  "description": "Premium tier processing fee"
}

[!tip] Partial Update Behavior
Only non-null fields are updated
Other fields remain unchanged
Perfect for updating single fields without affecting others
Name uniqueness is validated if name is being changed

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-bmmsP2PCommissionPart-alert: bmmsP2PCommissionPart.updated
X-bmmsP2PCommissionPart-params: 1

{
  "id": 1,
  "name": "Premium Transaction Fee",
  "description": "Premium tier processing fee",
  "amount": 2.5,
  "commMultiplierType": "PERCENT",
  "partDetails": "Applied to all P2P transactions",
  "code": "TXN_FEE",
  "isResidualReceiver": false
}

Get All Commission Parts

GET /api/p-2-p-commission-parts
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., name,asc)
unPaged - Boolean for unpaged results

Filters (P2pCommissionPartCriteria):

id.equals, id.in
name.contains, name.equals
code.equals, code.contains
commMultiplierType.equals - Filter by type
isResidualReceiver.equals - Filter by residual flag

Example Requests

GET /api/p-2-p-commission-parts?page=0&size=10&sort=name,asc
GET /api/p-2-p-commission-parts?name.contains=Transaction
GET /api/p-2-p-commission-parts?commMultiplierType.equals=PERCENT
GET /api/p-2-p-commission-parts?code.equals=TXN_FEE

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "name": "Transaction Fee",
    "description": "Standard transaction processing fee",
    "amount": 1.5,
    "commMultiplierType": "PERCENT",
    "partDetails": "Applied to all P2P transactions",
    "code": "TXN_FEE",
    "isResidualReceiver": false
  },
  {
    "id": 2,
    "name": "Service Charge",
    "description": "Standard service charge",
    "amount": 500.0,
    "commMultiplierType": "FIXED",
    "partDetails": "Fixed service fee",
    "code": "SVC_CHG",
    "isResidualReceiver": false
  },
  {
    "id": 3,
    "name": "Platform Fee",
    "description": "Platform usage fee",
    "amount": 0.3,
    "commMultiplierType": "PERCENT",
    "partDetails": "Platform commission",
    "code": "PLT_FEE",
    "isResidualReceiver": true
  }
]

Get Single Commission Part

GET /api/p-2-p-commission-parts/{id}
Retrieves a single commission part by ID with all relationships.

Path Parameters

id (Long) - Commission part identifier

Request

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

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Transaction Fee",
  "description": "Standard transaction processing fee",
  "amount": 1.5,
  "commMultiplierType": "PERCENT",
  "partDetails": "Applied to all P2P transactions",
  "code": "TXN_FEE",
  "isResidualReceiver": false
}

❌ Error (404 Not Found):

{
  "status": 404,
  "detail": "Commission part not found with id: 999"
}

Count Commission Parts

GET /api/p-2-p-commission-parts/count
Returns count of commission parts matching criteria.

Query Parameters

Same filtering parameters as [[#Get All Commission Parts]]

Example Requests

GET /api/p-2-p-commission-parts/count
GET /api/p-2-p-commission-parts/count?commMultiplierType.equals=PERCENT
GET /api/p-2-p-commission-parts/count?name.contains=Fee
GET /api/p-2-p-commission-parts/count?isResidualReceiver.equals=true

Response

✅ Success (200 OK):

Delete Commission Part

DELETE /api/p-2-p-commission-parts/{id}
Deletes a commission part from the system.

Path Parameters

id (Long) - Commission part identifier

Request

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

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content
X-bmmsP2PCommissionPart-alert: bmmsP2PCommissionPart.deleted
X-bmmsP2PCommissionPart-params: 1

❌ Error (400 - Part is in use):

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Cannot delete commission part because it is referenced by commission groups",
  "entityName": "bmmsP2PCommissionPart",
  "errorKey": "related.to.group",
  "params": "id",
  "message": "P2pCommissionPart",
  "id": 1
}

[!danger] Deletion Constraint Warning A commission part cannot be deleted if:
It is referenced by any commission part group
The system performs this check before deletion:
int countP2pCommissionRelatedWithGroup = 
    p2pCommissionPartService.countCommissionPartRelatedWithGroup(id);
if (countP2pCommissionRelatedWithGroup == 0) {
    // Deletion allowed
} else {
    throw new BadRequestException("related.to.group", ...);
}
Workaround: Remove the part from all commission groups before attempting deletion.

Delete Commission Part from Group

DELETE /api/p-2-p-commission-parts/{partId}/{groupId}
Removes a specific commission part from a specific group.

Path Parameters

partId (Long) - Commission part identifier
groupId (Long) - Commission part group identifier

Request

DELETE /api/p-2-p-commission-parts/1/5
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content
X-bmmsP2PCommissionPart-alert: bmmsP2PCommissionPart.deleted
X-bmmsP2PCommissionPart-params: 1

[!info] Use Case This endpoint is useful for:
Removing a part from a specific group without deleting the part entirely
Maintaining the part for use in other groups
Precise group membership management

Examples

Example 1: Create Percentage-Based Commission Part

Setup Percentage Fee Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-parts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Transaction Fee",
    "description": "1.5% transaction processing fee",
    "amount": 1.5,
    "commMultiplierType": "PERCENT",
    "partDetails": "Applied to transaction amount",
    "code": "TXN_FEE",
    "isResidualReceiver": false
  }'

Example 2: Create Fixed Amount Commission Part

Setup Fixed Fee Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-parts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Service Charge",
    "description": "Fixed service charge per transaction",
    "amount": 1000.00,
    "commMultiplierType": "FIXED",
    "partDetails": "Flat fee charged per transaction",
    "code": "SVC_CHG",
    "isResidualReceiver": false
  }'

Example 3: Create Residual Receiver Part

Setup Residual Receiver Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-parts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Platform Residual Fee",
    "description": "Receives remaining commission after all parts",
    "amount": 100.0,
    "commMultiplierType": "PERCENT",
    "partDetails": "Residual commission receiver",
    "code": "RESIDUAL",
    "isResidualReceiver": true
  }'

Example 4: Update Commission Amount

Update Fee Amount Request:

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

Response:

{
  "id": 1,
  "name": "Transaction Fee",
  "description": "1.5% transaction processing fee",
  "amount": 2.0,
  "commMultiplierType": "PERCENT",
  "partDetails": "Applied to transaction amount",
  "code": "TXN_FEE",
  "isResidualReceiver": false
}

Example 5: Change Commission Type

[!example]- Convert from Percent to Fixed Request:

curl -X PUT http://localhost:8080/api/p-2-p-commission-parts/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "name": "Transaction Fee",
    "description": "Fixed transaction processing fee",
    "amount": 500.00,
    "commMultiplierType": "FIXED",
    "partDetails": "Changed from percentage to fixed amount",
    "code": "TXN_FEE",
    "isResidualReceiver": false
  }'

Example 6: Remove Part from Specific Group

[!example]- Remove from Group Request:

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

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-commission-parts",
  "message": "error.code",
  "entityName": "bmmsP2PCommissionPart",
  "errorKey": "error.key",
  "params": "additionalInfo"
}

HTTP Status Codes

Code

Type

Description

Common Causes

400

Bad Request

Invalid request

Validation failure, ID mismatch, duplicate name, part in use

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, exception

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-commission-parts",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "p2pCommissionPartDTO",
      "field": "name",
      "message": "must not be empty"
    },
    {
      "objectName": "p2pCommissionPartDTO",
      "field": "amount",
      "message": "P2pCommissionPart amount can not be null"
    },
    {
      "objectName": "p2pCommissionPartDTO",
      "field": "commMultiplierType",
      "message": "P2pCommissionPart multiplier type can not be null"
    },
    {
      "objectName": "p2pCommissionPartDTO",
      "field": "code",
      "message": "must match \"^[a-zA-Z0-9]{1,15}$\""
    }
  ]
}

Validation Rules

Required Fields

[!check] Mandatory Fields
✅ name - Part name (unique)
✅ amount - Commission amount
✅ commMultiplierType - Calculation type (PERCENT or FIXED)

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new commission part cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

name

@NotEmpty, Unique

"must not be empty", "name already exists"

description

Optional

amount

@NotNull

"P2pCommissionPart amount can not be null"

commMultiplierType

@NotNull, ENUM

"P2pCommissionPart multiplier type can not be null"

partDetails

Optional

code

@Size(max=16), @Pattern

"size must be between 0 and 16", "must match pattern"

isResidualReceiver

Optional

Code Pattern Validation

[!info] Code Field Rules
Pattern: ^[a-zA-Z0-9]{1,15}$
Max Length: 16 characters
Allowed Characters: Letters (a-z, A-Z) and numbers (0-9)
Examples:
✅ Valid: TXN_FEE, FEE123, COMMISSION1
❌ Invalid: TXN-FEE (contains hyphen), FEE_123 (contains underscore)

Business Rules

[!info] Business Validation
name must be globally unique across all commission parts
amount must be a valid positive number
commMultiplierType determines how amount is interpreted:
PERCENT: amount is percentage (e.g., 1.5 = 1.5%)
FIXED: amount is fixed sum (e.g., 1000 = 1000 UZS)
Commission part cannot be deleted if referenced by any group
Only one isResidualReceiver part recommended per configuration
code should be unique (recommended but not enforced)

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/p-2-p-commission-parts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Transaction Fee",
    "description": "Standard fee",
    "amount": 1.5,
    "commMultiplierType": "PERCENT",
    "code": "TXN_FEE"
  }'

Update

curl -X PUT http://localhost:8080/api/p-2-p-commission-parts/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "Updated Transaction Fee",
    "description": "Updated fee",
    "amount": 2.0,
    "commMultiplierType": "PERCENT",
    "code": "TXN_FEE_V2"
  }'

Partial Update

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

Get All

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

Get Single

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

Count

curl -X GET "http://localhost:8080/api/p-2-p-commission-parts/count?commMultiplierType.equals=PERCENT" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

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

Delete from Group

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

PreviousP2p condition NextP2p commission part group

Last updated 1 month ago

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagP2pCommissionPartDTO Structure

hashtagField Specifications

hashtagCommMultiplierType Enum

hashtagAPI Endpoints

hashtagCreate Commission Part

hashtagRequest

hashtagResponse

hashtagUpdate Commission Part

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagPartial Update Commission Part

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagGet All Commission Parts

hashtagQuery Parameters

hashtagExample Requests

hashtagResponse

hashtagGet Single Commission Part

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagCount Commission Parts

hashtagQuery Parameters

hashtagExample Requests

hashtagResponse

hashtagDelete Commission Part

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagDelete Commission Part from Group

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagExamples

hashtagExample 1: Create Percentage-Based Commission Part

hashtagExample 2: Create Fixed Amount Commission Part

hashtagExample 3: Create Residual Receiver Part

hashtagExample 4: Update Commission Amount

hashtagExample 5: Change Commission Type

hashtagExample 6: Remove Part from Specific Group

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Error Example

hashtagValidation Rules

hashtagRequired Fields

hashtagField Constraints

hashtagCode Pattern Validation

hashtagBusiness Rules

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet Single

hashtagCount

hashtagDelete

hashtagDelete from Group

📋 Table of Contents

Quick Reference

Endpoints Summary

Data Models

P2pCommissionPartDTO Structure

Field Specifications

CommMultiplierType Enum

API Endpoints

Create Commission Part

Request

Response

Update Commission Part

Path Parameters

Request

Response

Partial Update Commission Part

Path Parameters

Request

Response

Get All Commission Parts

Query Parameters

Example Requests

Response

Get Single Commission Part

Path Parameters

Request

Response

Count Commission Parts

Query Parameters

Example Requests

Response

Delete Commission Part

Path Parameters

Request

Response

Delete Commission Part from Group

Path Parameters

Request

Response

Examples

Example 1: Create Percentage-Based Commission Part

Example 2: Create Fixed Amount Commission Part

Example 3: Create Residual Receiver Part

Example 4: Update Commission Amount

Example 5: Change Commission Type

Example 6: Remove Part from Specific Group

Error Handling

Error Response Format

HTTP Status Codes

Validation Error Example

Validation Rules

Required Fields

Field Constraints

Code Pattern Validation

Business Rules

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get Single

Count

Delete

Delete from Group