P2p commission part group

[!info] Overview The P2P Commission Part Group REST API manages commission part groupings in the BMMS billing system. Groups enable organizing related commission parts for streamlined configuration and assignment in P2P commission structures.

📋 Table of Contents

Quick Reference

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

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/p-2-p-commission-part-groups

Create new commission part group

201

PUT

/api/p-2-p-commission-part-groups/{id}

Full update

200

PATCH

/api/p-2-p-commission-part-groups/{id}

Partial update

200

GET

/api/p-2-p-commission-part-groups

Get all with criteria

200

GET

/api/p-2-p-commission-part-groups/{id}

Get by ID

200

GET

/api/p-2-p-commission-part-groups/count

Count by criteria

200

DELETE

/api/p-2-p-commission-part-groups/{id}

Delete commission part group

204

Field Specifications

Field

Type

Required

Constraints

Description

id

Long

❌ Auto

Primary key

name

String

✅

Unique

Group name (unique identifier)

description

String

❌

Optional description

commissionParts

List

✅

NotNull

List of commission parts in group

API Endpoints

Create Commission Part Group

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

Request

Headers:

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

Body:

{
  "name": "Standard Processing Fees",
  "description": "Standard commission parts for processing P2P transactions",
  "commissionParts": [
    {
      "id": 1,
      "name": "Transaction Fee",
      "code": "TXN_FEE",
      "percentage": 1.5,
      "fixedAmount": 1000.00
    },
    {
      "id": 2,
      "name": "Service Charge",
      "code": "SVC_CHG",
      "percentage": 0.5,
      "fixedAmount": 500.00
    },
    {
      "id": 3,
      "name": "Platform Fee",
      "code": "PLT_FEE",
      "percentage": 0.3,
      "fixedAmount": 300.00
    }
  ]
}

[!warning] Validation Rules
id must be null (auto-generated)
name must be non-empty and unique
commissionParts must be non-null and contain valid commission part references
Commission parts must exist in the system

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/p-2-p-commission-part-groups/1

{
  "id": 1,
  "name": "Standard Processing Fees",
  "description": "Standard commission parts for processing P2P transactions",
  "commissionParts": [
    {
      "id": 1,
      "name": "Transaction Fee",
      "code": "TXN_FEE",
      "percentage": 1.5,
      "fixedAmount": 1000.00
    },
    {
      "id": 2,
      "name": "Service Charge",
      "code": "SVC_CHG",
      "percentage": 0.5,
      "fixedAmount": 500.00
    },
    {
      "id": 3,
      "name": "Platform Fee",
      "code": "PLT_FEE",
      "percentage": 0.3,
      "fixedAmount": 300.00
    }
  ]
}

❌ Error (400 - Name exists):

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

Update Commission Part Group

[!example] PUT /api/p-2-p-commission-part-groups/{id} Completely updates an existing commission part group.

Path Parameters

id (Long) - Commission part group identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "name": "Updated Standard Processing Fees",
  "description": "Updated description for standard processing fees",
  "commissionParts": [
    {
      "id": 1,
      "name": "Transaction Fee",
      "code": "TXN_FEE",
      "percentage": 2.0,
      "fixedAmount": 1500.00
    },
    {
      "id": 4,
      "name": "New Platform Fee",
      "code": "NEW_PLT_FEE",
      "percentage": 0.4,
      "fixedAmount": 400.00
    }
  ]
}

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

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Updated Standard Processing Fees",
  "description": "Updated description for standard processing fees",
  "commissionParts": [
    {
      "id": 1,
      "name": "Transaction Fee",
      "code": "TXN_FEE",
      "percentage": 2.0,
      "fixedAmount": 1500.00
    },
    {
      "id": 4,
      "name": "New Platform Fee",
      "code": "NEW_PLT_FEE",
      "percentage": 0.4,
      "fixedAmount": 400.00
    }
  ]
}

❌ 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 Group

[!example] PATCH /api/p-2-p-commission-part-groups/{id} Updates only specified fields. Null fields are ignored.

Path Parameters

id (Long) - Commission part group identifier

Request

Headers:

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

Body (Example - update only description):

{
  "id": 1,
  "description": "Updated description for the group"
}

Body (Example - update name and commission parts):

{
  "id": 1,
  "name": "Premium Processing Fees",
  "commissionParts": [
    {
      "id": 5,
      "name": "Premium Transaction Fee",
      "code": "PREM_TXN",
      "percentage": 3.0,
      "fixedAmount": 2000.00
    }
  ]
}

[!tip] Partial Update Behavior
Only non-null fields are updated
Other fields remain unchanged
Perfect for updating single fields without affecting others
Commission parts list is completely replaced if provided (not merged)

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Premium Processing Fees",
  "description": "Updated description for the group",
  "commissionParts": [
    {
      "id": 5,
      "name": "Premium Transaction Fee",
      "code": "PREM_TXN",
      "percentage": 3.0,
      "fixedAmount": 2000.00
    }
  ]
}

