docs fix

interface/api/payment_methods/archive.yaml

@@ -1,15 +1,17 @@
 get:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Archive/unarchive payment method
+  description: Sets payment method archive state by `payment_methods_ref` and required `archived` query parameter.
   operationId: paymentMethodsArchive
   security:
     - bearerAuth: []
   parameters:
     - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
-    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/Payment MethodsRef
     - name: archived
       in: query
       required: true
+      description: Target archive value to set on the payment method.
       schema:
         type: boolean
     - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
@@ -24,7 +26,7 @@ get:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/create.yaml

@@ -1,6 +1,7 @@
 post:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Create payment method
+  description: Creates a payment method in the organization identified by `organizations_ref`.
   operationId: paymentMethodsCreate
   security:
     - bearerAuth: []
@@ -19,7 +20,7 @@ post:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/list.yaml

@@ -1,6 +1,9 @@
 get:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: List payment methods for recipient
+  description: |
+    Returns payment methods available for `recipients_ref` within `organizations_ref`.
+    Supports offset pagination and optional archive filtering.
   operationId: paymentMethodsList
   security:
     - bearerAuth: []
@@ -21,7 +24,7 @@ get:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/object.yaml

@@ -1,11 +1,12 @@
 get:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Get payment method
+  description: Returns payment method by `payment_methods_ref`.
   operationId: paymentMethodsGet
   security:
     - bearerAuth: []
   parameters:
-    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/Payment MethodsRef
   responses:
     '200':
       description: Payment method data
@@ -17,7 +18,7 @@ get:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':
@@ -30,13 +31,14 @@ get:
       $ref: ../response/operation.yaml#/components/responses/InternalServerError
 
 delete:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Delete payment method
+  description: Deletes payment method by reference. Use `cascade=true` to remove dependent objects when supported.
   operationId: paymentMethodsDelete
   security:
     - bearerAuth: []
   parameters:
-    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/Payment MethodsRef
     - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
   responses:
     '200':
@@ -49,7 +51,7 @@ delete:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/response/payment_method.yaml

@@ -1,6 +1,6 @@
 components:
   schemas:
-    PaymentMethodsAuthData:
+    Payment MethodsAuthData:
       type: object
       additionalProperties: false
       required:

interface/api/payment_methods/update.yaml

@@ -1,6 +1,7 @@
 put:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Update payment method
+  description: Updates payment method fields from request payload.
   operationId: paymentMethodsUpdate
   security:
     - bearerAuth: []
@@ -17,7 +18,7 @@ put:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':