Recipient

[!info] Overview The Recipient REST API manages service providers (recipients) in the pkbillms billing system. Recipients are entities that receive payments through various gateways and categories.

📋 Table of Contents

• Quick Reference

• Data Models

• API Endpoints

  • Create Recipient

  • Update Recipient

  • Partial Update

  • Get All Recipients

  • Get Recipients with Criteria

  • Export to Excel

  • Get Single Recipient

  • Count Recipients

  • Delete Recipient

  • Cascaded Delete

• Request & Response Examples

• Error Handling

• Validation Rules

• Business Logic

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: pkbillmsRecipient

• Controller: RecipientResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

Method	Endpoint	Description	Status
POST	/api/recipients	Create new recipient	201
PUT	/api/recipients/{id}	Full update	200
PATCH	/api/recipients/{id}	Partial update	200
GET	/api/recipients	Get all (read-only projection)	200
GET	/api/recipients/all	Get all for Excel export	200
GET	/api/recipients/criteria	Get by gateway/category	200
GET	/api/recipients/{id}	Get by ID	200
GET	/api/recipients/count	Count by criteria	200
DELETE	/api/recipients/{id}	Delete recipient	204
DELETE	/api/recipients/cascaded/{id}	Cascaded delete	200

---

Data Models

Recipient DTO Structure

[!note] Data Transfer Object Service provider/payment recipient entity with multilingual support and gateway integration.

@ApiModel(description = "Получатель денежных средств, поставщик услуг")
public class RecipientDTO extends AbstractAuditingDTO {
    private Long id;
    private String shortName;         // Unique name in gateway
    private String serviceId;         // Internal service ID
    private String thumbnail;         // Thumbnail path/URL
    private String logo;              // Logo path/URL
    private byte[] logoFile;          // Logo file binary
    private Integer amountRatio;      // Amount precision (1=sum, 100=tiyin)
    private Integer ccy;              // Currency code
    private Long minAmount;           // Minimum payment amount
    private Long maxAmount;           // Maximum payment amount
    private Integer limitRatio;       // Limit precision
    private Double commission;        // Recipient commission
    private Double fee;               // Recipient fee
    private Double systemCommission;  // System commission
    private Double systemFee;         // System fee
    private Double senderCommission;  // Sender commission
    private Integer ord;              // Display order
    private Boolean active;           // Active status
    private Boolean check;            // Check operation support
    private Boolean pay;              // Payment operation support
    private Boolean status;           // Status check support
    private Boolean cancel;           // Cancel operation support
    private Boolean canDeposit;       // Deposit capability
    private Boolean info;             // Info operation support
    private String settlementAccount; // Settlement account
    private String mfo;               // Bank MFO
    private String phoneNumber;       // Phone number
    private String inn;               // Tax ID
    private Boolean reconcile;        // Reconciliation flag
    private String jsonParams;        // Additional JSON params
    private RecipientType type;       // Recipient type enum
    private GatewayDTO gateway;       // Associated gateway
    private CategoryDTO category;     // Service category
    private Set<I18nDTO> titles;      // Multilingual titles
    private Set<I18nDTO> fullNames;   // Multilingual full names
}

Field Specifications

Field	Type	Required	Max	DB Column	Description
id	Long	❌ Auto	-	id	Primary key
shortName	String	✅	64	short_name	Unique gateway name
serviceId	String	✅	64	service_id	Internal service ID
thumbnail	String	❌	64	thumbnail	Thumbnail path/URL
logo	String	❌	64	logo	Logo path/URL
logoFile	byte[]	❌	-	-	Logo binary data (LOB)
amountRatio	Integer	✅	-	amount_ratio	Amount precision (1 or 100)
ccy	Integer	✅	-	ccy	Currency code
minAmount	Long	❌	-	min_amount	Min payment (limitRatio)
maxAmount	Long	❌	-	max_amount	Max payment (limitRatio)
limitRatio	Integer	✅	-	limit_ratio	Limit amount precision
commission	Double	❌	-	commission	Recipient commission %
fee	Double	❌	-	fee	Recipient fee amount
systemCommission	Double	❌	-	system_commission	System commission %
systemFee	Double	❌	-	system_fee	System fee amount
senderCommission	Double	❌	-	sender_commission	Sender reward
ord	Integer	❌	-	ord	Display order
active	Boolean	✅	-	active	Active/Inactive
check	Boolean	❌	-	jhi_check	Check operation
pay	Boolean	❌	-	pay	Payment operation
status	Boolean	❌	-	status	Status check
cancel	Boolean	❌	-	cancel	Cancel operation
canDeposit	Boolean	❌	-	can_deposit	Deposit capability
info	Boolean	❌	-	info	Info operation
settlementAccount	String	❌	32	settlement_account	Bank account
mfo	String	❌	16	mfo	Bank MFO code
phoneNumber	String	❌	-	-	Contact phone
inn	String	❌	32	inn	Tax ID number
reconcile	Boolean	❌	-	reconcile	Reconciliation flag
jsonParams	String	❌	-	json_params	JSON parameters (LOB)
type	RecipientType	❌	-	jhi_type	Recipient type (ENUM)
gateway	GatewayDTO	❌	-	gateway_id	Associated gateway
category	CategoryDTO	❌	-	category_id	Service category
titles	Set	✅	-	rel_recipient__title	Multilingual titles
fullNames	Set	✅	-	rel_recipient__full_name	Multilingual names