Get All Commission Part Groups

[!example] GET /api/p-2-p-commission-part-groups 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 (P2pCommissionPartGroupCriteria):

id.equals, id.in
name.contains, name.equals
description.contains

Example Requests

GET /api/p-2-p-commission-part-groups?page=0&size=10&sort=name,asc
GET /api/p-2-p-commission-part-groups?name.contains=Standard
GET /api/p-2-p-commission-part-groups?name.equals=Premium Processing Fees

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "name": "Standard Processing Fees",
    "description": "Standard commission parts for processing P2P transactions",
    "commissionParts": [
      {
        "id": 1,
        "name": "Transaction Fee",
        "code": "TXN_FEE",
        "percentage": 1.5,
        "fixedAmount": 1000.00
      },
      {
        "id": 2,
        "name": "Service Charge",
        "code": "SVC_CHG",
        "percentage": 0.5,
        "fixedAmount": 500.00
      }
    ]
  },
  {
    "id": 2,
    "name": "Premium Processing Fees",
    "description": "Premium tier commission structure",
    "commissionParts": [
      {
        "id": 5,
        "name": "Premium Fee",
        "code": "PREM_FEE",
        "percentage": 3.0,
        "fixedAmount": 2000.00
      }
    ]
  }
]

Get Single Commission Part Group

[!example] GET /api/p-2-p-commission-part-groups/{id} Retrieves a single commission part group by ID with all relationships.

Path Parameters

id (Long) - Commission part group identifier

Request

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

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Standard Processing Fees",
  "description": "Standard commission parts for processing P2P transactions",
  "commissionParts": [
    {
      "id": 1,
      "name": "Transaction Fee",
      "code": "TXN_FEE",
      "percentage": 1.5,
      "fixedAmount": 1000.00
    },
    {
      "id": 2,
      "name": "Service Charge",
      "code": "SVC_CHG",
      "percentage": 0.5,
      "fixedAmount": 500.00
    },
    {
      "id": 3,
      "name": "Platform Fee",
      "code": "PLT_FEE",
      "percentage": 0.3,
      "fixedAmount": 300.00
    }
  ]
}

❌ Error (404 Not Found):

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

Count Commission Part Groups

[!example] GET /api/p-2-p-commission-part-groups/count Returns count of commission part groups matching criteria.

Query Parameters

Same filtering parameters as [[#Get All Commission Part Groups]]

Example Requests

GET /api/p-2-p-commission-part-groups/count
GET /api/p-2-p-commission-part-groups/count?name.contains=Standard
GET /api/p-2-p-commission-part-groups/count?description.contains=Premium

Response

✅ Success (200 OK):

Delete Commission Part Group

[!example] DELETE /api/p-2-p-commission-part-groups/{id} Deletes a commission part group from the system.

Path Parameters

id (Long) - Commission part group identifier

Request

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

Response

✅ Success (204 No Content):

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

❌ Error (400 - Group is in use):

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Cannot delete commission part group because it is referenced by existing P2P commissions",
  "entityName": "bmmsP2PCommissionPartGroup",
  "errorKey": "related.to.group",
  "params": "id",
  "message": "p2pCommissionPartGroup",
  "id": 1
}

[!danger] Deletion Constraint Warning A commission part group cannot be deleted if:
It is referenced by any existing P2P commission configurations
The system performs this check before deletion:
if (p2pCommissionRepository.existsByCommissionPartGroupId(id)) {
    throw new BadRequestException("related.to.group", ENTITY_NAME, "id", 
                                  "p2pCommissionPartGroup", id);
}
Workaround: Remove the group reference from all P2P commission configurations before attempting deletion.

Examples

Example 1: Create Basic Commission Part Group

[!example]- Setup Basic Fee Structure Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-part-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Basic Transaction Fees",
    "description": "Standard fees for basic P2P transactions",
    "commissionParts": [
      {
        "id": 1,
        "name": "Processing Fee",
        "code": "PROC_FEE",
        "percentage": 1.0,
        "fixedAmount": 500.00
      }
    ]
  }'

Example 2: Create Multi-Part Commission Group

[!example]- Complex Fee Structure Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-part-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Enterprise Fee Structure",
    "description": "Multi-tier commission structure for enterprise clients",
    "commissionParts": [
      {
        "id": 1,
        "name": "Transaction Fee",
        "code": "TXN_FEE",
        "percentage": 0.8,
        "fixedAmount": 300.00
      },
      {
        "id": 2,
        "name": "Service Fee",
        "code": "SVC_FEE",
        "percentage": 0.3,
        "fixedAmount": 200.00
      },
      {
        "id": 3,
        "name": "Platform Fee",
        "code": "PLT_FEE",
        "percentage": 0.2,
        "fixedAmount": 100.00
      }
    ]
  }'

Example 3: Update Commission Parts in Group

[!example]- Replace Commission Parts Request:

