Merge pull request 'docs fix' (#556) from docs-555 into main

Reviewed-on: #556

interface/api.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Sendico Payment API Contract
-  version: 1.0.0
+  version: 3.0.0
   summary: Minimal client contract for payment execution flows via BFF.
   description: |
     OpenAPI 3.1 contract focused on flows required to perform payments:

interface/api/accounts/auth_login.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Login using email/password and receive pending verification token
+  description: |
+    Validates account credentials and returns a short-lived `pendingToken`.
+    This endpoint does not return final access/refresh tokens; complete verification flow via `/verification/verify`.
   operationId: accountsLogin
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/LoginBody

interface/api/accounts/auth_refresh.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Refresh access token by refresh token
+  description: |
+    Validates refresh token + session identifiers and issues a new access token.
+    Use this endpoint when refresh token stays the same.
   operationId: accountsRefreshAccessToken
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody

interface/api/accounts/auth_rotate.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Rotate refresh token and issue new access/refresh tokens
+  description: |
+    Validates refresh token + session identifiers and returns a new token pair.
+    Use this endpoint when replacing both access and refresh tokens.
   operationId: accountsRotateRefreshToken
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody

interface/api/organizations/get.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Organizations]
   summary: Get organization by reference
+  description: Fetches a single organization available to the authenticated account.
   operationId: organizationsGet
   security:
     - bearerAuth: []

interface/api/organizations/root.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Organizations]
   summary: List organizations of current account
+  description: Returns organizations the authenticated account can access.
   operationId: organizationsList
   security:
     - bearerAuth: []

interface/api/parameters/archived.yaml

@@ -4,5 +4,6 @@ components:
       name: archived
       in: query
       required: false
+      description: Filter by archive flag. `true` returns archived records, `false` returns active records.
       schema:
         type: boolean

interface/api/parameters/cascade.yaml

@@ -4,5 +4,6 @@ components:
       name: cascade
       in: query
       required: false
+      description: If `true`, apply operation to dependent objects where cascade is supported.
       schema:
         type: boolean

interface/api/parameters/cursor.yaml

@@ -4,5 +4,6 @@ components:
       name: cursor
       in: query
       required: false
+      description: Opaque cursor from a previous page response (`page.next_cursor`).
       schema:
         type: string

interface/api/parameters/destination_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: destination_ref
       in: query
       required: false
+      description: Optional destination endpoint reference filter (service-specific usage).
       schema:
         type: string

interface/api/parameters/filter_states.yaml

@@ -4,5 +4,8 @@ components:
       name: filter_states
       in: query
       required: false
+      description: |
+        Additional payment state filter. Accepts one value or comma-separated values.
+        Same semantics as `state`/`states`.
       schema:
         type: string

interface/api/parameters/limit.yaml

@@ -3,9 +3,9 @@ components:
     Limit:
       name: limit
       in: query
-      description: Max number of items to return.
+      description: Max number of items to return. Parsed as non-negative int64.
       required: false
       schema:
         type: integer
-        format: int32
+        format: int64
         minimum: 0

interface/api/parameters/offset.yaml

@@ -3,9 +3,9 @@ components:
     Offset:
       name: offset
       in: query
-      description: Number of items to skip.
+      description: Number of items to skip. Parsed as non-negative int64.
       required: false
       schema:
         type: integer
-        format: int32
+        format: int64
         minimum: 0

interface/api/parameters/org_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: org_ref
       in: path
       required: true
+      description: Organization reference in BFF route format (Mongo ObjectId, 24 hex chars).
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/organizations_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: organizations_ref
       in: path
       required: true
+      description: Organization reference used by payments/payment-methods/recipients routes.
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/payment_methods_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: payment_methods_ref
       in: path
       required: true
+      description: Payment method reference (Mongo ObjectId, 24 hex chars).
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/recipients_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: recipients_ref
       in: path
       required: true
+      description: Recipient reference (Mongo ObjectId, 24 hex chars).
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/source_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: source_ref
       in: query
       required: false
+      description: Optional source endpoint reference filter (service-specific usage).
       schema:
         type: string

interface/api/parameters/state.yaml

@@ -4,5 +4,8 @@ components:
       name: state
       in: query
       required: false
+      description: |
+        Payment state filter. Accepts aliases like `accepted`, `settled`, `failed`
+        or canonical values like `orchestration_state_created`.
       schema:
         type: string

interface/api/parameters/states.yaml

@@ -4,5 +4,7 @@ components:
       name: states
       in: query
       required: false
