Create Manual Payment (v1)

Method & Path

POST /api/v1/admin/payments

Description

Create a new manual payment record for a workspace. Manual payments are payments added by administrators for offline payments (e.g., cash, bank transfer) or to record payments that were processed outside the system.

Authentication

Required: Admin authentication with payments.manage permission.

Headers

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

Request Body

{
  "workspaceId": "507f1f77bcf86cd799439012",
  "paymentType": "subscription",
  "amount": 100.00,
  "paymentMethod": "cash",
  "paymentDate": "2025-01-15T10:30:00.000Z",
  "description": "Monthly subscription payment",
  "notes": "Payment received in cash",
  "receiptImage": {
    "url": "https://example.com/receipt.jpg",
    "path": "/uploads/receipts/receipt.jpg",
    "width": 1000,
    "height": 1000,
    "sizeBytes": 50000,
    "contentType": "image/jpeg"
  }
}

Request Body Schema

Field	Type	Required	Description
workspaceId	string	Yes	Workspace ID to associate payment with
paymentType	string	Yes	Payment type: ai-tools, sms, storage, or subscription
amount	number	Yes	Payment amount in USD (must be > 0)
paymentMethod	string	Yes	Payment method: cash, bank-transfer, card, or other
paymentDate	date	No	Payment date (defaults to current date/time)
description	string	No	Payment description
notes	string	No	Additional notes about the payment
receiptImage	object	No	Receipt image information

Receipt Image Schema

Field	Type	Required	Description
url	string	Yes	Public URL to the receipt image
path	string	Yes	Server path to the receipt image
width	number	No	Image width in pixels
height	number	No	Image height in pixels
sizeBytes	number	No	Image file size in bytes
contentType	string	Yes	MIME type of the image (e.g., image/jpeg)

Response 201 Created

{
  "id": "507f1f77bcf86cd799439011",
  "workspaceId": "507f1f77bcf86cd799439012",
  "paymentType": "subscription",
  "amount": 100.00,
  "paymentMethod": "cash",
  "paymentDate": "2025-01-15T10:30:00.000Z",
  "description": "Monthly subscription payment",
  "notes": "Payment received in cash",
  "isManual": true,
  "createdBy": "507f1f77bcf86cd799439014",
  "receiptImage": {
    "url": "https://example.com/receipt.jpg",
    "path": "/uploads/receipts/receipt.jpg",
    "width": 1000,
    "height": 1000,
    "sizeBytes": 50000,
    "contentType": "image/jpeg"
  },
  "metadata": {},
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Common Errors

400 Bad Request:

• Invalid workspace ID
• Invalid payment type
• Invalid payment method
• Amount must be greater than 0
• Missing required fields

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Admin does not have payments.manage permission

404 Not Found: Workspace not found

500 Internal Server Error: Server error occurred while creating the payment