curl -X PATCH http://localhost:8080/api/p-2-p-commission-part-groups/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "commissionParts": [
      {
        "id": 4,
        "name": "New Transaction Fee",
        "code": "NEW_TXN",
        "percentage": 1.2,
        "fixedAmount": 600.00
      },
      {
        "id": 5,
        "name": "New Service Fee",
        "code": "NEW_SVC",
        "percentage": 0.4,
        "fixedAmount": 250.00
      }
    ]
  }'

Response:

{
  "id": 1,
  "name": "Basic Transaction Fees",
  "description": "Standard fees for basic P2P transactions",
  "commissionParts": [
    {
      "id": 4,
      "name": "New Transaction Fee",
      "code": "NEW_TXN",
      "percentage": 1.2,
      "fixedAmount": 600.00
    },
    {
      "id": 5,
      "name": "New Service Fee",
      "code": "NEW_SVC",
      "percentage": 0.4,
      "fixedAmount": 250.00
    }
  ]
}

Example 4: Update Only Description

[!example]- Metadata Update Request:

curl -X PATCH http://localhost:8080/api/p-2-p-commission-part-groups/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "description": "Updated: Now includes promotional discounts"
  }'

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-part-groups",
  "message": "error.code",
  "entityName": "bmmsP2PCommissionPartGroup",
  "errorKey": "error.key",
  "params": "additionalInfo"
}

HTTP Status Codes

Code

Type

Description

Common Causes

400

Bad Request

Invalid request

Validation failure, ID mismatch, duplicate name, group 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-part-groups",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "p2pCommissionPartGroupDTO",
      "field": "name",
      "message": "must not be empty"
    },
    {
      "objectName": "p2pCommissionPartGroupDTO",
      "field": "commissionParts",
      "message": "must not be null"
    }
  ]
}

Validation Rules

Required Fields

[!check] Mandatory Fields
✅ name - Group name (unique)
✅ commissionParts - List of commission parts

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new commission part group 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

commissionParts

@NotNull, Valid references

"must not be null", "invalid commission part references"

Business Rules

[!info] Business Validation
name must be globally unique across all commission part groups
commissionParts must contain valid references to existing commission parts
Commission part group cannot be deleted if referenced by P2P commissions
Groups can contain multiple commission parts
Same commission part can appear in multiple groups
Empty commission parts list is not allowed

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/p-2-p-commission-part-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Standard Fees",
    "description": "Standard commission structure",
    "commissionParts": [
      {"id": 1, "name": "Fee 1", "code": "FEE1", "percentage": 1.0, "fixedAmount": 500}
    ]
  }'

Update

curl -X PUT http://localhost:8080/api/p-2-p-commission-part-groups/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "Updated Standard Fees",
    "description": "Updated description",
    "commissionParts": [
      {"id": 2, "name": "Fee 2", "code": "FEE2", "percentage": 1.5, "fixedAmount": 750}
    ]
  }'

Partial Update

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

Get All

curl -X GET "http://localhost:8080/api/p-2-p-commission-part-groups?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-part-groups/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Count

curl -X GET "http://localhost:8080/api/p-2-p-commission-part-groups/count?name.contains=Standard" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

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

PreviousP2p commission part NextP2p commission

Last updated 1 month ago

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagField Specifications

hashtagAPI Endpoints

hashtagCreate Commission Part Group

hashtagRequest

hashtagResponse

hashtagUpdate Commission Part Group

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagPartial Update Commission Part Group

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagGet All Commission Part Groups

hashtagQuery Parameters

hashtagExample Requests

hashtagResponse

hashtagGet Single Commission Part Group

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagCount Commission Part Groups

hashtagQuery Parameters

hashtagExample Requests

hashtagResponse

hashtagDelete Commission Part Group

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagExamples

hashtagExample 1: Create Basic Commission Part Group

hashtagExample 2: Create Multi-Part Commission Group

hashtagExample 3: Update Commission Parts in Group

hashtagExample 4: Update Only Description

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Error Example

hashtagValidation Rules

hashtagRequired Fields

hashtagField Constraints

hashtagBusiness Rules

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet Single

hashtagCount

hashtagDelete

📋 Table of Contents

Quick Reference

Endpoints Summary

Field Specifications

API Endpoints

Create Commission Part Group

Request

Response

Update Commission Part Group

Path Parameters

Request

Response

Partial Update Commission Part Group

Path Parameters

Request

Response

Get All Commission Part Groups

Query Parameters

Example Requests

Response

Get Single Commission Part Group

Path Parameters

Request

Response

Count Commission Part Groups

Query Parameters

Example Requests

Response

Delete Commission Part Group

Path Parameters

Request

Response

Examples

Example 1: Create Basic Commission Part Group

Example 2: Create Multi-Part Commission Group

Example 3: Update Commission Parts in Group

Example 4: Update Only Description

Error Handling

Error Response Format

HTTP Status Codes

Validation Error Example

Validation Rules

Required Fields

Field Constraints

Business Rules

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get Single

Count

Delete