ci/dev/Caddyfile.dev

@@ -37,6 +37,26 @@
       header Cache-Control "no-cache, no-store, must-revalidate"
     }
 
+    ########################################
+    # API docs (ReDoc)
+    ########################################
+    handle /docs {
+      redir * /docs/ 308
+    }
+
+    handle /docs/ {
+      root * {vars.static_root}/docs
+      rewrite * /doc.html
+      file_server
+      header Cache-Control "no-cache"
+    }
+
+    handle_path /docs/* {
+      root * {vars.static_root}/docs
+      file_server
+      header Cache-Control "no-cache"
+    }
+
     ########################################
     # Static assets
     ########################################

ci/dev/frontend.dockerfile

@@ -48,6 +48,7 @@ FROM caddy:alpine AS runtime
 WORKDIR /usr/share/pweb
 
 COPY --from=web_builder /home/flutteruser/app/pweb/build/web /usr/share/pweb
+COPY interface /usr/share/pweb/docs
 
 # Copy Caddy config (will be mounted from host)
 # COPY frontend/pweb/caddy/Caddyfile /etc/caddy/Caddyfile

ci/prod/compose/frontend.dockerfile

@@ -45,6 +45,7 @@ WORKDIR /usr/share/pweb
 COPY frontend/pweb/entrypoint.sh /entrypoint.sh
 COPY frontend/pweb/caddy/Caddyfile /etc/caddy/Caddyfile
 COPY --from=web_builder /home/flutteruser/app/pweb/build/web /usr/share/pweb
+COPY interface /usr/share/pweb/docs
 
 RUN chmod +x /entrypoint.sh
 

interface/api.yaml

@@ -0,0 +1,89 @@
+openapi: 3.1.0
+info:
+  title: Sendico Payment API Contract
+  version: 1.0.0
+  summary: Minimal client contract for payment execution flows via BFF.
+  description: |
+    OpenAPI 3.1 contract focused on flows required to perform payments:
+    authentication, verification, recipients, payment methods and payments.
+servers:
+  - url: /api/v1
+    description: Main HTTP API base path
+
+tags:
+  - name: Auth
+    description: Authentication and token lifecycle
+  - name: Accounts
+    description: Account auth responses used by login/verification
+  - name: Verification
+    description: Pending-account code verification
+  - name: Organizations
+    description: Organization selection for payment operations
+  - name: Recipients
+    description: Recipient CRUD and archive flows
+  - name: PaymentMethods
+    description: Payment method CRUD and archive flows
+  - name: Payments
+    description: Quotation and payment orchestration
+
+paths:
+  /accounts/login:
+    $ref: ./api/accounts/auth_login.yaml
+  /accounts/rotate:
+    $ref: ./api/accounts/auth_rotate.yaml
+  /accounts/refresh:
+    $ref: ./api/accounts/auth_refresh.yaml
+
+  /verification:
+    $ref: ./api/verification/create.yaml
+  /verification/resend:
+    $ref: ./api/verification/resend.yaml
+  /verification/verify:
+    $ref: ./api/verification/verify.yaml
+
+  /organizations:
+    $ref: ./api/organizations/root.yaml
+  /organizations/{org_ref}:
+    $ref: ./api/organizations/get.yaml
+
+  /recipients/list/{org_ref}/{organizations_ref}:
+    $ref: ./api/recipients/list.yaml
+  /recipients/{org_ref}:
+    $ref: ./api/recipients/create.yaml
+  /recipients/{recipients_ref}:
+    $ref: ./api/recipients/object.yaml
+  /recipients:
+    $ref: ./api/recipients/update.yaml
+  /recipients/archive/{org_ref}/{recipients_ref}:
+    $ref: ./api/recipients/archive.yaml
+
+  /payment_methods/list/{organizations_ref}/{recipients_ref}:
+    $ref: ./api/payment_methods/list.yaml
+  /payment_methods/{organizations_ref}:
+    $ref: ./api/payment_methods/create.yaml
+  /payment_methods/{payment_methods_ref}:
+    $ref: ./api/payment_methods/object.yaml
+  /payment_methods:
+    $ref: ./api/payment_methods/update.yaml
+  /payment_methods/archive/{organizations_ref}/{payment_methods_ref}:
+    $ref: ./api/payment_methods/archive.yaml
+
+  /payments/quote/{organizations_ref}:
+    $ref: ./api/payments/quote.yaml
+  /payments/multiquote/{organizations_ref}:
+    $ref: ./api/payments/multiquote.yaml
+  /payments/immediate/{organizations_ref}:
+    $ref: ./api/payments/immediate.yaml
+  /payments/by-quote/{organizations_ref}:
+    $ref: ./api/payments/by_quote.yaml
+  /payments/by-multiquote/{organizations_ref}:
+    $ref: ./api/payments/by_multiquote.yaml
+  /payments/{organizations_ref}:
+    $ref: ./api/payments/list.yaml
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT

interface/api/accounts/auth_login.yaml

@@ -0,0 +1,26 @@
+post:
+  tags: [Accounts, Auth]
+  summary: Login using email/password and receive pending verification token
+  operationId: accountsLogin
+  requestBody:
+    $ref: ./bodies/auth.yaml#/components/requestBodies/LoginBody
+  responses:
+    '202':
+      description: Pending verification token issued
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/auth.yaml#/components/schemas/PendingLoginData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/accounts/auth_refresh.yaml

@@ -0,0 +1,28 @@
+post:
+  tags: [Accounts, Auth]
+  summary: Refresh access token by refresh token
+  operationId: accountsRefreshAccessToken
+  requestBody:
+    $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody
+  responses:
+    '200':
+      description: Access token refreshed
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/auth.yaml#/components/schemas/AccountAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/accounts/auth_rotate.yaml

@@ -0,0 +1,28 @@
+post:
+  tags: [Accounts, Auth]
+  summary: Rotate refresh token and issue new access/refresh tokens
+  operationId: accountsRotateRefreshToken
+  requestBody:
+    $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody
+  responses:
+    '200':
+      description: New token pair issued
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/auth.yaml#/components/schemas/LoginData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/accounts/bodies/auth.yaml

@@ -0,0 +1,15 @@
+components:
+  requestBodies:
+    LoginBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/auth.yaml#/components/schemas/LoginRequest
+
+    RefreshTokenBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/auth.yaml#/components/schemas/RefreshTokenRequest

interface/api/accounts/request/auth.yaml

@@ -0,0 +1,17 @@
+components:
+  schemas:
+    LoginRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - login
+      properties:
+        clientId:
+          type: string
+        deviceId:
+          type: string
+        login:
+          $ref: ../../../models/auth/login_data.yaml#/components/schemas/LoginData
+
+    RefreshTokenRequest:
+      $ref: ../../../models/auth/client_refresh_token.yaml#/components/schemas/ClientRefreshToken

interface/api/accounts/response/auth.yaml

@@ -0,0 +1,49 @@
+components:
+  schemas:
+    AccountAuthData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - account
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        account:
+          $ref: ../../../models/account/account.yaml#/components/schemas/AccountData
+
+    LoginData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - account
+        - refreshToken
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        account:
+          $ref: ../../../models/account/account.yaml#/components/schemas/AccountData
+        refreshToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+
+    PendingLoginData:
+      type: object
+      additionalProperties: false
+      required:
+        - account
+        - pendingToken
+        - target
+      properties:
+        account:
+          type: object
+          additionalProperties: false
+          properties:
+            accessToken:
+              $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+            account:
+              $ref: ../../../models/account/account.yaml#/components/schemas/AccountData
+        pendingToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        target:
+          type: string

interface/api/organizations/get.yaml

@@ -0,0 +1,28 @@
+get:
+  tags: [Organizations]
+  summary: Get organization by reference
+  operationId: organizationsGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+  responses:
+    '200':
+      description: Organization details
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/organization.yaml#/components/schemas/OrganizationsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/organizations/response/organization.yaml

@@ -0,0 +1,15 @@
+components:
+  schemas:
+    OrganizationsAuthData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - organizations
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        organizations:
+          type: array
+          items:
+            $ref: ../../../models/organization/organization.yaml#/components/schemas/Organization

interface/api/organizations/root.yaml

@@ -0,0 +1,26 @@
+get:
+  tags: [Organizations]
+  summary: List organizations of current account
+  operationId: organizationsList
+  security:
+    - bearerAuth: []
+  responses:
+    '200':
+      description: Organizations list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/organization.yaml#/components/schemas/OrganizationsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/parameters/archived.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    Archived:
+      name: archived
+      in: query
+      required: false
+      schema:
+        type: boolean

interface/api/parameters/cascade.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    Cascade:
+      name: cascade
+      in: query
+      required: false
+      schema:
+        type: boolean

interface/api/parameters/cursor.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    Cursor:
+      name: cursor
+      in: query
+      required: false
+      schema:
+        type: string

interface/api/parameters/destination_ref.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    DestinationRef:
+      name: destination_ref
+      in: query
+      required: false
+      schema:
+        type: string

interface/api/parameters/filter_states.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    FilterStates:
+      name: filter_states
+      in: query
+      required: false
+      schema:
+        type: string

interface/api/parameters/limit.yaml

@@ -0,0 +1,11 @@
+components:
+  parameters:
+    Limit:
+      name: limit
+      in: query
+      description: Max number of items to return.
+      required: false
+      schema:
+        type: integer
+        format: int32
+        minimum: 0

interface/api/parameters/offset.yaml

@@ -0,0 +1,11 @@
+components:
+  parameters:
+    Offset:
+      name: offset
+      in: query
+      description: Number of items to skip.
+      required: false
+      schema:
+        type: integer
+        format: int32
+        minimum: 0

interface/api/parameters/org_ref.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    OrgRef:
+      name: org_ref
+      in: path
+      required: true
+      schema:
+        $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/organizations_ref.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    OrganizationsRef:
+      name: organizations_ref
+      in: path
+      required: true
+      schema:
+        $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/payment_methods_ref.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    PaymentMethodsRef:
+      name: payment_methods_ref
+      in: path
+      required: true
+      schema:
+        $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/recipients_ref.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    RecipientsRef:
+      name: recipients_ref
+      in: path
+      required: true
+      schema:
+        $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/source_ref.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    SourceRef:
+      name: source_ref
+      in: query
+      required: false
+      schema:
+        type: string

interface/api/parameters/state.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    State:
+      name: state
+      in: query
+      required: false
+      schema:
+        type: string

interface/api/parameters/states.yaml

@@ -0,0 +1,8 @@
+components:
+  parameters:
+    States:
+      name: states
+      in: query
+      required: false
+      schema:
+        type: string

interface/api/payment_methods/archive.yaml

@@ -0,0 +1,35 @@
+get:
+  tags: [PaymentMethods]
+  summary: Archive/unarchive payment method
+  operationId: paymentMethodsArchive
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - name: archived
+      in: query
+      required: true
+      schema:
+        type: boolean
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Archive state updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payment_methods/bodies/payment_method.yaml

@@ -0,0 +1,8 @@
+components:
+  requestBodies:
+    PaymentMethodBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment_method.yaml#/components/schemas/PaymentMethodRequest

interface/api/payment_methods/create.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [PaymentMethods]
+  summary: Create payment method
+  operationId: paymentMethodsCreate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment_method.yaml#/components/requestBodies/PaymentMethodBody
+  responses:
+    '201':
+      description: Payment method created
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payment_methods/list.yaml

@@ -0,0 +1,34 @@
+get:
+  tags: [PaymentMethods]
+  summary: List payment methods for recipient
+  operationId: paymentMethodsList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/recipients_ref.yaml#/components/parameters/RecipientsRef
+    - $ref: ../parameters/limit.yaml#/components/parameters/Limit
+    - $ref: ../parameters/offset.yaml#/components/parameters/Offset
+    - $ref: ../parameters/archived.yaml#/components/parameters/Archived
+  responses:
+    '200':
+      description: Payment methods list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payment_methods/object.yaml

@@ -0,0 +1,62 @@
+get:
+  tags: [PaymentMethods]
+  summary: Get payment method
+  operationId: paymentMethodsGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+  responses:
+    '200':
+      description: Payment method data
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+
+delete:
+  tags: [PaymentMethods]
+  summary: Delete payment method
+  operationId: paymentMethodsDelete
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Payment method deleted
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payment_methods/request/payment_method.yaml

@@ -0,0 +1,4 @@
+components:
+  schemas:
+    PaymentMethodRequest:
+      $ref: ../../../models/payment_method/payment_method.yaml#/components/schemas/PaymentMethod

interface/api/payment_methods/response/payment_method.yaml

@@ -0,0 +1,15 @@
+components:
+  schemas:
+    PaymentMethodsAuthData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - payment_methods
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        payment_methods:
+          type: array
+          items:
+            $ref: ../../../models/payment_method/payment_method.yaml#/components/schemas/PaymentMethod

interface/api/payment_methods/update.yaml

@@ -0,0 +1,32 @@
+put:
+  tags: [PaymentMethods]
+  summary: Update payment method
+  operationId: paymentMethodsUpdate
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/payment_method.yaml#/components/requestBodies/PaymentMethodBody
+  responses:
+    '200':
+      description: Payment method updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/bodies/payment.yaml

@@ -0,0 +1,29 @@
+components:
+  requestBodies:
+    QuotePaymentBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/QuotePaymentRequest
+
+    QuotePaymentsBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/QuotePaymentsRequest
+
+    InitiatePaymentBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/InitiatePaymentRequest
+
+    InitiatePaymentsBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/InitiatePaymentsRequest

interface/api/payments/by_multiquote.yaml

@@ -0,0 +1,30 @@
+post:
+  tags: [Payments]
+  summary: Initiate payment batch by quote reference
+  operationId: paymentsInitiateBatchByQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment.yaml#/components/requestBodies/InitiatePaymentsBody
+  responses:
+    '200':
+      description: Payment batch initiated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentsData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/by_quote.yaml

@@ -0,0 +1,41 @@
+post:
+  tags: [Payments]
+  summary: Initiate payment using quote reference
+  operationId: paymentsInitiateByQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          allOf:
+            - $ref: ./request/payment.yaml#/components/schemas/InitiatePaymentRequest
+            - type: object
+              required:
+                - quoteRef
+              not:
+                required:
+                  - intent
+  responses:
+    '200':
+      description: Payment initiated by quote
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/immediate.yaml

@@ -0,0 +1,41 @@
+post:
+  tags: [Payments]
+  summary: Initiate payment from immediate intent
+  operationId: paymentsInitiateImmediate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          allOf:
+            - $ref: ./request/payment.yaml#/components/schemas/InitiatePaymentRequest
+            - type: object
+              required:
+                - intent
+              not:
+                required:
+                  - quoteRef
+  responses:
+    '200':
+      description: Payment initiated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/list.yaml

@@ -0,0 +1,50 @@
+get:
+  tags: [Payments]
+  summary: List payments in organization
+  operationId: paymentsList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/cursor.yaml#/components/parameters/Cursor
+    - $ref: ../parameters/limit.yaml#/components/parameters/Limit
+    - name: quotation_ref
+      in: query
+      required: false
+      schema:
+        type: string
+    - name: created_from
+      in: query
+      required: false
+      schema:
+        type: string
+        format: date-time
+    - name: created_to
+      in: query
+      required: false
+      schema:
+        type: string
+        format: date-time
+    - $ref: ../parameters/state.yaml#/components/parameters/State
+    - $ref: ../parameters/states.yaml#/components/parameters/States
+    - $ref: ../parameters/filter_states.yaml#/components/parameters/FilterStates
+  responses:
+    '200':
+      description: Payments list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentsData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/multiquote.yaml

@@ -0,0 +1,30 @@
+post:
+  tags: [Payments]
+  summary: Quote multiple payment intents
+  operationId: paymentsMultiQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment.yaml#/components/requestBodies/QuotePaymentsBody
+  responses:
+    '200':
+      description: Quotes generated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentQuotesData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/quote.yaml

@@ -0,0 +1,30 @@
+post:
+  tags: [Payments]
+  summary: Quote single payment intent
+  operationId: paymentsQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment.yaml#/components/requestBodies/QuotePaymentBody
+  responses:
+    '200':
+      description: Quote generated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentQuoteData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/payments/request/payment.yaml

@@ -0,0 +1,104 @@
+components:
+  schemas:
+    PaymentBase:
+      type: object
+      additionalProperties: false
+      required:
+        - idempotencyKey
+      properties:
+        idempotencyKey:
+          type: string
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+
+    QuotePaymentRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - intent
+      properties:
+        idempotencyKey:
+          type: string
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+        intent:
+          $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
+        previewOnly:
+          type: boolean
+      allOf:
+        - if:
+            properties:
+              previewOnly:
+                const: true
+            required:
+              - previewOnly
+          then:
+            not:
+              required:
+                - idempotencyKey
+          else:
+            required:
+              - idempotencyKey
+
+    QuotePaymentsRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - intents
+      properties:
+        idempotencyKey:
+          type: string
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+        intents:
+          type: array
+          minItems: 1
+          items:
+            $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
+        previewOnly:
+          type: boolean
+      allOf:
+        - if:
+            properties:
+              previewOnly:
+                const: true
+            required:
+              - previewOnly
+          then:
+            not:
+              required:
+                - idempotencyKey
+          else:
+            required:
+              - idempotencyKey
+
+    InitiatePaymentRequest:
+      allOf:
+        - $ref: ./payment.yaml#/components/schemas/PaymentBase
+        - type: object
+          additionalProperties: false
+          oneOf:
+            - required: [intent]
+            - required: [quoteRef]
+          properties:
+            intent:
+              $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
+            quoteRef:
+              type: string
+
+    InitiatePaymentsRequest:
+      allOf:
+        - $ref: ./payment.yaml#/components/schemas/PaymentBase
+        - type: object
+          additionalProperties: false
+          required:
+            - quoteRef
+          properties:
+            quoteRef:
+              type: string

interface/api/payments/response/payment.yaml

@@ -0,0 +1,66 @@
+components:
+  schemas:
+    PaymentQuoteData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - quote
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        idempotencyKey:
+          type: string
+        quote:
+          $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
+
+    PaymentQuotesData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - quote
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        quote:
+          type: object
+          additionalProperties: false
+          properties:
+            idempotencyKey:
+              type: string
+            quoteRef:
+              type: string
+            aggregate:
+              $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuoteAggregate
+            quotes:
+              type: array
+              items:
+                $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
+
+    PaymentsData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        payments:
+          type: array
+          items:
+            $ref: ../../../models/payment/payment.yaml#/components/schemas/Payment
+        page:
+          $ref: ../../../models/common/pagination.yaml#/components/schemas/CursorPageResponse
+
+    PaymentData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - payment
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        payment:
+          $ref: ../../../models/payment/payment.yaml#/components/schemas/Payment

interface/api/recipients/archive.yaml

@@ -0,0 +1,35 @@
+get:
+  tags: [Recipients]
+  summary: Archive/unarchive recipient
+  operationId: recipientsArchive
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+    - $ref: ../parameters/recipients_ref.yaml#/components/parameters/RecipientsRef
+    - name: archived
+      in: query
+      required: true
+      schema:
+        type: boolean
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Archive state updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/recipient.yaml#/components/schemas/RecipientsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/recipients/bodies/recipient.yaml

@@ -0,0 +1,8 @@
+components:
+  requestBodies:
+    RecipientBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/recipient.yaml#/components/schemas/RecipientRequest

interface/api/recipients/create.yaml

@@ -0,0 +1,32 @@
+post:
+  tags: [Recipients]
+  summary: Create recipient
+  operationId: recipientsCreate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+  requestBody:
+    $ref: ./bodies/recipient.yaml#/components/requestBodies/RecipientBody
+  responses:
+    '201':
+      description: Recipient created
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/recipient.yaml#/components/schemas/RecipientsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/recipients/list.yaml

@@ -0,0 +1,32 @@
+get:
+  tags: [Recipients]
+  summary: List recipients
+  operationId: recipientsList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/org_ref.yaml#/components/parameters/OrgRef
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/limit.yaml#/components/parameters/Limit
+    - $ref: ../parameters/offset.yaml#/components/parameters/Offset
+    - $ref: ../parameters/archived.yaml#/components/parameters/Archived
+  responses:
+    '200':
+      description: Recipient list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/recipient.yaml#/components/schemas/RecipientsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/recipients/object.yaml

@@ -0,0 +1,62 @@
+get:
+  tags: [Recipients]
+  summary: Get recipient by reference
+  operationId: recipientsGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/recipients_ref.yaml#/components/parameters/RecipientsRef
+  responses:
+    '200':
+      description: Recipient data
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/recipient.yaml#/components/schemas/RecipientsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+
+delete:
+  tags: [Recipients]
+  summary: Delete recipient
+  operationId: recipientsDelete
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/recipients_ref.yaml#/components/parameters/RecipientsRef
+    - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
+  responses:
+    '200':
+      description: Recipient deleted
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/recipient.yaml#/components/schemas/RecipientsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/recipients/request/recipient.yaml

@@ -0,0 +1,4 @@
+components:
+  schemas:
+    RecipientRequest:
+      $ref: ../../../models/recipient/recipient.yaml#/components/schemas/Recipient

interface/api/recipients/response/recipient.yaml

@@ -0,0 +1,15 @@
+components:
+  schemas:
+    RecipientsAuthData:
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - recipients
+      properties:
+        accessToken:
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        recipients:
+          type: array
+          items:
+            $ref: ../../../models/recipient/recipient.yaml#/components/schemas/Recipient

interface/api/recipients/update.yaml

@@ -0,0 +1,30 @@
+put:
+  tags: [Recipients]
+  summary: Update recipient
+  operationId: recipientsUpdate
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/recipient.yaml#/components/requestBodies/RecipientBody
+  responses:
+    '200':
+      description: Recipient updated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/recipient.yaml#/components/schemas/RecipientsAuthData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/response/error.yaml

@@ -0,0 +1,19 @@
+components:
+  schemas:
+    ApiError:
+      type: object
+      additionalProperties: false
+      required:
+        - code
+        - error
+        - source
+      properties:
+        code:
+          type: integer
+          format: int32
+        error:
+          type: string
+        source:
+          type: string
+        details:
+          type: string

interface/api/response/operation.yaml

@@ -0,0 +1,78 @@
+components:
+  responses:
+    Ok:
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/BaseResponse
+
+    Created:
+      description: Resource created
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/BaseResponse
+
+    Accepted:
+      description: Request accepted for processing
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/BaseResponse
+
+    BadRequest:
+      description: Bad request payload or query/path parameter
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Forbidden:
+      description: Forbidden
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Gone:
+      description: Resource is no longer available
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    Conflict:
+      description: Conflict
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    TooManyRequests:
+      description: Too many requests
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse
+
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: ./response.yaml#/components/schemas/ErrorResponse

interface/api/response/response.yaml

@@ -0,0 +1,47 @@
+components:
+  schemas:
+    BaseResponse:
+      type: object
+      additionalProperties: false
+      required:
+        - status
+        - data
+      properties:
+        status:
+          $ref: ./status.yaml#/components/schemas/ApiStatus
+        data:
+          description: Payload for success or error responses.
+
+    ErrorResponse:
+      allOf:
+        - $ref: ./response.yaml#/components/schemas/BaseResponse
+        - type: object
+          properties:
+            status:
+              type: string
+              enum:
+                - error
+            data:
+              $ref: ./error.yaml#/components/schemas/ApiError
+
+    SuccessResultData:
+      type: object
+      additionalProperties: false
+      required:
+        - result
+      properties:
+        result:
+          type: boolean
+
+    SuccessResultResponse:
+      allOf:
+        - $ref: ./response.yaml#/components/schemas/BaseResponse
+        - type: object
+          properties:
+            status:
+              type: string
+              enum:
+                - success
+                - processed
+            data:
+              $ref: ./response.yaml#/components/schemas/SuccessResultData

interface/api/response/status.yaml

@@ -0,0 +1,10 @@
+components:
+  schemas:
+    ApiStatus:
+      type: string
+      description: Unified response status used by backend wrappers.
+      enum:
+        - success
+        - processed
+        - error
+        - request

interface/api/verification/bodies/verification.yaml

@@ -0,0 +1,15 @@
+components:
+  requestBodies:
+    VerificationCodeBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/verification.yaml#/components/schemas/VerificationCodeRequest
+
+    VerifyCodeBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/verification.yaml#/components/schemas/CodeVerificationRequest

interface/api/verification/create.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Verification, Auth]
+  summary: Request verification code
+  operationId: verificationRequestCode
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/verification.yaml#/components/requestBodies/VerificationCodeBody
+  responses:
+    '202':
+      description: Verification code requested
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/verification.yaml#/components/schemas/VerificationResponseData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '429':
+      $ref: ../response/operation.yaml#/components/responses/TooManyRequests
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/verification/request/verification.yaml

@@ -0,0 +1,31 @@
+components:
+  schemas:
+    VerificationCodeRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - purpose
+        - idempotencyKey
+      properties:
+        purpose:
+          type: string
+          description: Verification purpose, e.g. login.
+        target:
+          type: string
+          format: email
+        idempotencyKey:
+          type: string
+
+    CodeVerificationRequest:
+      allOf:
+        - $ref: ./verification.yaml#/components/schemas/VerificationCodeRequest
+        - type: object
+          additionalProperties: false
+          required:
+            - code
+            - sessionIdentifier
+          properties:
+            code:
+              type: string
+            sessionIdentifier:
+              $ref: ../../../models/auth/session_identifier.yaml#/components/schemas/SessionIdentifier

interface/api/verification/resend.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Verification, Auth]
+  summary: Resend verification code
+  operationId: verificationResendCode
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/verification.yaml#/components/requestBodies/VerificationCodeBody
+  responses:
+    '202':
+      description: Verification code resent
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/verification.yaml#/components/schemas/VerificationResponseData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '429':
+      $ref: ../response/operation.yaml#/components/responses/TooManyRequests
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/api/verification/response/verification.yaml

@@ -0,0 +1,26 @@
+components:
+  schemas:
+    VerificationResponseData:
+      type: object
+      additionalProperties: false
+      required:
+        - idempotencyKey
+        - ttl_seconds
+        - cooldown_seconds
+        - target
+      properties:
+        idempotencyKey:
+          type: string
+        ttl_seconds:
+          type: integer
+          format: int32
+        cooldown_seconds:
+          type: integer
+          format: int32
+        target:
+          type: string
+
+    VerifyResultData:
+      oneOf:
+        - $ref: ../../accounts/response/auth.yaml#/components/schemas/LoginData
+        - $ref: ../../response/response.yaml#/components/schemas/SuccessResultData

interface/api/verification/verify.yaml

@@ -0,0 +1,34 @@
+post:
+  tags: [Verification, Auth]
+  summary: Verify code and complete pending flow
+  operationId: verificationVerifyCode
+  security:
+    - bearerAuth: []
+  requestBody:
+    $ref: ./bodies/verification.yaml#/components/requestBodies/VerifyCodeBody
+  responses:
+    '200':
+      description: Verification successful
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/verification.yaml#/components/schemas/VerifyResultData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '410':
+      $ref: ../response/operation.yaml#/components/responses/Gone
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError

interface/doc.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Sendico API Docs (Redoc)</title>
+  <style>
+    html, body { margin: 0; height: 100%; }
+  </style>
+</head>
+<body>
+  <redoc spec-url="./api.yaml"></redoc>
+  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+</body>
+</html>

interface/external/chain_network.yaml

@@ -0,0 +1,10 @@
+components:
+  schemas:
+    ChainNetwork:
+      type: string
+      enum:
+        - unspecified
+        - ethereum_mainnet
+        - arbitrum_one
+        - tron_mainnet
+        - tron_nile

interface/external/endpoint_type.yaml

@@ -0,0 +1,10 @@
+components:
+  schemas:
+    EndpointType:
+      type: string
+      enum:
+        - ledger
+        - managedWallet
+        - cryptoAddress
+        - card
+        - cardToken

interface/external/fx_side.yaml

@@ -0,0 +1,8 @@
+components:
+  schemas:
+    FxSide:
+      type: string
+      enum:
+        - unspecified
+        - buy_base_sell_quote
+        - sell_base_buy_quote

interface/external/payment_kind.yaml

@@ -0,0 +1,9 @@
+components:
+  schemas:
+    PaymentKind:
+      type: string
+      enum:
+        - unspecified
+        - payout
+        - internal_transfer
+        - fx_conversion

interface/external/payment_method_type.yaml

@@ -0,0 +1,12 @@
+components:
+  schemas:
+    PaymentMethodType:
+      type: string
+      enum:
+        - iban
+        - card
+        - cardToken
+        - bankAccount
+        - wallet
+        - cryptoAddress
+        - ledger

interface/external/payment_state.yaml

@@ -0,0 +1,12 @@
+components:
+  schemas:
+    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

interface/external/settlement_mode.yaml

@@ -0,0 +1,8 @@
+components:
+  schemas:
+    SettlementMode:
+      type: string
+      enum:
+        - unspecified
+        - fix_source
+        - fix_received

interface/models/account/account.yaml

@@ -0,0 +1,12 @@
+components:
+  schemas:
+    AccountData:
+      allOf:
+        - $ref: ./account_public.yaml#/components/schemas/AccountPublic
+        - type: object
+          additionalProperties: false
+          required:
+            - isAnonymous
+          properties:
+            isAnonymous:
+              type: boolean

interface/models/account/account_public.yaml

@@ -0,0 +1,26 @@
+components:
+  schemas:
+    AccountPublic:
+      allOf:
+        - $ref: ../storable.yaml#/components/schemas/Storable
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - login
+            - locale
+            - lastName
+            - isArchived
+          properties:
+            login:
+              type: string
+              format: email
+            locale:
+              type: string
+            lastName:
+              type: string
+            avatarUrl:
+              type: string
+              nullable: true
+            isArchived:
+              type: boolean

interface/models/auth/client_refresh_token.yaml

@@ -0,0 +1,12 @@
+components:
+  schemas:
+    ClientRefreshToken:
+      allOf:
+        - $ref: ./session_identifier.yaml#/components/schemas/SessionIdentifier
+        - type: object
+          additionalProperties: false
+          required:
+            - token
+          properties:
+            token:
+              type: string

interface/models/auth/login_data.yaml

@@ -0,0 +1,17 @@
+components:
+  schemas:
+    LoginData:
+      type: object
+      additionalProperties: false
+      required:
+        - login
+        - password
+      properties:
+        login:
+          type: string
+          format: email
+        password:
+          type: string
+          format: password
+        locale:
+          type: string

interface/models/auth/session_identifier.yaml

@@ -0,0 +1,13 @@
+components:
+  schemas:
+    SessionIdentifier:
+      type: object
+      additionalProperties: false
+      required:
+        - clientId
+        - deviceId
+      properties:
+        clientId:
+          type: string
+        deviceId:
+          type: string

interface/models/auth/token_data.yaml

@@ -0,0 +1,14 @@
+components:
+  schemas:
+    TokenData:
+      type: object
+      additionalProperties: false
+      required:
+        - token
+        - expiration
+      properties:
+        token:
+          type: string
+        expiration:
+          type: string
+          format: date-time

interface/models/common/describable.yaml

@@ -0,0 +1,13 @@
+components:
+  schemas:
+    Describable:
+      type: object
+      additionalProperties: false
+      required:
+        - name
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+          nullable: true

interface/models/common/money.yaml

@@ -0,0 +1,16 @@
+components:
+  schemas:
+    Money:
+      type: object
+      additionalProperties: false
+      required:
+        - amount
+        - currency
+      properties:
+        amount:
+          type: string
+          description: Decimal string amount.
+          example: '125.50'
+        currency:
+          type: string
+          example: USD

interface/models/common/pagination.yaml

@@ -0,0 +1,8 @@
+components:
+  schemas:
+    CursorPageResponse:
+      type: object
+      additionalProperties: false
+      properties:
+        next_cursor:
+          type: string

interface/models/objectid.yaml

@@ -0,0 +1,7 @@
+components:
+  schemas:
+    ObjectId:
+      type: string
+      pattern: '^[a-fA-F0-9]{24}$'
+      examples:
+        - 64f85f5f4c7dbf7cfb8f3f10

interface/models/organization/organization.yaml

@@ -0,0 +1,32 @@
+components:
+  schemas:
+    OrganizationBase:
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - tenantRef
+            - timeZone
+          properties:
+            tenantRef:
+              $ref: ../objectid.yaml#/components/schemas/ObjectId
+            timeZone:
+              type: string
+            logoUrl:
+              type: string
+              nullable: true
+
+    Organization:
+      allOf:
+        - $ref: ./organization.yaml#/components/schemas/OrganizationBase
+        - type: object
+          additionalProperties: false
+          required:
+            - members
+          properties:
+            members:
+              type: array
+              items:
+                $ref: ../objectid.yaml#/components/schemas/ObjectId

interface/models/payment/payment.yaml

@@ -0,0 +1,279 @@
+components:
+  schemas:
+    Asset:
+      type: object
+      additionalProperties: false
+      properties:
+        chain:
+          $ref: ../../external/chain_network.yaml#/components/schemas/ChainNetwork
+        token_symbol:
+          type: string
+        contract_address:
+          type: string
+
+    LedgerEndpoint:
+      type: object
+      properties:
+        ledger_account_ref:
+          type: string
+        contra_ledger_account_ref:
+          type: string
+
+    ManagedWalletEndpoint:
+      type: object
+      properties:
+        managed_wallet_ref:
+          type: string
+        asset:
+          $ref: ./payment.yaml#/components/schemas/Asset
+
+    ExternalChainEndpoint:
+      type: object
+      properties:
+        asset:
+          $ref: ./payment.yaml#/components/schemas/Asset
+        address:
+          type: string
+        memo:
+          type: string
+
+    CardEndpoint:
+      type: object
+      properties:
+        pan:
+          type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+        exp_month:
+          type: integer
+          format: int32
+        exp_year:
+          type: integer
+          format: int32
+        country:
+          type: string
+
+    CardTokenEndpoint:
+      type: object
+      properties:
+        token:
+          type: string
+        masked_pan:
+          type: string
+
+    Endpoint:
+      type: object
+      additionalProperties: false
+      required:
+        - type
+        - data
+      properties:
+        type:
+          $ref: ../../external/endpoint_type.yaml#/components/schemas/EndpointType
+        data:
+          type: object
+          additionalProperties: true
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+
+    Customer:
+      type: object
+      additionalProperties: false
+      properties:
+        id:
+          type: string
+        first_name:
+          type: string
+        middle_name:
+          type: string
+        last_name:
+          type: string
+        ip:
+          type: string
+        zip:
+          type: string
+        country:
+          type: string
+        state:
+          type: string
+        city:
+          type: string
+        address:
+          type: string
+
+    CurrencyPair:
+      type: object
+      additionalProperties: false
+      required:
+        - base
+        - quote
+      properties:
+        base:
+          type: string
+        quote:
+          type: string
+
+    FxIntent:
+      type: object
+      additionalProperties: false
+      required:
+        - side
+      properties:
+        pair:
+          $ref: ./payment.yaml#/components/schemas/CurrencyPair
+        side:
+          $ref: ../../external/fx_side.yaml#/components/schemas/FxSide
+        firm:
+          type: boolean
+        ttl_ms:
+          type: integer
+          format: int64
+        preferred_provider:
+          type: string
+        max_age_ms:
+          type: integer
+          format: int32
+
+    PaymentIntent:
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - source
+        - destination
+        - amount
+      properties:
+        kind:
+          $ref: ../../external/payment_kind.yaml#/components/schemas/PaymentKind
+        source:
+          $ref: ./payment.yaml#/components/schemas/Endpoint
+        destination:
+          $ref: ./payment.yaml#/components/schemas/Endpoint
+        amount:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        fx:
+          $ref: ./payment.yaml#/components/schemas/FxIntent
+        settlement_mode:
+          $ref: ../../external/settlement_mode.yaml#/components/schemas/SettlementMode
+        settlement_currency:
+          type: string
+        attributes:
+          type: object
+          additionalProperties:
+            type: string
+        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
+      properties:
+        ledgerAccountRef:
+          type: string
+        amount:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        lineType:
+          type: string
+        side:
+          type: string
+        meta:
+          type: object
+          additionalProperties:
+            type: string
+
+    FxQuote:
+      type: object
+      additionalProperties: false
+      properties:
+        quoteRef:
+          type: string
+        baseCurrency:
+          type: string
+        quoteCurrency:
+          type: string
+        side:
+          type: string
+        price:
+          type: string
+        baseAmount:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        quoteAmount:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        expiresAtUnixMs:
+          type: integer
+          format: int64
+        pricedAtUnixMs:
+          type: integer
+          format: int64
+        provider:
+          type: string
+        rateRef:
+          type: string
+        firm:
+          type: boolean
+
+    PaymentQuoteAggregate:
+      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
+
+    Payment:
+      type: object
+      additionalProperties: false
+      properties:
+        paymentRef:
+          type: string
+        idempotencyKey:
+          type: string
+        state:
+          $ref: ../../external/payment_state.yaml#/components/schemas/PaymentState
+        failureCode:
+          type: string
+        failureReason:
+          type: string
+        lastQuote:
+          $ref: ./payment.yaml#/components/schemas/PaymentQuote
+        createdAt:
+          type: string
+          format: date-time
+        meta:
+          type: object
+          additionalProperties:
+            type: string

interface/models/payment_method/payment_method.yaml

@@ -0,0 +1,22 @@
+components:
+  schemas:
+    PaymentMethod:
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - recipientRef
+            - type
+            - isMain
+          properties:
+            recipientRef:
+              $ref: ../objectid.yaml#/components/schemas/ObjectId
+            type:
+              $ref: ../../external/payment_method_type.yaml#/components/schemas/PaymentMethodType
+            data:
+              type: object
+              additionalProperties: true
+            isMain:
+              type: boolean

interface/models/permission_bound.yaml

@@ -0,0 +1,18 @@
+components:
+  schemas:
+    PermissionBound:
+      allOf:
+        - $ref: ./storable.yaml#/components/schemas/Storable
+        - type: object
+          additionalProperties: false
+          required:
+            - organizationRef
+            - permissionRef
+            - isArchived
+          properties:
+            organizationRef:
+              $ref: ./objectid.yaml#/components/schemas/ObjectId
+            permissionRef:
+              $ref: ./objectid.yaml#/components/schemas/ObjectId
+            isArchived:
+              type: boolean

interface/models/recipient/recipient.yaml

@@ -0,0 +1,30 @@
+components:
+  schemas:
+    Recipient:
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - email
+            - status
+            - type
+          properties:
+            email:
+              type: string
+              format: email
+            avatarUrl:
+              type: string
+              nullable: true
+            status:
+              type: string
+              enum:
+                - ready
+                - registered
+                - notRegistered
+            type:
+              type: string
+              enum:
+                - internal
+                - external

interface/models/storable.yaml

@@ -0,0 +1,18 @@
+components:
+  schemas:
+    Storable:
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - createdAt
+        - updatedAt
+      properties:
+        id:
+          $ref: ./objectid.yaml#/components/schemas/ObjectId
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time

interface/sw.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Sendico API Docs (Swagger UI)</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+  <style>
+    html, body { margin: 0; height: 100%; }
+    #swagger-ui { height: 100%; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    window.ui = SwaggerUIBundle({
+      url: './api.yaml',
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      presets: [SwaggerUIBundle.presets.apis],
+      layout: 'BaseLayout'
+    });
+  </script>
+</body>
+</html>