Update Manual Payment (v1)

Method & Path

PATCH /api/v1/admin/payments/:paymentId

Description

Update an existing manual payment record. Only manual payments (payments with isManual: true) can be updated. Automatic payments created by the system cannot be modified.

Authentication

Required: Admin authentication with payments.manage permission.

Headers

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

Path Parameters

Parameter	Type	Required	Description
paymentId	string	Yes	ID of the payment to update

Request Body

All fields are optional. Only include fields you want to update.

{
  "amount": 150.00,
  "paymentMethod": "bank-transfer",
  "paymentDate": "2025-01-16T10:30:00.000Z",
  "description": "Updated subscription payment",
  "notes": "Payment received via bank transfer",
  "receiptImage": {
    "url": "https://example.com/new-receipt.jpg",
    "path": "/uploads/receipts/new-receipt.jpg",
    "width": 1000,
    "height": 1000,
    "sizeBytes": 50000,
    "contentType": "image/jpeg"
  }
}

Request Body Schema

Field	Type	Required	Description
amount	number	No	Payment amount in USD (must be > 0 if provided)
paymentMethod	string	No	Payment method: cash, bank-transfer, card, or other
paymentDate	date	No	Payment date
description	string	No	Payment description
notes	string	No	Additional notes about the payment
receiptImage	object	No	Receipt image information (can be set to null to remove)

Response 200 OK

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

Common Errors

400 Bad Request:

• Invalid payment ID
• Invalid payment method
• Amount must be greater than 0

401 Unauthorized: Missing or invalid authentication token

403 Forbidden:

• Admin does not have payments.manage permission
• Payment is not a manual payment (automatic payments cannot be updated)

404 Not Found: Payment not found

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