List Payments (v1)

Method & Path

GET /api/v1/admin/payments

Description

Retrieve a paginated list of all workspace payments with optional filtering by workspace, payment type, date range, and manual/automatic status.

Authentication

Required: Admin authentication with payments.view permission.

Headers

Authorization: Bearer <admin_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
workspaceId	string	No	Filter by workspace ID
paymentType	string	No	Filter by payment type (ai-tools, sms, storage, subscription)
startDate	date	No	Start date for date range filter (ISO 8601 format)
endDate	date	No	End date for date range filter (ISO 8601 format)
isManual	boolean	No	Filter by manual/automatic payments (true for manual, false for automatic)
page	number	No	Page number (default: 1, min: 1)
limit	number	No	Items per page (default: 10, min: 1, max: 100)

Response 200 OK

{
  "payments": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "workspace": {
        "id": "507f1f77bcf86cd799439012",
        "name": "Example Workspace",
        "email": "workspace@example.com"
      },
      "paymentType": "subscription",
      "amount": 100.00,
      "paymentMethod": "card",
      "paymentDate": "2025-01-15T10:30:00.000Z",
      "description": "Monthly subscription renewal",
      "notes": "Payment processed successfully",
      "isManual": false,
      "createdBy": null,
      "receiptImage": {
        "url": "https://example.com/receipt.jpg",
        "path": "/uploads/receipts/receipt.jpg",
        "width": 1000,
        "height": 1000,
        "sizeBytes": 50000,
        "contentType": "image/jpeg"
      },
      "metadata": {
        "planId": "507f1f77bcf86cd799439013",
        "planName": "Professional Plan",
        "period": "monthly",
        "paymentMethod": "card",
        "discountPercentage": 10
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

Common Errors

400 Bad Request: Invalid query parameters (e.g., invalid date format, invalid payment type)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Admin does not have payments.view permission

500 Internal Server Error: Server error occurred while processing the request