RecipientType Enum

public enum RecipientType {
    SIMPLE,  
	GIFT,  
	PIN,
	AMOUNT_DICTATOR,  
	INVOICE,  
	OTHER
}

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 Recipient

POST /api/recipients

Creates a new recipient (service provider) entity.

Request

Headers:

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

Body:

{
  "shortName": "UZCARD_PAY",
  "serviceId": "SRV_UZCARD_001",
  "thumbnail": "/images/uzcard_thumb.png",
  "logo": "/images/uzcard_logo.png",
  "amountRatio": 100,
  "ccy": 860,
  "minAmount": 100000,
  "maxAmount": 10000000000,
  "limitRatio": 100,
  "commission": 0.5,
  "fee": 1000,
  "systemCommission": 0.2,
  "systemFee": 500,
  "senderCommission": 0.1,
  "ord": 1,
  "active": true,
  "check": true,
  "pay": true,
  "status": true,
  "cancel": false,
  "canDeposit": true,
  "info": true,
  "settlementAccount": "20208000123456789012",
  "mfo": "00422",
  "phoneNumber": "[phone]",
  "inn": "123456789",
  "reconcile": true,
  "jsonParams": "{\"apiKey\":\"xxx\",\"endpoint\":\"https://api.uzcard.uz\"}",
  "type": "FINANCIAL",
  "gateway": {
    "id": 1
  },
  "category": {
    "id": 5
  },
  "titles": [
    {
      "lang": "EN",
      "text": "Uzcard Payment"
    },
    {
      "lang": "RU",
      "text": "Платеж Uzcard"
    },
    {
      "lang": "UZ",
      "text": "Uzcard to'lovi"
    }
  ],
  "fullNames": [
    {
      "lang": "EN",
      "text": "Uzcard National Payment System"
    },
    {
      "lang": "RU",
      "text": "Национальная платежная система Uzcard"
    },
    {
      "lang": "UZ",
      "text": "Uzcard milliy to'lov tizimi"
    }
  ]
}

[!warning] Validation Rules

• id must be null (auto-generated)

• shortName, serviceId, amountRatio, ccy, limitRatio, active are required

• titles and fullNames must not be empty

• String fields must respect max length

• Boolean operation flags default to false if not specified

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/recipients/1

{
  "id": 1,
  "shortName": "UZCARD_PAY",
  "serviceId": "SRV_UZCARD_001",
  "thumbnail": "/images/uzcard_thumb.png",
  "logo": "/images/uzcard_logo.png",
  "amountRatio": 100,
  "ccy": 860,
  "minAmount": 100000,
  "maxAmount": 10000000000,
  "limitRatio": 100,
  "commission": 0.5,
  "fee": 1000.0,
  "systemCommission": 0.2,
  "systemFee": 500.0,
  "senderCommission": 0.1,
  "ord": 1,
  "active": true,
  "check": true,
  "pay": true,
  "status": true,
  "cancel": false,
  "canDeposit": true,
  "info": true,
  "settlementAccount": "20208000123456789012",
  "mfo": "00422",
  "phoneNumber": "[phone]",
  "inn": "123456789",
  "reconcile": true,
  "jsonParams": "{\"apiKey\":\"xxx\",\"endpoint\":\"https://api.uzcard.uz\"}",
  "type": "FINANCIAL",
  "gateway": {
    "id": 1,
    "name": "Main Gateway"
  },
  "category": {
    "id": 5,
    "shortName": "PAYMENT"
  },
  "titles": [...],
  "fullNames": [...],
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T10:30:00Z"
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "detail": "A new recipient cannot already have an ID",
  "message": "error.idexists"
}

