P2p commission group

[!info] Overview The P2P Commission Group REST API manages commission groupings in the BMMS billing system. Commission groups organize multiple P2P commissions together for streamlined management and configuration across payment transactions.

📋 Table of Contents

• Quick Reference

• Data Models

• API Endpoints

  • Create Commission Group

  • Update Commission Group

  • Partial Update Commission Group

  • Get All Commission Groups

  • Get Single Commission Group

  • Count Commission Groups

  • Delete Commission Group

• Request & Response Examples

• Error Handling

• Validation Rules

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: P2PCommissionGroup

• Controller: P2pCommissionGroupResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

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

---

Field Specifications

Field	Type	Required	Constraints	DB Column	Description
id	Long	❌ Auto	-	id	Primary key
name	String	✅	Unique	name	Group name (unique identifier)
description	String	❌	-	description	Optional description
p2pCommissions	List	✅	NotNull	ManyToMany rel	Associated P2P commissions

---

API Endpoints

Create Commission Group

POST /api/p-2-p-commission-groups

Creates a new commission group entity.

Request

Headers:

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

Body:

{
  "name": "Standard Transaction Commissions",
  "description": "Standard commission group for regular P2P transactions",
  "p2pCommissions": [
    {
      "id": 1,
      "name": "Basic Commission",
      "description": "Standard transaction commission",
      "totalAmount": 1.5,
      "type": "PERCENT"
    },
    {
      "id": 2,
      "name": "Service Fee",
      "description": "Service processing fee",
      "totalAmount": 500.0,
      "type": "FIXED"
    }
  ]
}

[!warning] Validation Rules

• id must be null (auto-generated)

• name must be non-empty and unique

• p2pCommissions must be non-null and contain valid commission references

• P2P commissions must exist in the system

Response

✅ Success (201 Created):

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

{
  "id": 1,
  "name": "Standard Transaction Commissions",
  "description": "Standard commission group for regular P2P transactions",
  "p2pCommissions": [
    {
      "id": 1,
      "name": "Basic Commission",
      "description": "Standard transaction commission",
      "totalAmount": 1.5,
      "type": "PERCENT"
    },
    {
      "id": 2,
      "name": "Service Fee",
      "description": "Service processing fee",
      "totalAmount": 500.0,
      "type": "FIXED"
    }
  ]
}

❌ Error (400 - Name exists):

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

❌ Error (400 - ID exists):

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

---

Update Commission Group

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

Completely updates an existing commission group.

Path Parameters

• id (Long) - Commission group identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "name": "Updated Standard Transaction Commissions",
  "description": "Updated description for standard commission group",
  "p2pCommissions": [
    {
      "id": 1,
      "name": "Basic Commission",
      "description": "Standard transaction commission",
      "totalAmount": 2.0,
      "type": "PERCENT"
    },
    {
      "id": 3,
      "name": "New Platform Fee",
      "description": "New platform processing fee",
      "totalAmount": 750.0,
      "type": "FIXED"
    }
  ]
}

[!warning] Validation

• Body id must not be null

• Path id must match body id

• Commission 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 Transaction Commissions",
  "description": "Updated description for standard commission group",
  "p2pCommissions": [
    {
      "id": 1,
      "name": "Basic Commission",
      "description": "Standard transaction commission",
      "totalAmount": 2.0,
      "type": "PERCENT"
    },
    {
      "id": 3,
      "name": "New Platform Fee",
      "description": "New platform processing fee",
      "totalAmount": 750.0,
      "type": "FIXED"
    }
  ]
}

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

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

Updates only specified fields. Null fields are ignored.

Path Parameters

• id (Long) - Commission 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 commission group"
}

Body (Example - update name and commissions):

{
  "id": 1,
  "name": "Premium Transaction Commissions",
  "p2pCommissions": [
    {
      "id": 5,
      "name": "Premium Commission",
      "description": "Premium tier commission",
      "totalAmount": 3.0,
      "type": "PERCENT"
    }
  ]
}

[!tip] Partial Update Behavior

• Only non-null fields are updated

• Other fields remain unchanged

• Perfect for updating single fields without affecting others

• P2P commissions list is completely replaced if provided (not merged)

• Name uniqueness is validated if name is being changed

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Premium Transaction Commissions",
  "description": "Updated description for the commission group",
  "p2pCommissions": [
    {
      "id": 5,
      "name": "Premium Commission",
      "description": "Premium tier commission",
      "totalAmount": 3.0,
      "type": "PERCENT"
    }
  ]
}

---

Get All Commission Groups

GET /api/p-2-p-commission-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 (P2pCommissionGroupCriteria):

• id.equals, id.in

• name.contains, name.equals

• description.contains

Example Requests

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

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "name": "Standard Transaction Commissions",
    "description": "Standard commission group for regular P2P transactions",
    "p2pCommissions": [
      {
        "id": 1,
        "name": "Basic Commission",
        "description": "Standard transaction commission",
        "totalAmount": 1.5,
        "type": "PERCENT"
      },
      {
        "id": 2,
        "name": "Service Fee",
        "description": "Service processing fee",
        "totalAmount": 500.0,
        "type": "FIXED"
      }
    ]
  },
  {
    "id": 2,
    "name": "Premium Transaction Commissions",
    "description": "Premium tier commission structure",
    "p2pCommissions": [
      {
        "id": 5,
        "name": "Premium Commission",
        "description": "Premium tier commission",
        "totalAmount": 3.0,
        "type": "PERCENT"
      }
    ]
  }
]