+      description: |
+        Multi-state filter. Provide a comma-separated list with same accepted values as `state`.
       schema:
         type: string

interface/api/payment_methods/archive.yaml

@@ -1,6 +1,7 @@
 get:
   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: []
@@ -10,6 +11,7 @@ get:
     - 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

interface/api/payment_methods/create.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payment Methods]
   summary: Create payment method
+  description: Creates a payment method in the organization identified by `organizations_ref`.
   operationId: paymentMethodsCreate
   security:
     - bearerAuth: []

interface/api/payment_methods/list.yaml

@@ -1,6 +1,9 @@
 get:
   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: []

interface/api/payment_methods/object.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Payment Methods]
   summary: Get payment method
+  description: Returns payment method by `payment_methods_ref`.
   operationId: paymentMethodsGet
   security:
     - bearerAuth: []
@@ -32,6 +33,7 @@ get:
 delete:
   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: []

interface/api/payment_methods/update.yaml

@@ -1,6 +1,7 @@
 put:
   tags: [Payment Methods]
   summary: Update payment method
+  description: Updates payment method fields from request payload.
   operationId: paymentMethodsUpdate
   security:
     - bearerAuth: []

interface/api/payments/by_multiquote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Initiate payment batch by quote reference
+  description: Executes batch payment from a previously created multi-quote reference.
   operationId: paymentsInitiateBatchByQuote
   security:
     - bearerAuth: []

interface/api/payments/by_quote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Initiate payment using quote reference
+  description: Executes one payment from an existing quote reference (`quoteRef` required, `intent` forbidden).
   operationId: paymentsInitiateByQuote
   security:
     - bearerAuth: []

interface/api/payments/immediate.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Initiate payment from immediate intent
+  description: Creates quote and executes a single payment in one call (request must include `intent`).
   operationId: paymentsInitiateImmediate
   security:
     - bearerAuth: []

interface/api/payments/list.yaml

@@ -1,6 +1,9 @@
 get:
   tags: [Payments]
   summary: List payments in organization
+  description: |
+    Returns organization payments with cursor pagination and optional filters.
+    State filters accept aliases (`accepted`, `settled`, `failed`, etc.) or canonical orchestration states.
   operationId: paymentsList
   security:
     - bearerAuth: []
@@ -11,17 +14,20 @@ get:
     - name: quotation_ref
       in: query
       required: false
+      description: Filter by quotation reference used for execution.
       schema:
         type: string
     - name: created_from
       in: query
       required: false
+      description: Include payments created at or after this RFC3339 timestamp.
       schema:
         type: string
         format: date-time
     - name: created_to
       in: query
       required: false
+      description: Include payments created before this RFC3339 timestamp (must be after `created_from`).
       schema:
         type: string
         format: date-time

interface/api/payments/multiquote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Quote multiple payment intents
+  description: Calculates a batch quote for multiple payment intents in one request.
   operationId: paymentsMultiQuote
   security:
     - bearerAuth: []

interface/api/payments/quote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Quote single payment intent
+  description: Calculates quote for one payment intent without executing payment.
   operationId: paymentsQuote
   security:
     - bearerAuth: []

interface/api/payments/response/payment.yaml

@@ -31,9 +31,7 @@ components:
               type: string
             quoteRef:
               type: string
-            aggregate:
-              $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuoteAggregate
-            quotes:
+            items:
               type: array
               items:
                 $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
@@ -43,6 +41,7 @@ components:
       additionalProperties: false
       required:
         - accessToken
+        - payments
       properties:
         accessToken:
           $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData

interface/api/recipients/archive.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Recipients]
   summary: Archive/unarchive recipient
+  description: Sets recipient archive state by `recipients_ref` and required `archived` query parameter.
   operationId: recipientsArchive
   security:
     - bearerAuth: []
@@ -10,6 +11,7 @@ get:
     - name: archived
       in: query
       required: true
+      description: Target archive value to set on the recipient.
       schema:
         type: boolean
     - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade

interface/api/recipients/create.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Recipients]
   summary: Create recipient
+  description: Creates a recipient inside the organization identified by `org_ref`.
   operationId: recipientsCreate
   security:
     - bearerAuth: []

interface/api/recipients/list.yaml

@@ -1,6 +1,9 @@
 get:
   tags: [Recipients]
   summary: List recipients
+  description: |
+    Returns recipients for the specified organization context.
+    Supports offset pagination and optional archive filtering.
   operationId: recipientsList
   security:
     - bearerAuth: []