---

Update Recipient

PUT /api/recipients/{id}

Completely updates an existing recipient. All required fields must be provided.

Path Parameters

• id (Long) - Recipient identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "shortName": "UZCARD_PAY_UPDATED",
  "serviceId": "SRV_UZCARD_001",
  "amountRatio": 100,
  "ccy": 860,
  "limitRatio": 100,
  "active": false,
  "commission": 0.7,
  "fee": 1500.0,
  "gateway": {
    "id": 1
  },
  "category": {
    "id": 5
  },
  "titles": [...],
  "fullNames": [...]
}

[!warning] Validation

• Body id must not be null

• Path id must match body id

• Recipient must exist in database

• All required fields must be provided

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "UZCARD_PAY_UPDATED",
  "active": false,
  "commission": 0.7,
  "fee": 1500.0,
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T14:20:00Z"
}

❌ Errors:

Status	Detail	Message
400	Invalid id	error.idnull
400	Invalid ID	error.idinvalid
400	Entity not found	error.idnotfound

---

Partial Update

PATCH /api/recipients/{id}

Updates only specified fields. Null fields are ignored.

Path Parameters

• id (Long) - Recipient identifier

Request

Headers:

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

Body (Example - toggle active status and update commission):

{
  "id": 1,
  "active": true,
  "commission": 0.6
}

[!tip] Partial Update Behavior

• Only non-null fields are updated

• Other fields remain unchanged

• Perfect for status toggles or single field updates

• Relationships can be partially updated

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "UZCARD_PAY_UPDATED",
  "active": true,
  "commission": 0.6,
  "fee": 1500.0,
  "lastModifiedDate": "2024-01-29T15:45:00Z"
}

---

Get All Recipients

GET /api/recipients

Retrieves paginated list with read-only projection for optimized queries.

Query Parameters

Pagination:

• page - Page number (0-indexed, default: 0)

• size - Items per page (default: 20)

• sort - Sort criteria (e.g., shortName,asc)

Filters (RecipientReadOnlyCriteria):

• id.equals, id.in

• shortName.contains, shortName.equals

• serviceId.equals

• active.equals

• type.equals, type.in

• gatewayId.equals

• categoryId.equals

• minAmount.greaterThanOrEqual

• maxAmount.lessThanOrEqual

Example Requests

GET /api/recipients?page=0&size=10&sort=shortName,asc
GET /api/recipients?active.equals=true
GET /api/recipients?gatewayId.equals=1&active.equals=true
GET /api/recipients?type.in=FINANCIAL,UTILITY

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "shortName": "UZCARD_PAY",
    "logo": "logo_4c19b2c461ab",
    "serviceId": "SRV_UZCARD_001",
    "type": "SIMPLE",
    "minAmount": 0,
    "maxAmount": 0,
    "active": true,
    "amountRatio": 0,
    "limitRatio": 0,
    "gatewayId": 1,
    "categoryId": 5
  },
  {
    "id": 1,
    "shortName": "UZCARD_PAY",
    "logo": "logo_4c19b2c461ab",
    "serviceId": "SRV_UZCARD_001",
    "type": "SIMPLE",
    "minAmount": 0,
    "maxAmount": 1000,
    "active": true,
    "amountRatio": 0,
    "limitRatio": 0,
    "gatewayId": 1,
    "categoryId": 6
  }
]

[!info] Read-Only Projection This endpoint uses RecipientReadOnly projection for better performance. It returns minimal fields without relationships.

---

Export to Excel

GET /api/recipients/all

Retrieves all recipients for Excel export with full DTO structure.

Query Parameters

