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: /api

  • Entity Name: pkbillmsP2PCommission

  • Controller: P2pCommissionResource

  • Framework: Spring Boot + JHipster

  • Auth: Required (Spring Security)

  • Content-Type: application/json

Endpoints Summary

Method
Endpoint
Description
Status

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

Field
Type
Required
Max/Range
Description

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.lessThan

  • name.equals, name.contains, name.specified

  • fromAmount.equals, fromAmount.greaterThan, fromAmount.lessThan

  • toAmount.equals, toAmount.greaterThan, toAmount.lessThan

  • up.equals, up.greaterThan, up.lessThan

  • down.equals, down.greaterThan, down.lessThan

  • fee.equals, fee.greaterThan, fee.lessThan

Audit Fields (Inherited)

[!success] Auto-managed These fields are automatically populated by the system.

Field
Type
Description

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-commissions or /api/p-2-p-commissions/v1

Creates a new P2P commission rule.

Request

Headers:

Body:

[!warning] Validation Rules

  • id must be null (auto-generated)

  • name must be unique

  • name is required

  • up, down, fee must 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 id must not be null

  • Path id must match body id

  • P2P commission must exist in database

  • name must remain unique (excluding current record)

  • up, down, fee must be between 0 and 100

Response

✅ Success (200 OK):

❌ Errors:

Status
Detail
Message

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-commissions

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 (P2pCommissionCriteria):

  • id.equals, id.in, id.greaterThan, id.lessThan

  • name.equals, name.contains, name.specified

  • fromAmount.equals, fromAmount.greaterThan, fromAmount.lessThan

  • toAmount.equals, toAmount.greaterThan, toAmount.lessThan

  • up.equals, up.greaterThan, up.lessThan

  • down.equals, down.greaterThan, down.lessThan

  • fee.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/count

Returns 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

Code
Type
Description
Common Causes

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

Field
Rules
Error Messages

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

  • name must be unique across all commissions

  • fromAmount defines the minimum transaction amount for this commission

  • toAmount defines the maximum transaction amount for this commission

  • up is commission added on top of the transaction amount (percentage)

  • down is commission deducted from the transaction amount (percentage)

  • fee is an additional service fee (percentage)

  • commissionDetails stores JSON string with additional configuration

  • Cannot 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