User - Payments

Base URL: https://your-domain.com

Admin endpoints for managing payments. All endpoints require admin/staff authentication.

---

Fetch All Payments

Retrieve a paginated list of all payment transactions. Returns payment data with action by user, user data, and subscriber with salesperson information.

Property	Value
Endpoint	Fetch All Payments
Method	GET
URL	/api/v1/payments
Authentication	Bearer Token

Request Headers:

Header	Value	Required
Accept	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Query Parameters:

Required Parameters

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID

Pagination Parameters

Parameter	Type	Required	Description
offset	integer	No	Pagination offset (default: 0)
limit	integer	No	Results per page (default: 100)

Filter Parameters

Parameter	Type	Required	Description
profile_type	integer	No	Filter by profile type (1=User, 2=Subscriber)
payer_id	integer	No	Filter by payer ID (requires profile_type)
payment_type	integer	No	Filter by payment method

Request Body: None

Success Response (200 OK):

{
    "success": true,
    "data": {
        "payments": [
            {
                "id": 1,
                "subscriber_id": 1,
                "subscriber_name": "John Doe",
                "amount": 1000,
                "payment_method": "Cash",
                "invoice_id": 123,
                "received_by": "Admin User",
                "created_at": "2024-01-15 10:30:00"
            }
        ],
        "total": 50
    }
}

Error Response (401 Unauthorized):

{
    "success": false,
    "message": "Unauthenticated"
}

cURL Example:

curl -X GET "https://your-domain.com/api/v1/payments?isp_id=1&branch_id=1&offset=0&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

---

Payment Receipt

Get payment receipt data including payment details and ISP information with area data.

Property	Value
Endpoint	Payment Receipt
Method	GET
URL	/api/v1/payments/receipt
Authentication	Bearer Token

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Payment ID

Query Parameters:

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID
user_id	integer	Yes	User ID

Success Response (200 OK):

{
    "success": true,
    "data": {
        "receipt_number": "RCP-2024-0001",
        "subscriber_name": "John Doe",
        "amount": 1000,
        "payment_method": "Cash",
        "invoice_number": "INV-2024-0123",
        "received_by": "Admin User",
        "isp_name": "Your ISP Name",
        "isp_address": "123 ISP Street",
        "payment_date": "2024-01-15 10:30:00"
    }
}

Error Response (404 Not Found):

{
    "success": false,
    "message": "Payment not found"
}

cURL Example:

curl -X GET "https://your-domain.com/api/v1/payments/receipt?id=1&isp_id=1&branch_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

---

Add Subscriber Balance

Add balance to a subscriber account. Creates a payment record and updates subscriber balance. Rate limited to prevent duplicate payments within 60 seconds.

Property	Value
Endpoint	Add Subscriber Balance
Method	POST
URL	/api/v1/payments/add-subscriber-balance
Authentication	Bearer Token

Request Headers:

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Request Body:

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "subscriber_id": 1,
    "amount": 500,
    "payment_method": 1,
    "notes": "Balance top-up"
}

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID
user_id	integer	Yes	Admin user ID
subscriber_id	integer	Yes	Subscriber ID
amount	decimal	Yes	Amount to add
payment_method	integer	No	Payment method ID
notes	string	No	Transaction notes

Success Response (200 OK):

{
    "success": true,
    "message": "Balance added successfully",
    "data": {
        "new_balance": 1500,
        "transaction_id": 456
    }
}

Error Response (404 Not Found):

{
    "success": false,
    "message": "Subscriber not found"
}

Error Response (422 Validation Error):

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "amount": ["The amount must be greater than 0."]
    }
}

cURL Example:

curl -X POST "https://your-domain.com/api/v1/payments/add-subscriber-balance" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "subscriber_id": 1,
    "payment_amount": 500
  }'