Same as [[#Get All Recipients]] but returns RecipientReadOnlyDTO with more fields.

Example Request

GET /api/recipients/all?active.equals=true&sort=shortName,asc

Response

✅ Success (200 OK):

[
  {
    "id": 1,
    "shortName": "UZCARD_PAY",
    "logo": "logo_4c19b2c461ab",
    "serviceId": "SRV_UZCARD_001",
    "type": "SIMPLE",
    "minAmount": 0,
    "maxAmount": 1000,
    "active": true,
    "amountRatio": 0,
    "limitRatio": 0,
    "gatewayId": 1,
    "categoryId": 6
  }
]

[!tip] Use Case Use this endpoint when exporting data to Excel or other formats requiring complete data.

---

Get Recipients with Criteria

GET /api/recipients/criteria

Advanced filtering by gateway name and category shortName.

Query Parameters

Standard Filters:

• All RecipientCriteria filters

• Pagination parameters

Special Parameters:

• gatewayName (String) - Filter by gateway name

• categoryShortName (String) - Filter by category short name

Example Requests

GET /api/recipients/criteria?active.equals=true
GET /api/recipients/criteria?shortName.equals=ucell&gatewayId.equals=12
GET /api/recipients/criteria?page=0&size=20

Response

✅ Success (200 OK):

[
  {
    "id": 1,
    "shortName": "UZCARD_PAY",
    "serviceId": "SRV_UZCARD_001",
    "active": true,
    "gateway": {
      "id": 1,
      "name": "MainGateway"
    },
    "category": {
      "id": 5,
      "shortName": "PAYMENT"
    }
  }
]

[!info] Business Logic

• Gateway and Category are resolved by name/shortName

• If not found, filter is not applied

• Results include full DTO with relationships

---

Get Single Recipient

GET /api/recipients/{id}

Retrieves a single recipient by ID with all relationships.

Path Parameters

• id (Long) - Recipient identifier

Request

GET /api/recipients/1
Authorization: Bearer {token}

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "UZCARD_PAY",
  "serviceId": "SRV_UZCARD_001",
  "thumbnail": "/images/uzcard_thumb.png",
  "logo": "/images/uzcard_logo.png",
  "amountRatio": 100,
  "ccy": 860,
  "minAmount": 100000,
  "maxAmount": 10000000000,
  "limitRatio": 100,
  "commission": 0.5,
  "fee": 1000.0,
  "systemCommission": 0.2,
  "systemFee": 500.0,
  "active": true,
  "type": "FINANCIAL",
  "gateway": {
    "id": 1,
    "name": "Main Gateway"
  },
  "category": {
    "id": 5,
    "shortName": "PAYMENT",
    "names": [...]
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Uzcard Payment"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "Платеж Uzcard"
    }
  ],
  "fullNames": [...]
}

❌ Error (404 Not Found):

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

---

Count Recipients

GET /api/recipients/count

Returns count of recipients matching criteria.

Query Parameters

Same filtering parameters as [[#Get All Recipients]]

Example Requests

GET /api/recipients/count
GET /api/recipients/count?active.equals=true
GET /api/recipients/count?type.equals=FINANCIAL
GET /api/recipients/count?gatewayId.equals=1&active.equals=true

Response

✅ Success (200 OK):

125

---

Delete Recipient

DELETE /api/recipients/{id}

Deletes a recipient by ID (standard delete).

Path Parameters

• id (Long) - Recipient identifier

Request

DELETE /api/recipients/1
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

[!danger] Standard Delete Warning This is a standard delete. May fail if recipient has dependent relationships.

---

Cascaded Delete

DELETE /api/recipients/cascaded/{id}

Deletes a recipient and all dependent entities (cascaded delete).

Path Parameters

• id (Long) - Recipient identifier

Request

DELETE /api/recipients/cascaded/1
Authorization: Bearer {token}

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

[!danger] Cascaded Delete Warning This operation will delete:

• The recipient entity

• All associated I18n entries (titles, fullNames)

• Any other dependent relationships

Use with extreme caution! This operation cannot be undone.

---

Examples

Example 1: Create Utility Service Provider

Create Water Service Request:

curl -X POST http://localhost:8080/api/recipients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "shortName": "WATER_SUPPLY",
    "serviceId": "SRV_WATER_001",
    "amountRatio": 100,
    "ccy": 860,
    "minAmount": 10000,
    "maxAmount": 100000000,
    "limitRatio": 100,
    "commission": 0.0,
    "fee": 500.0,
    "active": true,
    "check": true,
    "pay": true,
    "status": true,
    "type": "UTILITY",
    "gateway": {"id": 1},
    "category": {"id": 3},
    "titles": [
      {"lang": "en", "text": "Water Supply"},
      {"lang": "ru", "text": "Водоснабжение"},
      {"lang": "uz", "text": "Suv ta'\''minoti"}
    ],
    "fullNames": [
      {"lang": "en", "text": "Municipal Water Supply Service"},
      {"lang": "ru", "text": "Муниципальная служба водоснабжения"},
      {"lang": "uz", "text": "Munitsipal suv ta'\''minoti xizmati"}
    ]
  }'

Example 2: Toggle Recipient Status

• Deactivate Recipient Request:

curl -X PATCH http://localhost:8080/api/recipients/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "active": false
  }'

Response:

{
  "id": 1,
  "shortName": "WATER_SUPPLY",
  "active": false,
  "lastModifiedDate": "2024-01-29T17:30:12.456Z"
}

Example 3: Search Financial Recipients

Filter by Type and Gateway Request:

curl -X GET "http://localhost:8080/api/recipients?\
type.equals=FINANCIAL&\
gatewayId.equals=1&\
active.equals=true&\
page=0&\
size=10&\
sort=shortName,asc" \
  -H "Authorization: Bearer TOKEN"

Example 4: Get Recipients by Gateway and Category Names

Named Filter Query Request:

curl -X GET "http://localhost:8080/api/recipients/criteria?\
gatewayName=MainGateway&\
categoryShortName=UTILITY&\
active.equals=true" \
  -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/recipients",
  "message": "error.code",
  "params": "additionalInfo"
}

HTTP Status Codes

Code	Type	Description	Common Causes
400	Bad Request	Invalid request	Validation failure, ID mismatch
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 shortName, constraints
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/recipients",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "recipientDTO",
      "field": "shortName",
      "message": "must not be null"
    },
    {
      "objectName": "recipientDTO",
      "field": "amountRatio",
      "message": "must not be null"
    },
    {
      "objectName": "recipientDTO",
      "field": "titles",
      "message": "must not be empty"
    }
  ]
}

---

Validation Rules

Required Fields

[!check] Mandatory Fields

• ✅ shortName - Unique name in gateway

• ✅ serviceId - Internal service identifier

• ✅ amountRatio - Amount precision (1 or 100)

• ✅ ccy - Currency code (e.g., 860 for UZS)

• ✅ limitRatio - Limit precision

• ✅ active - Active status flag

• ✅ titles - At least one title required

• ✅ fullNames - At least one full name required

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"A new recipient cannot already have an ID"
id	Not null for PUT/PATCH	"Invalid id"
shortName	@NotNull, @Size(max=64), unique	"must not be null", "size must be between 0 and 64"
serviceId	@Size(max=64)	"size must be between 0 and 64"
thumbnail	@Size(max=64)	"size must be between 0 and 64"
logo	@Size(max=64)	"size must be between 0 and 64"
amountRatio	@NotNull, 1 or 100	"must not be null"
ccy	@NotNull, valid currency code	"must not be null"
limitRatio	@NotNull	"must not be null"
settlementAccount	@Size(max=32)	"size must be between 0 and 32"
mfo	@Size(max=16)	"size must be between 0 and 16"
inn	@Size(max=32)	"size must be between 0 and 32"
titles	@NotNull, not empty	"must not be null", "must not be empty"
fullNames	@NotNull, not empty	"must not be null", "must not be empty"

Business Rules

[!info] Business Validation

• shortName must be unique within the system

• minAmount must be less than maxAmount (if both specified)

• amountRatio typically 1 (sum) or 100 (tiyin)

• limitRatio typically matches amountRatio

• Commission and fee values should be non-negative

• Gateway and Category must exist if specified

• At least one operation flag (check, pay, status, etc.) should be true

---

Business Logic

Amount Precision System

[!abstract] Understanding Amount Ratios

The recipient entity uses a dual-precision system for amounts:

amountRatio:

• 1 = Amount in sums (whole units)

• 100 = Amount in tiyins (1/100 units)

limitRatio:

• Defines precision for minAmount and maxAmount

• Should typically match amountRatio

Example:

{
  "amountRatio": 100,
  "limitRatio": 100,
  "minAmount": 100000,
  "maxAmount": 10000000000
}

Means:

• Amounts processed in tiyins

• Min: 1,000.00 sum (100,000 tiyins)

• Max: 100,000,000.00 sum (10,000,000,000 tiyins)

Commission Structure

[!info] Fee Calculation

Recipients can have multiple commission types:

Commission Type	Description	Usage
commission	Recipient commission %	Charged to customer
fee	Recipient fixed fee	Added to transaction
systemCommission	System commission %	Platform revenue
systemFee	System fixed fee	Platform revenue
senderCommission	Sender reward %	If sender participates

Example Calculation:

Payment Amount: 100,000 sum
Recipient commission: 0.5% = 500 sum
Recipient fee: 1,000 sum
Total charged to customer: 101,500 sum

System commission: 0.2% of 100,000 = 200 sum
System fee: 500 sum
Total platform revenue: 700 sum

Multilingual Support

[!tip] I18n Integration

Recipients support multiple languages through I18n entities:

Titles: Short display names

"titles": [
  {"lang": "EN", "text": "Water Supply"},
  {"lang": "RU", "text": "Водоснабжение"},
  {"lang": "UZ", "text": "Suv ta'minoti"}
]

Full Names: Complete service names

"fullNames": [
  {"lang": "EN", "text": "Municipal Water Supply Service"},
  {"lang": "RU", "text": "Муниципальная служба водоснабжения"}
]

Operation Flags

[!abstract] Service Capabilities

Boolean flags define what operations the recipient supports:

Flag	Purpose	Example Use Case
check	Balance/debt inquiry	Check utility bill
pay	Payment processing	Pay bill
status	Transaction status	Check payment status
cancel	Cancel transaction	Reverse payment
canDeposit	Accept deposits	Mobile top-up
info	Service information	Get tariff info
reconcile	Financial reconciliation	Daily settlement

Typical Configurations:

Utility Service:

{
  "check": true,
  "pay": true,
  "status": true,
  "cancel": false,
  "canDeposit": false,
  "info": true
}

Mobile Operator:

{
  "check": false,
  "pay": true,
  "status": true,
  "cancel": false,
  "canDeposit": true,
  "info": false
}

Gateway Integration

[!info] Gateway Relationship

Each recipient belongs to a gateway that handles:

• Payment routing

• Protocol implementation

• Transaction processing

• Response handling

The jsonParams field stores gateway-specific configuration:

{
  "jsonParams": "{\"apiKey\":\"xxx\",\"endpoint\":\"https://api.provider.uz\",\"timeout\":30000}"
}

---

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/recipients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "shortName": "TEST_RECIPIENT",
    "serviceId": "SRV_TEST_001",
    "amountRatio": 100,
    "ccy": 860,
    "limitRatio": 100,
    "active": true,
    "gateway": {"id": 1},
    "category": {"id": 1},
    "titles": [{"lang": "en", "text": "Test"}],
    "fullNames": [{"lang": "en", "text": "Test Recipient"}]
  }'

Update

curl -X PUT http://localhost:8080/api/recipients/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "shortName": "UPDATED_RECIPIENT",
    "serviceId": "SRV_TEST_001",
    "amountRatio": 100,
    "ccy": 860,
    "limitRatio": 100,
    "active": false,
    "gateway": {"id": 1},
    "category": {"id": 1},
    "titles": [{"lang": "en", "text": "Updated"}],
    "fullNames": [{"lang": "en", "text": "Updated Recipient"}]
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/recipients/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "active": true, "commission": 0.8}'

Get All

curl -X GET "http://localhost:8080/api/recipients?active.equals=true&page=0&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get with Gateway/Category Filter

curl -X GET "http://localhost:8080/api/recipients/criteria?gatewayId.equals=12" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

curl -X GET http://localhost:8080/api/recipients/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Count

curl -X GET "http://localhost:8080/api/recipients/count?type.equals=FINANCIAL" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

curl -X DELETE http://localhost:8080/api/recipients/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Cascaded Delete

curl -X DELETE http://localhost:8080/api/recipients/cascaded/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

📌 Metadata

[!metadata] Version: 1.0 Last Updated: 2024-01-29 API Version: v1 Team: pkbillms Development Team Status: 🟢 Active Complexity: 🔴 High (Complex entity with relationships)

---

🏷️ Tags

#api #recipient #service-provider #rest #jhipster #payment #multilingual #gateway #category #i18n #commission #fee #crud #spring-boot #backend #pkbillms