interface/api/recipients/object.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Recipients]
   summary: Get recipient by reference
+  description: Returns a recipient by `recipients_ref`.
   operationId: recipientsGet
   security:
     - bearerAuth: []
@@ -32,6 +33,7 @@ get:
 delete:
   tags: [Recipients]
   summary: Delete recipient
+  description: Deletes recipient by reference. Use `cascade=true` to remove dependent objects when supported.
   operationId: recipientsDelete
   security:
     - bearerAuth: []

interface/api/recipients/update.yaml

@@ -1,6 +1,7 @@
 put:
   tags: [Recipients]
   summary: Update recipient
+  description: Updates recipient fields from request payload.
   operationId: recipientsUpdate
   security:
     - bearerAuth: []

interface/api/verification/create.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Verification, Auth]
   summary: Request verification code
+  description: |
+    Creates a verification challenge for the specified purpose/target.
+    For `purpose=login`, request must be authorized with a pending account token.
   operationId: verificationRequestCode
   security:
     - bearerAuth: []

interface/api/verification/request/verification.yaml

@@ -5,7 +5,6 @@ components:
       additionalProperties: false
       required:
         - purpose
-        - idempotencyKey
       properties:
         purpose:
           type: string

interface/api/verification/resend.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Verification, Auth]
   summary: Resend verification code
+  description: |
+    Re-issues a verification challenge using the same request shape as `/verification`.
+    Cooldown and retry limits are enforced by backend verification storage policy.
   operationId: verificationResendCode
   security:
     - bearerAuth: []

interface/api/verification/verify.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Verification, Auth]
   summary: Verify code and complete pending flow
+  description: |
+    Verifies submitted code and consumes verification token.
+    For login purpose, returns full auth payload (access + refresh tokens); for other purposes returns operation result.
   operationId: verificationVerifyCode
   security:
     - bearerAuth: []

interface/external/endpoint_type.yaml

@@ -8,3 +8,4 @@ components:
         - cryptoAddress
         - card
         - cardToken
+        - wallet

interface/external/fx_side.yaml

@@ -3,6 +3,5 @@ components:
     FxSide:
       type: string
       enum:
-        - unspecified
         - buy_base_sell_quote
         - sell_base_buy_quote

interface/external/payment_kind.yaml

@@ -3,7 +3,6 @@ components:
     PaymentKind:
       type: string
       enum:
-        - unspecified
         - payout
         - internal_transfer
         - fx_conversion

interface/external/payment_state.yaml

@@ -3,10 +3,9 @@ components:
     PaymentState:
       type: string
       enum:
-        - payment_state_unspecified
-        - payment_state_accepted
-        - payment_state_funds_reserved
-        - payment_state_submitted
-        - payment_state_settled
-        - payment_state_failed
-        - payment_state_cancelled
+        - orchestration_state_unspecified
+        - orchestration_state_created
+        - orchestration_state_executing
+        - orchestration_state_needs_attention
+        - orchestration_state_settled
+        - orchestration_state_failed

interface/models/payment/payment.yaml

@@ -13,6 +13,9 @@ components:
 
     LedgerEndpoint:
       type: object
+      additionalProperties: false
+      required:
+        - ledger_account_ref
       properties:
         ledger_account_ref:
           type: string
@@ -21,6 +24,9 @@ components:
 
     ManagedWalletEndpoint:
       type: object
+      additionalProperties: false
+      required:
+        - managed_wallet_ref
       properties:
         managed_wallet_ref:
           type: string
@@ -29,6 +35,10 @@ components:
 
     ExternalChainEndpoint:
       type: object
+      additionalProperties: false
+      required:
+        - asset
+        - address
       properties:
         asset:
           $ref: ./payment.yaml#/components/schemas/Asset
@@ -39,6 +49,9 @@ components:
 
     CardEndpoint:
       type: object
+      additionalProperties: false
+      required:
+        - pan
       properties:
         pan:
           type: string
@@ -49,20 +62,34 @@ components:
         exp_month:
           type: integer
           format: int32
+          minimum: 0
         exp_year:
           type: integer
           format: int32
+          minimum: 0
         country:
           type: string
 
     CardTokenEndpoint:
       type: object
+      additionalProperties: false
+      required:
+        - token
       properties:
         token:
           type: string
         masked_pan:
           type: string
 
+    WalletEndpoint:
+      type: object
+      additionalProperties: false
+      required:
+        - walletId
+      properties:
+        walletId:
+          type: string
+
     Endpoint:
       type: object
       additionalProperties: false