---

Get Single Commission Group

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

Retrieves a single commission group by ID with all relationships.

Path Parameters

• id (Long) - Commission group identifier

Request

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

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Standard Transaction Commissions",
  "description": "Standard commission group for regular P2P transactions",
  "p2pCommissions": [
    {
      "id": 1,
      "name": "Basic Commission",
      "description": "Standard transaction commission",
      "totalAmount": 1.5,
      "type": "PERCENT"
    },
    {
      "id": 2,
      "name": "Service Fee",
      "description": "Service processing fee",
      "totalAmount": 500.0,
      "type": "FIXED"
    }
  ]
}

❌ Error (404 Not Found):

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

---

Count Commission Groups

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

Returns count of commission groups matching criteria.

Query Parameters

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

Example Requests

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

Response

✅ Success (200 OK):

12

---

Delete Commission Group

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

Deletes a commission group from the system.

Path Parameters

• id (Long) - Commission group identifier

Request

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

Response

✅ Success (204 No Content):

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

[!info] Deletion Behavior

• Commission group is permanently deleted from the system

• Associated relationships are removed

• P2P commissions within the group are not deleted, only the grouping relationship is removed

• No cascade deletion of commissions

---

Examples

Example 1: Create Basic Commission Group

• Setup Basic Commission Structure Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Basic Transaction Commissions",
    "description": "Basic commission structure for standard transactions",
    "p2pCommissions": [
      {
        "id": 1,
        "name": "Processing Fee",
        "description": "Standard processing fee",
        "totalAmount": 1.0,
        "type": "PERCENT"
      }
    ]
  }'

Example 2: Create Multi-Commission Group

• Complex Commission Structure Request:

curl -X POST http://localhost:8080/api/p-2-p-commission-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Enterprise Commission Structure",
    "description": "Multi-tier commission structure for enterprise clients",
    "p2pCommissions": [
      {
        "id": 1,
        "name": "Transaction Commission",
        "description": "Primary transaction commission",
        "totalAmount": 0.8,
        "type": "PERCENT"
      },
      {
        "id": 2,
        "name": "Service Fee",
        "description": "Service processing fee",
        "totalAmount": 300.0,
        "type": "FIXED"
      },
      {
        "id": 3,
        "name": "Platform Fee",
        "description": "Platform usage fee",
        "totalAmount": 0.2,
        "type": "PERCENT"
      }
    ]
  }'

Example 3: Update Commissions in Group

• Replace Commission List Request:

curl -X PATCH http://localhost:8080/api/p-2-p-commission-groups/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "p2pCommissions": [
      {
        "id": 4,
        "name": "New Transaction Fee",
        "description": "Updated transaction fee",
        "totalAmount": 1.2,
        "type": "PERCENT"
      },
      {
        "id": 5,
        "name": "New Service Fee",
        "description": "Updated service fee",
        "totalAmount": 400.0,
        "type": "FIXED"
      }
    ]
  }'

Response:

{
  "id": 1,
  "name": "Basic Transaction Commissions",
  "description": "Basic commission structure for standard transactions",
  "p2pCommissions": [
    {
      "id": 4,
      "name": "New Transaction Fee",
      "description": "Updated transaction fee",
      "totalAmount": 1.2,
      "type": "PERCENT"
    },
    {
      "id": 5,
      "name": "New Service Fee",
      "description": "Updated service fee",
      "totalAmount": 400.0,
      "type": "FIXED"
    }
  ]
}

Example 4: Update Only Description

• Metadata Update Request:

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

Example 5: Search by Name

• Find Specific Groups Request:

curl -X GET "http://localhost:8080/api/p-2-p-commission-groups?name.contains=Premium" \
  -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-groups",
  "message": "error.code",
  "entityName": "bmmsP2PCommissionGroup",
  "errorKey": "error.key",
  "params": "additionalInfo"
}

HTTP Status Codes

Code	Type	Description	Common Causes
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, 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-groups",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "p2pCommissionGroupAddDTO",
      "field": "name",
      "message": "must not be empty"
    },
    {
      "objectName": "p2pCommissionGroupAddDTO",
      "field": "p2pCommissions",
      "message": "must not be null"
    }
  ]
}

---

Validation Rules

Required Fields

[!check] Mandatory Fields

• ✅ name - Group name (unique)

• ✅ p2pCommissions - List of P2P commissions

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"A new commission 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	-
p2pCommissions	@NotNull, Valid references	"must not be null", "invalid commission references"

Business Rules

[!info] Business Validation

• name must be globally unique across all commission groups

• p2pCommissions must contain valid references to existing P2P commissions

• Groups can contain multiple P2P commissions

• Same P2P commission can appear in multiple groups

• Empty P2P commissions list is not allowed

• Deletion removes the group but not the P2P commissions

---

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/p-2-p-commission-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Standard Commissions",
    "description": "Standard commission structure",
    "p2pCommissions": [
      {"id": 1, "name": "Commission 1", "totalAmount": 1.0, "type": "PERCENT"}
    ]
  }'

Update

curl -X PUT http://localhost:8080/api/p-2-p-commission-groups/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "Updated Standard Commissions",
    "description": "Updated description",
    "p2pCommissions": [
      {"id": 2, "name": "Commission 2", "totalAmount": 1.5, "type": "PERCENT"}
    ]
  }'

Partial Update

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

Count

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

Delete

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

---

---