@@ -73,8 +100,13 @@ components:
         type:
           $ref: ../../external/endpoint_type.yaml#/components/schemas/EndpointType
         data:
-          type: object
-          additionalProperties: true
+          oneOf:
+            - $ref: ./payment.yaml#/components/schemas/LedgerEndpoint
+            - $ref: ./payment.yaml#/components/schemas/ManagedWalletEndpoint
+            - $ref: ./payment.yaml#/components/schemas/ExternalChainEndpoint
+            - $ref: ./payment.yaml#/components/schemas/CardEndpoint
+            - $ref: ./payment.yaml#/components/schemas/CardTokenEndpoint
+            - $ref: ./payment.yaml#/components/schemas/WalletEndpoint
         metadata:
           type: object
           additionalProperties:
@@ -121,6 +153,7 @@ components:
       type: object
       additionalProperties: false
       required:
+        - pair
         - side
       properties:
         pair:
@@ -159,8 +192,12 @@ components:
           $ref: ./payment.yaml#/components/schemas/FxIntent
         settlement_mode:
           $ref: ../../external/settlement_mode.yaml#/components/schemas/SettlementMode
-        settlement_currency:
+        fee_treatment:
           type: string
+          enum:
+            - unspecified
+            - add_to_source
+            - deduct_from_destination
         attributes:
           type: object
           additionalProperties:
@@ -168,27 +205,6 @@ components:
         customer:
           $ref: ./payment.yaml#/components/schemas/Customer
 
-    PaymentQuote:
-      type: object
-      additionalProperties: false
-      properties:
-        quoteRef:
-          type: string
-        debitAmount:
-          $ref: ../common/money.yaml#/components/schemas/Money
-        debitSettlementAmount:
-          $ref: ../common/money.yaml#/components/schemas/Money
-        expectedSettlementAmount:
-          $ref: ../common/money.yaml#/components/schemas/Money
-        expectedFeeTotal:
-          $ref: ../common/money.yaml#/components/schemas/Money
-        feeLines:
-          type: array
-          items:
-            $ref: ./payment.yaml#/components/schemas/FeeLine
-        fxQuote:
-          $ref: ./payment.yaml#/components/schemas/FxQuote
-
     FeeLine:
       type: object
       additionalProperties: false
@@ -206,6 +222,26 @@ components:
           additionalProperties:
             type: string
 
+    QuoteFees:
+      type: object
+      additionalProperties: false
+      properties:
+        lines:
+          type: array
+          items:
+            $ref: ./payment.yaml#/components/schemas/FeeLine
+
+    QuoteAmounts:
+      type: object
+      additionalProperties: false
+      properties:
+        sourcePrincipal:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        sourceDebitTotal:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        destinationSettlement:
+          $ref: ../common/money.yaml#/components/schemas/Money
+
     FxQuote:
       type: object
       additionalProperties: false
@@ -237,22 +273,43 @@ components:
         firm:
           type: boolean
 
-    PaymentQuoteAggregate:
+    PaymentQuote:
       type: object
       additionalProperties: false
       properties:
-        debitAmounts:
-          type: array
-          items:
-            $ref: ../common/money.yaml#/components/schemas/Money
-        expectedSettlementAmounts:
-          type: array
-          items:
-            $ref: ../common/money.yaml#/components/schemas/Money
-        expectedFeeTotals:
-          type: array
-          items:
-            $ref: ../common/money.yaml#/components/schemas/Money
+        quoteRef:
+          type: string
+        intentRef:
+          type: string
+        amounts:
+          $ref: ./payment.yaml#/components/schemas/QuoteAmounts
+        fees:
+          $ref: ./payment.yaml#/components/schemas/QuoteFees
+        fxQuote:
+          $ref: ./payment.yaml#/components/schemas/FxQuote
+
+    PaymentOperation:
+      type: object
+      additionalProperties: false
+      properties:
+        stepRef:
+          type: string
+        code:
+          type: string
+        state:
+          type: string
+        label:
+          type: string
+        failureCode:
+          type: string
+        failureReason:
+          type: string
+        startedAt:
+          type: string
+          format: date-time
+        completedAt:
+          type: string
+          format: date-time
 
     Payment:
       type: object
@@ -268,6 +325,10 @@ components:
           type: string
         failureReason:
           type: string
+        operations:
+          type: array
+          items:
+            $ref: ./payment.yaml#/components/schemas/PaymentOperation
         lastQuote:
           $ref: ./payment.yaml#/components/schemas/PaymentQuote
         createdAt: