Bootstrap copied BFF and local accounts with public Sendico contracts (#34)

backend/contracts/sendico/models/account/account.yaml

@@ -0,0 +1,15 @@
+components:
+  schemas:
+    AccountData:
+      description: Extended account payload including visibility-specific metadata.
+      allOf:
+        - $ref: ./account_public.yaml#/components/schemas/AccountPublic
+        - type: object
+          description: Account attributes that are not part of the public profile.
+          additionalProperties: false
+          required:
+            - isAnonymous
+          properties:
+            isAnonymous:
+              description: Indicates whether the account is marked as anonymous.
+              type: boolean

backend/contracts/sendico/models/account/account_public.yaml

@@ -0,0 +1,33 @@
+components:
+  schemas:
+    AccountPublic:
+      description: Public account profile data exposed in API responses.
+      allOf:
+        - $ref: ../storable.yaml#/components/schemas/Storable
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          description: Account-specific public attributes.
+          additionalProperties: false
+          required:
+            - login
+            - locale
+            - lastName
+            - isArchived
+          properties:
+            login:
+              description: Account login identifier represented as an email address.
+              type: string
+              format: email
+            locale:
+              description: Preferred locale used for account-facing content.
+              type: string
+            lastName:
+              description: Account holder last name.
+              type: string
+            avatarUrl:
+              description: Optional URL of the account avatar image.
+              type: string
+              nullable: true
+            isArchived:
+              description: Indicates whether the account is archived and inactive.
+              type: boolean

backend/contracts/sendico/models/auth/client_refresh_token.yaml

@@ -0,0 +1,15 @@
+components:
+  schemas:
+    ClientRefreshToken:
+      description: Refresh token bound to a specific client and device session.
+      allOf:
+        - $ref: ./session_identifier.yaml#/components/schemas/SessionIdentifier
+        - type: object
+          description: Refresh-token payload associated with the session identifier.
+          additionalProperties: false
+          required:
+            - token
+          properties:
+            token:
+              description: Long-lived token used to obtain a new access token.
+              type: string

backend/contracts/sendico/models/auth/login_data.yaml

@@ -0,0 +1,21 @@
+components:
+  schemas:
+    LoginData:
+      description: Credentials and optional locale used during user sign-in.
+      type: object
+      additionalProperties: false
+      required:
+        - login
+        - password
+      properties:
+        login:
+          description: User login identifier, represented as an email address.
+          type: string
+          format: email
+        password:
+          description: User password submitted for authentication.
+          type: string
+          format: password
+        locale:
+          description: Optional locale preference provided at login time.
+          type: string

backend/contracts/sendico/models/auth/session_identifier.yaml

@@ -0,0 +1,16 @@
+components:
+  schemas:
+    SessionIdentifier:
+      description: Identifies an authentication session by client and device.
+      type: object
+      additionalProperties: false
+      required:
+        - clientId
+        - deviceId
+      properties:
+        clientId:
+          description: Client application identifier associated with the session.
+          type: string
+        deviceId:
+          description: Device/server identifier associated with the client session.
+          type: string

backend/contracts/sendico/models/auth/token_data.yaml

@@ -0,0 +1,17 @@
+components:
+  schemas:
+    TokenData:
+      description: Authentication token payload with expiration metadata.
+      type: object
+      additionalProperties: false
+      required:
+        - token
+        - expiration
+      properties:
+        token:
+          description: Issued authentication token value.
+          type: string
+        expiration:
+          description: RFC 3339 timestamp when the token expires.
+          type: string
+          format: date-time

backend/contracts/sendico/models/callback/callback.yaml

@@ -0,0 +1,152 @@
+components:
+  schemas:
+    CallbackBackoff:
+      description: Backoff window used between callback retry attempts.
+      type: object
+      additionalProperties: false
+      required:
+        - minDelayMs
+        - maxDelayMs
+      properties:
+        minDelayMs:
+          description: Minimum delay in milliseconds before scheduling a retry attempt.
+          type: integer
+          minimum: 1
+        maxDelayMs:
+          description: Maximum delay in milliseconds before scheduling a retry attempt.
+          type: integer
+          minimum: 1
+
+    CallbackRetryPolicy:
+      description: Retry and delivery behavior for callback requests.
+      type: object
+      additionalProperties: false
+      required:
+        - backoff
+        - signingMode
+        - maxAttempts
+        - requestTimeoutMs
+      properties:
+        backoff:
+          description: Delay boundaries used to compute retry backoff between attempts.
+          $ref: '#/components/schemas/CallbackBackoff'
+        signingMode:
+          description: Request-signing strategy applied when dispatching callback payloads. `jws_eddsa_ed25519` sends the raw JSON body unchanged and includes a detached compact JWS in `X-Callback-JWS`.
+          type: string
+          enum:
+            - none
+            - hmac_sha256
+            - jws_eddsa_ed25519
+        headers:
+          description: Additional HTTP headers included with every callback request.
+          type: object
+          additionalProperties:
+            type: string
+        maxAttempts:
+          description: Maximum number of delivery attempts before marking dispatch as failed.
+          type: integer
+          minimum: 1
+        requestTimeoutMs:
+          description: Per-request timeout in milliseconds for callback HTTP calls.
+          type: integer
+          minimum: 1
+
+    CallbackSigningJWK:
+      description: Ed25519 verification key published for callbacks that use detached JWS signing.
+      type: object
+      additionalProperties: false
+      required:
+        - kty
+        - crv
+        - alg
+        - use
+        - kid
+        - x
+      properties:
+        kty:
+          type: string
+          enum: [OKP]
+        crv:
+          type: string
+          enum: [Ed25519]
+        alg:
+          type: string
+          enum: [EdDSA]
+        use:
+          type: string
+          enum: [sig]
+        kid:
+          description: Opaque key identifier mirrored into the protected JWS header and `X-Callback-Key-Id`.
+          type: string
+        x:
+          description: Base64url-encoded Ed25519 public key bytes used to verify the detached JWS signature.
+          type: string
+
+    CallbackSigningKey:
+      description: Verification material exposed for callbacks that use `jws_eddsa_ed25519`. Receivers verify `X-Callback-JWS` against the raw request body with the matching `kid`. Retiring keys remain available for 24 hours after rotation so queued deliveries remain verifiable.
+      type: object
+      additionalProperties: false
+      required:
+        - status
+        - jwk
+      properties:
+        status:
+          description: Indicates whether the key is the current signing key or a still-valid retiring key from a recent rotation.
+          type: string
+          enum:
+            - active
+            - retiring
+        expiresAt:
+          description: Timestamp after which a retiring key is no longer returned in callback reads.
+          type: string
+          format: date-time
+          nullable: true
+        jwk:
+          $ref: '#/components/schemas/CallbackSigningJWK'
+
+    CallbackContent:
+      description: Callback endpoint configuration and delivery parameters.
+      allOf:
+        - type: object
+          additionalProperties: false
+          required:
+            - status
+            - url
+            - eventTypes
+            - retryPolicy
+          properties:
+            status:
+              description: Operational state controlling whether callback delivery is enabled.
+              type: string
+              enum:
+                - active
+                - disabled
+            url:
+              description: Absolute HTTPS endpoint URL that receives callback events.
+              type: string
+              format: uri
+            eventTypes:
+              description: Event type names that trigger callback delivery to this endpoint.
+              type: array
+              items:
+                type: string
+            retryPolicy:
+              description: Retry and timeout parameters used when dispatching callback events.
+              $ref: '#/components/schemas/CallbackRetryPolicy'
+
+
+    Callback:
+      description: Stored callback configuration bound to an organization permission scope.
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - $ref: '#/components/schemas/CallbackContent'
+        - type: object
+          additionalProperties: false
+          properties:
+            signingKeys:
+              description: Read-only verification keys for callbacks that use detached JWS signing. The callback JSON body is not wrapped; receivers verify `X-Callback-JWS` against the raw body bytes and use the key matching the protected-header `kid`.
+              type: array
+              readOnly: true
+              items:
+                $ref: '#/components/schemas/CallbackSigningKey'

backend/contracts/sendico/models/common/describable.yaml

@@ -0,0 +1,16 @@
+components:
+  schemas:
+    Describable:
+      description: Common naming metadata for user-defined entities.
+      type: object
+      additionalProperties: false
+      required:
+        - name
+      properties:
+        name:
+          description: Human-readable name of the entity.
+          type: string
+        description:
+          description: Optional free-form description of the entity.
+          type: string
+          nullable: true

backend/contracts/sendico/models/common/money.yaml

@@ -0,0 +1,18 @@
+components:
+  schemas:
+    Money:
+      description: Monetary value represented by a decimal amount and ISO currency code.
+      type: object
+      additionalProperties: false
+      required:
+        - amount
+        - currency
+      properties:
+        amount:
+          type: string
+          description: Decimal string amount.
+          example: '125.50'
+        currency:
+          description: ISO 4217 currency code for the provided amount.
+          type: string
+          example: USD

backend/contracts/sendico/models/common/pagination.yaml

@@ -0,0 +1,10 @@
+components:
+  schemas:
+    CursorPageResponse:
+      description: Cursor-based pagination metadata returned with list responses.
+      type: object
+      additionalProperties: false
+      properties:
+        next_cursor:
+          description: Opaque cursor to request the next page; omitted when no more items exist.
+          type: string

backend/contracts/sendico/models/ledger/balance.yaml

@@ -0,0 +1,53 @@
+components:
+  schemas:
+    LedgerAccountBalance:
+      description: Canonical ledger account balance. Current and historical modes have distinct field-presence semantics.
+      oneOf:
+        - $ref: ./balance.yaml#/components/schemas/CurrentLedgerAccountBalance
+        - $ref: ./balance.yaml#/components/schemas/HistoricalLedgerAccountBalance
+
+    CurrentLedgerAccountBalance:
+      description: Current materialized ledger account balance.
+      type: object
+      additionalProperties: false
+      required:
+        - ledgerAccountRef
+        - balance
+        - version
+        - lastUpdated
+      properties:
+        ledgerAccountRef:
+          description: Ledger account reference.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId
+        balance:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        version:
+          description: Materialized account-balance version.
+          type: integer
+          format: int64
+        lastUpdated:
+          description: Materialized balance update timestamp.
+          type: string
+          format: date-time
+
+    HistoricalLedgerAccountBalance:
+      description: |
+        Event-time accounting balance reconstructed from posted statement-entry deltas
+        where `eventTime <= asOf`. This is not a materialized historical snapshot.
+      type: object
+      additionalProperties: false
+      required:
+        - ledgerAccountRef
+        - balance
+        - asOf
+      properties:
+        ledgerAccountRef:
+          description: Ledger account reference.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId
+        balance:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        asOf:
+          description: Canonical UTC RFC3339 event-time cutoff used for reconstruction.
+          type: string
+          format: date-time
+          example: '2026-04-23T12:30:00Z'

backend/contracts/sendico/models/ledger/operation.yaml

@@ -0,0 +1,124 @@
+components:
+  schemas:
+    LedgerStatementVisibility:
+      description: Visibility of the account-history projection returned for the requested ledger account.
+      type: string
+      enum:
+        - full
+        - partial
+
+    LedgerEntryType:
+      description: Lowercase ledger entry type string from the BFF response.
+      type: string
+      example: transfer
+
+    LedgerLineType:
+      description: Lowercase posting-line type string from the BFF response.
+      type: string
+      example: main
+
+    LedgerAccountOperationSummary:
+      description: |
+        Account-history summary projection for a ledger statement entry.
+        `accountAmount` is the exact decimal sum of visible posting-line amounts whose `ledgerAccountRef`
+        equals the requested statement account. Positive means net credit, negative means net debit,
+        zero means net neutral, and the currency matches the requested ledger account currency.
+      type: object
+      additionalProperties: false
+      required:
+        - entryRef
+        - entryType
+        - accountAmount
+        - eventTime
+        - version
+        - visibility
+      properties:
+        entryRef:
+          description: Statement entry reference.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId
+        entryType:
+          $ref: ./operation.yaml#/components/schemas/LedgerEntryType
+        accountAmount:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        description:
+          description: Human-readable entry description when present.
+          type: string
+        eventTime:
+          description: Event timestamp carried by the canonical statement entry.
+          type: string
+          format: date-time
+        version:
+          description: Immutable ledger history version used for deterministic ordering.
+          type: integer
+          format: int64
+        visibility:
+          $ref: ./operation.yaml#/components/schemas/LedgerStatementVisibility
+
+    LedgerAccountOperationLine:
+      description: Visible posting line included in the account-history projection.
+      type: object
+      additionalProperties: false
+      required:
+        - ledgerAccountRef
+        - money
+        - lineType
+      properties:
+        ledgerAccountRef:
+          description: Ledger account reference for the visible posting line.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId
+        money:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        lineType:
+          $ref: ./operation.yaml#/components/schemas/LedgerLineType
+        organizationRef:
+          description: Owning organization reference when visible to the caller.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId
+
+    LedgerAccountOperation:
+      description: |
+        Detailed account-history projection for a statement entry.
+        This payload is scoped to the requested ledger account and does not expose general journal-entry data outside that visibility model.
+      type: object
+      additionalProperties: false
+      required:
+        - entryRef
+        - entryType
+        - accountAmount
+        - eventTime
+        - version
+        - visibility
+        - lines
+      properties:
+        entryRef:
+          description: Statement entry reference.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId
+        entryType:
+          $ref: ./operation.yaml#/components/schemas/LedgerEntryType
+        accountAmount:
+          $ref: ../common/money.yaml#/components/schemas/Money
+        description:
+          description: Human-readable entry description when present.
+          type: string
+        eventTime:
+          description: Event timestamp carried by the canonical statement entry.
+          type: string
+          format: date-time
+        version:
+          description: Immutable ledger history version used for deterministic ordering.
+          type: integer
+          format: int64
+        visibility:
+          $ref: ./operation.yaml#/components/schemas/LedgerStatementVisibility
+        lines:
+          description: Visible posting lines included in the account-history projection.
+          type: array
+          items:
+            $ref: ./operation.yaml#/components/schemas/LedgerAccountOperationLine
+        metadata:
+          description: Entry metadata when visible to the caller.
+          type: object
+          additionalProperties:
+            type: string
+        organizationRef:
+          description: Entry organization reference when visible to the caller.
+          $ref: ../objectid.yaml#/components/schemas/ObjectId

backend/contracts/sendico/models/objectid.yaml

@@ -0,0 +1,9 @@
+components:
+  schemas:
+    ObjectId:
+      description: Object identifier represented as a 24-character hexadecimal string.
+      type: string
+      format: objectid
+      pattern: '^[a-fA-F0-9]{24}$'
+      examples:
+        - 64f85f5f4c7dbf7cfb8f3f10

backend/contracts/sendico/models/organization/organization.yaml

@@ -0,0 +1,39 @@
+components:
+  schemas:
+    OrganizationBase:
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - timeZone
+          properties:
+            tenantRef:
+              description: Tenant identifier that owns the organization.
+              $ref: ../objectid.yaml#/components/schemas/ObjectId
+            timeZone:
+              type: string
+            logoUrl:
+              type: string
+              nullable: true
+            signupState:
+              description: Signup/provisioning lifecycle state for the organization.
+              type: string
+              enum:
+                - pending_signup_provisioning
+                - blocked_signup_provisioning
+                - active
+
+    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

backend/contracts/sendico/models/payment/fx_metadata.yaml

@@ -0,0 +1,78 @@
+components:
+  schemas:
+    FXCurrency:
+      description: Display-facing currency metadata sourced from the Treasury Currency Catalog startup snapshot cached by the BFF.
+      type: object
+      additionalProperties: false
+      required:
+        - code
+        - kind
+      properties:
+        code:
+          description: Treasury canonical asset code.
+          type: string
+        kind:
+          description: Compatibility asset kind projection. Use `assetKind` for the Treasury-owned exact asset kind.
+          type: string
+          enum:
+            - fiat
+            - crypto
+            - internal
+        assetKind:
+          description: Treasury-owned asset kind. Network-specific support, provider asset codes, token contracts, and provider rails are not represented here.
+          type: string
+          enum:
+            - fiat
+            - crypto_token
+            - crypto_native
+            - internal_platform
+        decimals:
+          description: Display-facing compatibility field backed by Treasury `displayScale`. Backend services and clients must not use it as accounting, quote, or payout execution precision authority.
+          type: integer
+          format: int32
+          minimum: 0
+        scale:
+          description: Display-facing compatibility field backed by Treasury `displayScale`; always equal to `decimals` in this response.
+          type: integer
+          format: int32
+          minimum: 0
+        displayScale:
+          description: Treasury UI/display precision.
+          type: integer
+          format: int32
+          minimum: 0
+        accountingScaleCandidate:
+          description: Informational Treasury accounting scale candidate. This is not provider execution precision, not FX rate precision, and not guaranteed executable payout precision or provider support.
+          type: integer
+          format: int32
+          minimum: 0
+        rounding:
+          description: Preferred rounding mode for the currency, when supplied by the oracle.
+          type: string
+          enum:
+            - round_half_even
+            - round_half_up
+            - round_down
+
+    FXDirection:
+      description: Direction-level FX availability for an organization.
+      type: object
+      additionalProperties: false
+      required:
+        - fromCurrency
+        - toCurrency
+        - pair
+        - side
+      properties:
+        fromCurrency:
+          description: Source currency of the directed conversion.
+          type: string
+        toCurrency:
+          description: Target currency of the directed conversion.
+          type: string
+        pair:
+          description: Oracle canonical base/quote pair from which the direction was derived. This pair does not follow display from/to order.
+          $ref: ./payment.yaml#/components/schemas/CurrencyPair
+        side:
+          description: FX side interpreted against the canonical pair. `sell_base_buy_quote` means the customer sells base and receives quote; `buy_base_sell_quote` means the customer buys base and pays quote.
+          $ref: ../../external/fx_side.yaml#/components/schemas/FxSide

backend/contracts/sendico/models/payment/payment.yaml

@@ -0,0 +1,879 @@
+components:
+  schemas:
+    Asset:
+      description: Blockchain asset identifier used for on-chain transfers.
+      type: object
+      additionalProperties: false
+      properties:
+        chain:
+          description: Chain/network where the asset exists.
+          $ref: ../../external/chain_network.yaml#/components/schemas/ChainNetwork
+        token_symbol:
+          description: Symbol of the token on the selected chain.
+          type: string
+        contract_address:
+          description: Smart-contract address for tokenized assets.
+          type: string
+
+    ExternalChainAsset:
+      description: Blockchain asset identifier used for external-chain endpoints. `token_symbol` is required by current quote/initiate logic; `chain` remains optional.
+      required:
+        - token_symbol
+      allOf:
+        - $ref: ./payment.yaml#/components/schemas/Asset
+
+    LedgerEndpoint:
+      description: |
+        Internal ledger-based endpoint used as payment source or destination.
+        Current request handling accepts exactly one of `account_ref` or `account_code`.
+        `ledger_account_ref` is accepted as a legacy alias for `account_ref`.
+      type: object
+      additionalProperties: false
+      properties:
+        account_ref:
+          description: Reference of the primary ledger account.
+          type: string
+        ledger_account_ref:
+          description: Legacy alias for `account_ref`.
+          deprecated: true
+          type: string
+        account_code:
+          description: Account code of the primary ledger account.
+          type: string
+        contra_account_ref:
+          description: Optional contra ledger account reference for balancing entries.
+          type: string
+        contra_account_code:
+          description: Optional contra ledger account code for balancing entries.
+          type: string
+
+    PaymentMethodEndpoint:
+      description: Stored payment method selector. Sent with endpoint type `paymentMethod` and `data.ref`.
+      type: object
+      additionalProperties: false
+      required:
+        - ref
+      properties:
+        ref:
+          description: Stored payment method reference.
+          type: string
+
+    AccountEndpoint:
+      description: Account-owned main payment method selector. Sent with endpoint type `account` and `data.ref`.
+      type: object
+      additionalProperties: false
+      required:
+        - ref
+      properties:
+        ref:
+          description: Account reference whose main payment method should be used.
+          type: string
+
+    RecipientEndpoint:
+      description: Recipient-owned main payment method selector. Sent with endpoint type `recipient` and `data.ref`.
+      type: object
+      additionalProperties: false
+      required:
+        - ref
+      properties:
+        ref:
+          description: Recipient reference whose main payment method should be used.
+          type: string
+
+    ManagedWalletEndpoint:
+      description: Endpoint referencing a managed wallet within the platform.
+      type: object
+      additionalProperties: false
+      required:
+        - ref
+      properties:
+        ref:
+          description: Reference of the managed wallet.
+          type: string
+        asset:
+          description: Asset details for the managed wallet transfer.
+          $ref: ./payment.yaml#/components/schemas/Asset
+
+    ExternalChainEndpoint:
+      description: Endpoint representing an external blockchain address.
+      type: object
+      additionalProperties: false
+      required:
+        - asset
+        - address
+      properties:
+        asset:
+          description: Asset to be transferred to or from the external address.
+          $ref: ./payment.yaml#/components/schemas/ExternalChainAsset
+        address:
+          description: Target blockchain address.
+          type: string
+        memo:
+          description: Optional destination memo or tag required by some chains.
+          type: string
+
+    CardEndpoint:
+      description: |
+        Raw card payout endpoint.
+        Current quotation logic only requires `pan`; `exp_month` and `exp_year` are accepted but optional while pricing.
+        Raw-card payment execution requires `pan`, `exp_month`, and `exp_year`.
+        That execution rule also applies when a payment is later created from `quoteRef`, because the quoted endpoint snapshot is reused.
+      type: object
+      additionalProperties: false
+      required:
+        - pan
+      properties:
+        pan:
+          description: Primary account number of the card. Required for both quotation and raw-card payment execution.
+          type: string
+        firstName:
+          description: Optional cardholder first name hint. Current quote and execution logic do not require it.
+          type: string
+        lastName:
+          description: Optional cardholder last name hint. Current quote and execution logic do not require it.
+          type: string
+        exp_month:
+          description: Card expiration month. Optional for quotation, but required for raw-card payment execution, including payments executed later from `quoteRef`.
+          type: integer
+          format: int32
+          minimum: 0
+        exp_year:
+          description: Card expiration year. Optional for quotation, but required for raw-card payment execution, including payments executed later from `quoteRef`.
+          type: integer
+          format: int32
+          minimum: 0
+        country:
+          description: Optional card country hint. Current quote and execution logic do not require it.
+          type: string
+
+    CardTokenEndpoint:
+      description: |
+        Tokenized card payout endpoint used instead of raw PAN details.
+        Current quotation and payment-execution logic require only `token`.
+        `masked_pan` remains optional and is mainly used for display, auditing, and provider-specific context.
+      type: object
+      additionalProperties: false
+      required:
+        - token
+      properties:
+        token:
+          description: Provider-issued card token. Required for both quotation and tokenized-card payment execution.
+          type: string
+        masked_pan:
+          description: Optional masked PAN representation for display and auditing. Current quote and execution logic do not require it.
+          type: string
+
+    BankAccountEndpoint:
+      description: |
+        Russian domestic bank-account payout endpoint.
+        The recipient name is grouped under `recipient` with `first_name`
+        and `last_name`.
+      type: object
+      additionalProperties: false
+      required:
+        - recipient
+        - kpp
+        - bankName
+        - bik
+        - accountNumber
+        - correspondentAccount
+      properties:
+        recipient:
+          description: Legal recipient name for the bank-account payout.
+          type: object
+          additionalProperties: false
+          required:
+            - first_name
+            - last_name
+          properties:
+            first_name:
+              description: Recipient first name.
+              type: string
+            last_name:
+              description: Recipient last name.
+              type: string
+        inn:
+          description: Optional Russian INN tax identifier for the recipient. If present, it must be valid. Bank payout execution uses this value before falling back to the customer or saved owner tax identifier.
+          type: string
+        kpp:
+          description: Russian KPP tax registration reason code.
+          type: string
+        bankName:
+          description: Recipient bank name.
+          type: string
+        bik:
+          description: 9-digit Russian bank identification code.
+          type: string
+        accountNumber:
+          description: 20-digit Russian bank account number.
+          type: string
+        correspondentAccount:
+          description: 20-digit correspondent account number.
+          type: string
+      example:
+        recipient:
+          first_name: Ivan
+          last_name: Ivanov
+        inn: '7707083893'
+        kpp: '770701001'
+        bankName: Test Bank
+        bik: '044525225'
+        accountNumber: '40702810900000000001'
+        correspondentAccount: '30101810400000000225'
+
+    IBANEndpoint:
+      description: International bank-account payout endpoint.
+      type: object
+      additionalProperties: false
+      required:
+        - iban
+        - accountHolder
+      properties:
+        iban:
+          type: string
+        accountHolder:
+          type: string
+        bic:
+          type: string
+        bankName:
+          type: string
+
+    Endpoint:
+      description: |
+        Polymorphic payment endpoint definition. Every endpoint is expressed with the same
+        `type` plus `data` shape. Stored references are typed endpoints too: a stored payment
+        method uses `type: paymentMethod`, a recipient main method uses `type: recipient`, and
+        an account main method uses `type: account`, each with a `ref` inside `data`.
+        Flat top-level selector fields (`paymentMethodRef`, `recipientRef`, `accountRef`) are
+        not accepted; the request handler rejects them.
+      type: object
+      additionalProperties: false
+      required:
+        - type
+        - data
+      properties:
+        type:
+          description: Endpoint type determining the shape of the `data` field.
+          $ref: ../../external/endpoint_type.yaml#/components/schemas/EndpointType
+        data:
+          description: Endpoint payload corresponding to the selected endpoint type. For raw `card` payloads, `pan` is always required and expiry becomes required once the intent is executed.
+          anyOf:
+            - $ref: ./payment.yaml#/components/schemas/PaymentMethodEndpoint
+            - $ref: ./payment.yaml#/components/schemas/AccountEndpoint
+            - $ref: ./payment.yaml#/components/schemas/RecipientEndpoint
+            - $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/BankAccountEndpoint
+            - $ref: ./payment.yaml#/components/schemas/IBANEndpoint
+        metadata:
+          description: Optional key-value metadata attached to the endpoint.
+          type: object
+          additionalProperties:
+            type: string
+
+    PaymentResponseEndpoint:
+      description: |
+        Endpoint snapshot attached to a persisted payment. Uses the same `type` plus `data`
+        shape as request endpoints. Stored-reference snapshots are emitted as typed endpoints
+        (`paymentMethod`, `account`, or `recipient`) with a `ref` inside `data`.
+      type: object
+      additionalProperties: false
+      required:
+        - type
+        - data
+      properties:
+        type:
+          description: Endpoint type for the endpoint snapshot.
+          $ref: ../../external/endpoint_type.yaml#/components/schemas/EndpointType
+        data:
+          description: Endpoint payload snapshot; shape depends on `type`.
+          anyOf:
+            - $ref: ./payment.yaml#/components/schemas/PaymentMethodEndpoint
+            - $ref: ./payment.yaml#/components/schemas/AccountEndpoint
+            - $ref: ./payment.yaml#/components/schemas/RecipientEndpoint
+            - $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/BankAccountEndpoint
+            - $ref: ./payment.yaml#/components/schemas/IBANEndpoint
+
+    Customer:
+      description: Customer identity and address attributes for compliance and routing.
+      type: object
+      additionalProperties: false
+      properties:
+        id:
+          description: External or internal customer identifier.
+          type: string
+        first_name:
+          description: Customer first name.
+          type: string
+        middle_name:
+          description: Customer middle name.
+          type: string
+        last_name:
+          description: Customer last name.
+          type: string
+        ip:
+          description: Source IP address associated with the payment request.
+          type: string
+        zip:
+          description: Postal or ZIP code.
+          type: string
+        country:
+          description: Country code of customer residence or billing address.
+          type: string
+        state:
+          description: State or region.
+          type: string
+        city:
+          description: City name.
+          type: string
+        address:
+          description: Street address line.
+          type: string
+        tax_identifier:
+          description: Customer tax identifier. Russian bank-account payouts interpret this value as INN.
+          type: string
+
+    CurrencyPair:
+      description: Foreign-exchange currency pair.
+      type: object
+      additionalProperties: false
+      required:
+        - base
+        - quote
+      properties:
+        base:
+          description: Base currency code.
+          type: string
+        quote:
+          description: Quote currency code.
+          type: string
+
+    FxIntent:
+      description: FX execution preferences associated with a payment.
+      type: object
+      additionalProperties: false
+      required:
+        - pair
+        - side
+      properties:
+        pair:
+          description: Currency pair for FX conversion.
+          $ref: ./payment.yaml#/components/schemas/CurrencyPair
+        side:
+          description: Side of the FX trade intent.
+          $ref: ../../external/fx_side.yaml#/components/schemas/FxSide
+        firm:
+          description: Whether a firm quote is required.
+          type: boolean
+        ttl_ms:
+          description: Desired quote time-to-live in milliseconds.
+          type: integer
+          format: int64
+        preferred_provider:
+          description: Preferred FX liquidity provider identifier.
+          type: string
+        max_age_ms:
+          description: Maximum accepted quote age in milliseconds.
+          type: integer
+          format: int32
+
+    PaymentIntent:
+      description: Requested payment execution parameters before processing. For raw `card` destinations, quotation accepts missing expiry but payment execution requires `exp_month` and `exp_year`.
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - source
+        - destination
+        - amount
+      properties:
+        kind:
+          description: High-level payment kind that drives orchestration behavior.
+          $ref: ../../external/payment_kind.yaml#/components/schemas/PaymentKind
+        source:
+          description: Source endpoint from which funds are debited.
+          $ref: ./payment.yaml#/components/schemas/Endpoint
+        destination:
+          description: Destination endpoint to which funds are credited. If `type=card`, `exp_month` and `exp_year` are optional while quoting but required when the payment is executed.
+          $ref: ./payment.yaml#/components/schemas/Endpoint
+        amount:
+          description: Requested payment amount.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        fx:
+          description: Optional FX preferences when conversion is needed.
+          $ref: ./payment.yaml#/components/schemas/FxIntent
+        settlement_mode:
+          description: Settlement strategy for the transfer.
+          $ref: ../../external/settlement_mode.yaml#/components/schemas/SettlementMode
+        fee_treatment:
+          description: How fees should be applied to source/destination amounts.
+          type: string
+          enum:
+            - unspecified
+            - add_to_source
+            - deduct_from_destination
+        attributes:
+          description: Additional key-value attributes used by downstream processors.
+          type: object
+          additionalProperties:
+            type: string
+        comment:
+          description: Optional free-form comment attached to the payment intent.
+          type: string
+        customer:
+          description: Optional customer information attached to the payment intent.
+          $ref: ./payment.yaml#/components/schemas/Customer
+
+    FeeLine:
+      description: Single fee component included in a payment quote.
+      type: object
+      additionalProperties: false
+      properties:
+        ledgerAccountRef:
+          description: Ledger account reference receiving or charging this fee.
+          type: string
+        amount:
+          description: Monetary amount of the fee line.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        lineType:
+          description: Fee line classification.
+          type: string
+        side:
+          description: Indicates whether the fee applies on debit or credit side.
+          type: string
+        meta:
+          description: Optional metadata for fee calculation traceability.
+          type: object
+          additionalProperties:
+            type: string
+
+    QuoteFees:
+      description: Collection of fee lines for a quoted payment.
+      type: object
+      additionalProperties: false
+      properties:
+        lines:
+          description: List of individual quoted fee lines.
+          type: array
+          items:
+            $ref: ./payment.yaml#/components/schemas/FeeLine
+
+    QuoteAmounts:
+      description: Amount breakdown returned with a payment quote.
+      type: object
+      additionalProperties: false
+      properties:
+        sourcePrincipal:
+          description: Principal amount debited from the source before fees.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        sourceDebitTotal:
+          description: Total amount debited from the source including adjustments.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        destinationSettlement:
+          description: Net amount expected to settle at the destination.
+          $ref: ../common/money.yaml#/components/schemas/Money
+
+    FxQuote:
+      description: FX quote details used to price converted payment amounts.
+      type: object
+      additionalProperties: false
+      properties:
+        quoteRef:
+          description: Identifier of the FX quote.
+          type: string
+        baseCurrency:
+          description: Base currency of the quote pair.
+          type: string
+        quoteCurrency:
+          description: Quote currency of the quote pair.
+          type: string
+        side:
+          description: FX side used for pricing.
+          type: string
+        price:
+          description: Quoted FX price as a decimal string.
+          type: string
+        baseAmount:
+          description: Base currency amount covered by this quote.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        quoteAmount:
+          description: Quote currency amount corresponding to the base amount.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        expiresAtUnixMs:
+          description: Quote expiration timestamp in Unix milliseconds.
+          type: integer
+          format: int64
+        pricedAtUnixMs:
+          description: Quote pricing timestamp in Unix milliseconds.
+          type: integer
+          format: int64
+        provider:
+          description: Provider that supplied the FX quote.
+          type: string
+        rateRef:
+          description: Provider-specific rate reference identifier.
+          type: string
+        firm:
+          description: Indicates whether the FX quote is firm.
+          type: boolean
+
+    FxRateCalculation:
+      description: Exchange-rate calculation used by an FX quote.
+      type: object
+      additionalProperties: false
+      required:
+        - requestedPair
+        - requestedSide
+        - pathKind
+        - marketRate
+        - effectiveRate
+        - overrideScope
+        - specialRateApplied
+        - legs
+      properties:
+        requestedPair:
+          description: Requested currency pair for the FX quote.
+          $ref: ./payment.yaml#/components/schemas/CurrencyPair
+        requestedSide:
+          description: FX side interpreted against the requested pair.
+          $ref: ../../external/fx_side.yaml#/components/schemas/FxSide
+        pathKind:
+          description: Whether the applied rate was obtained from a direct pair or a cross-rate path.
+          type: string
+          enum:
+            - direct
+            - cross
+        marketRate:
+          description: Market-path rate before quote-level overrides, as a decimal string.
+          type: string
+        effectiveRate:
+          description: Final rate applied to the quote after leg-level or whole-rate overrides, as a decimal string.
+          type: string
+        overrideScope:
+          description: Location of the rate override. `none` means no special rate was applied.
+          type: string
+          enum:
+            - none
+            - leg
+            - total
+        specialRateApplied:
+          description: Derived convenience flag equal to `overrideScope != none`.
+          type: boolean
+        overrideRef:
+          description: Opaque support/audit reference for whole-rate overrides. Clients must not parse it.
+          type: string
+        asOfUnixMs:
+          description: Calculation/path decision timestamp in Unix milliseconds.
+          type: integer
+          format: int64
+        legs:
+          description: Resolved market path legs used to obtain the rate.
+          type: array
+          items:
+            $ref: ./payment.yaml#/components/schemas/FxRateCalculationLeg
+
+    FxRateCalculationLeg:
+      description: One market-path leg used in an FX quote rate calculation.
+      type: object
+      additionalProperties: false
+      required:
+        - pair
+        - sourcePair
+        - invertedFromSource
+        - marketRate
+        - effectiveRate
+        - overrideApplied
+      properties:
+        pair:
+          description: Oriented pair multiplied in path order.
+          $ref: ./payment.yaml#/components/schemas/CurrencyPair
+        sourcePair:
+          description: Stored/provider pair before orientation adjustments.
+          $ref: ./payment.yaml#/components/schemas/CurrencyPair
+        invertedFromSource:
+          description: Whether the source pair was inverted to produce this oriented leg.
+          type: boolean
+        marketRate:
+          description: Market executable rate for this leg, as a decimal string.
+          type: string
+        effectiveRate:
+          description: Effective rate for this leg after leg-level override, as a decimal string.
+          type: string
+        provider:
+          description: Rate provider identifier.
+          type: string
+        rateRef:
+          description: Opaque support/audit reference for the source rate. Clients must not parse it.
+          type: string
+        asOfUnixMs:
+          description: Source rate timestamp for this leg in Unix milliseconds.
+          type: integer
+          format: int64
+        overrideApplied:
+          description: Whether a leg-level override was applied to this leg.
+          type: boolean
+        overrideRef:
+          description: Opaque support/audit reference for the leg-level override. Clients must not parse it.
+          type: string
+
+    SpecialRateInfo:
+      description: Indicates whether quotation pricing policy applied a non-market FX rate to the quote.
+      type: object
+      additionalProperties: false
+      required:
+        - applied
+      properties:
+        applied:
+          description: Derived from `fxRateCalculation.overrideScope != none` when `fxRateCalculation` is present.
+          type: boolean
+
+    PaymentQuote:
+      description: Pricing result for a specific payment intent.
+      type: object
+      additionalProperties: false
+      required:
+        - executable
+        - state
+      properties:
+        quoteRef:
+          description: Unique identifier of the payment quote.
+          type: string
+        intentRef:
+          description: Reference to the payment intent used for quoting.
+          type: string
+        state:
+          description: Backend quotation execution state. `executable` means the quote can be submitted for execution. `blocked`, `indicative`, `expired`, and `unspecified` must not be executed as-is.
+          type: string
+          enum:
+            - unspecified
+            - indicative
+            - executable
+            - blocked
+            - expired
+        executable:
+          description: Explicit execution flag. `false` means the quote must not be sent to `/payments/by-quote` or `/payments/by-multiquote`.
+          type: boolean
+        blockReason:
+          description: Reason the quote is not executable when `state` is `blocked`. Omitted for executable, indicative, and expired quotes.
+          type: string
+          enum:
+            - route_unavailable
+            - limit_blocked
+            - risk_blocked
+            - insufficient_liquidity
+            - price_stale
+            - amount_too_small
+            - amount_too_large
+        amounts:
+          description: Amount breakdown for source and destination values.
+          $ref: ./payment.yaml#/components/schemas/QuoteAmounts
+        fees:
+          description: Fee breakdown included in the quote.
+          $ref: ./payment.yaml#/components/schemas/QuoteFees
+        fxQuote:
+          description: Associated FX quote when conversion is part of the payment.
+          $ref: ./payment.yaml#/components/schemas/FxQuote
+        fxRateCalculation:
+          description: Explanation of how the FX quote rate was obtained.
+          $ref: ./payment.yaml#/components/schemas/FxRateCalculation
+        specialRate:
+          description: Indicates whether quotation pricing policy applied a special FX rate while pricing this quote.
+          $ref: ./payment.yaml#/components/schemas/SpecialRateInfo
+
+    PaymentFailureCode:
+      description: |
+        Broad machine-readable category for a payment or operation that reports a failure
+        condition. This field is a public category, not the orchestration service's
+        canonical failure code. A card payout terminated after a definitive AML denial
+        uses `failure_restriction`; its canonical orchestration code is `card.aml_denied`.
+
+        The enumeration is closed and safe to use for failure handling after checking the
+        payment state. The state remains the lifecycle authority: `failure_restriction`
+        can accompany non-terminal `needs_attention` while manual review or additional
+        checks are pending. `failure_policy` is reserved and is not currently returned by
+        the API; policy blocks are reported as `failure_restriction`.
+
+        The published cause-to-category-to-reason list is at
+        https://app.sendico.io/docs/en/payment-failures/
+      type: string
+      enum:
+        - failure_unspecified
+        - failure_balance
+        - failure_ledger
+        - failure_fx
+        - failure_chain
+        - failure_fees
+        - failure_policy
+        - failure_validation
+        - failure_restriction
+      example: failure_restriction
+
+    PaymentFailureReason:
+      description: |
+        Stable lowercase machine-readable reason token intended for client handling. A
+        card payout terminated after a definitive AML denial uses `aml_denied`. Detailed
+        AML evidence, including the matched blacklist reason, and raw gateway, provider,
+        or RPC messages are not exposed here.
+
+        Unlike `failureCode`, this token set is open: compliance policy reason codes and
+        provider-derived reasons can add values without a contract change. Treat unknown
+        tokens as the category-level failure and keep a fallback message.
+
+        Default reasons per category: `insufficient_funds`; `ledger_operation_failed`,
+        `ledger_operation_cancelled`, `ledger_access_violation`,
+        `ledger_validation_failed`; `fee_fx_conversion_failed`; `fee_posting_failed`;
+        `gateway_execution_failed`, `gateway_execution_rejected`, `gateway_execution_cancelled`,
+        `gateway_transfer_failed`, `gateway_transfer_cancelled`, `card_payout_failed`,
+        `card_payout_cancelled`, `provider_declined`, `provider_limit`,
+        `provider_unavailable`, `provider_status_unknown`, `provider_unknown`,
+        `velocity_limit_exceeded`, `limits_rejected`; `validation_failed`,
+        `quote_precision_identity_missing`, `quote_precision_asset_identity_mismatch`,
+        `quote_precision_asset_scale_missing`, `quote_precision_amount_scale_exceeded`,
+        `card_validation_failed`, `card_scheme_unsupported`, `card_expired`,
+        `amount_below_minimum`, `amount_above_maximum`, `duplicate_transaction`,
+        `currency_unsupported`; `card_scheme_disabled`, `aml_denied`, `policy_blocked`,
+        `review_required`, `more_checks_required`, `risk_restricted`,
+        `operation_restricted`, `card_product_unsupported`; `assessment_failed`;
+        `failure_unspecified` for an unclassified cause.
+
+        Additional currently known override reasons are `do_not_honor`, `invalid_card`,
+        `invalid_card_number`, `invalid_cardholder_name`, `cardholder_name_mismatch`,
+        `card_details_invalid`, `card_expiry_required`, `invalid_amount`,
+        `provider_cancelled`, `disabled_card_scheme`,
+        `unsupported_gateway_card_scheme`, and `recipient_tax_identifier_required`.
+        Structured bank validation can add normalized reasons ending in `_required` or
+        `_invalid`; compliance policy reason codes are also an open set.
+
+        The published cause-to-category-to-reason list, including the additional
+        provider, submit-validation, and bank-validation tokens, is at
+        https://app.sendico.io/docs/en/payment-failures/
+      type: string
+      pattern: '^[a-z0-9_]+$'
+      example: aml_denied
+
+    PaymentOperation:
+      description: |
+        Execution step record captured during payment processing. For a card payout
+        terminated by AML screening, `failureCode` is `failure_restriction` and
+        `failureReason` is `aml_denied`.
+      type: object
+      additionalProperties: false
+      properties:
+        stepRef:
+          description: Identifier of the orchestration step.
+          type: string
+        code:
+          description: Operation code representing the executed action.
+          type: string
+        state:
+          description: Current state of the operation.
+          type: string
+        label:
+          description: Human-readable operation label.
+          type: string
+        comment:
+          description: Optional comment attached to the execution step.
+          type: string
+        money:
+          description: Planned and executed monetary snapshots for the operation.
+          $ref: ./payment.yaml#/components/schemas/PaymentOperationMoney
+        operationRef:
+          description: External operation reference identifier reported by the gateway.
+          type: string
+        gateway:
+          description: Gateway microservice type handling the operation.
+          type: string
+        failureCode:
+          $ref: ./payment.yaml#/components/schemas/PaymentFailureCode
+        failureReason:
+          $ref: ./payment.yaml#/components/schemas/PaymentFailureReason
+        startedAt:
+          description: RFC 3339 timestamp when execution of the operation started.
+          type: string
+          format: date-time
+        completedAt:
+          description: RFC 3339 timestamp when execution of the operation completed.
+          type: string
+          format: date-time
+
+    PaymentOperationMoney:
+      description: Planned and executed monetary snapshots associated with the operation.
+      type: object
+      additionalProperties: false
+      properties:
+        planned:
+          description: Monetary values planned for the operation before execution.
+          $ref: ./payment.yaml#/components/schemas/PaymentOperationMoneySnapshot
+        executed:
+          description: Monetary values observed after the operation was executed.
+          $ref: ./payment.yaml#/components/schemas/PaymentOperationMoneySnapshot
+
+    PaymentOperationMoneySnapshot:
+      description: Monetary snapshot containing base and converted amounts for an operation state.
+      type: object
+      additionalProperties: false
+      properties:
+        amount:
+          description: Primary money amount associated with the operation snapshot.
+          $ref: ../common/money.yaml#/components/schemas/Money
+        convertedAmount:
+          description: Secondary amount for conversion operations in the same snapshot.
+          $ref: ../common/money.yaml#/components/schemas/Money
+
+    Payment:
+      description: |
+        Persisted payment aggregate with status, quote, and operation history. A definitive
+        card-payout AML denial terminates the payment in the failed state and is reported as
+        `failureCode: failure_restriction` with `failureReason: aml_denied` at both payment
+        and failed-operation level.
+      type: object
+      additionalProperties: false
+      properties:
+        paymentRef:
+          description: Unique payment reference identifier.
+          type: string
+        state:
+          description: Current lifecycle state of the payment.
+          $ref: ../../external/payment_state.yaml#/components/schemas/PaymentState
+        comment:
+          description: Optional comment copied from the original payment intent.
+          type: string
+        source:
+          description: Source endpoint snapshot captured from intent.
+          $ref: ./payment.yaml#/components/schemas/PaymentResponseEndpoint
+        destination:
+          description: Destination endpoint snapshot captured from intent.
+          $ref: ./payment.yaml#/components/schemas/PaymentResponseEndpoint
+        failureCode:
+          $ref: ./payment.yaml#/components/schemas/PaymentFailureCode
+        failureReason:
+          $ref: ./payment.yaml#/components/schemas/PaymentFailureReason
+        operations:
+          description: Chronological list of operations executed for this payment.
+          type: array
+          items:
+            $ref: ./payment.yaml#/components/schemas/PaymentOperation
+        lastQuote:
+          description: Most recent payment quote used or generated for the payment.
+          $ref: ./payment.yaml#/components/schemas/PaymentQuote
+        createdAt:
+          description: RFC 3339 timestamp when the payment was created.
+          type: string
+          format: date-time
+        completedAt:
+          description: RFC 3339 timestamp when the payment reached a terminal state. Omitted while the payment is still in progress.
+          type: string
+          format: date-time
+        meta:
+          description: Additional metadata captured for the payment.
+          type: object
+          additionalProperties:
+            type: string

backend/contracts/sendico/models/payment_method/payment_method.yaml

@@ -0,0 +1,29 @@
+components:
+  schemas:
+    PaymentMethod:
+      allOf:
+        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
+        - $ref: ../common/describable.yaml#/components/schemas/Describable
+        - type: object
+          additionalProperties: false
+          required:
+            - ownerKind
+            - ownerRef
+            - type
+            - isMain
+          properties:
+            ownerKind:
+              type: string
+              enum:
+                - ACCOUNT
+                - RECIPIENT
+            ownerRef:
+              $ref: ../objectid.yaml#/components/schemas/ObjectId
+            type:
+              $ref: ../../external/payment_method_type.yaml#/components/schemas/PaymentMethodType
+            data:
+              description: Payment-method-type-specific payload. `bankAccount` methods use the same Russian bank-account data shape as `BankAccountEndpoint`.
+              type: object
+              additionalProperties: true
+            isMain:
+              type: boolean

backend/contracts/sendico/models/permission_bound.yaml

@@ -0,0 +1,23 @@
+components:
+  schemas:
+    PermissionBound:
+      description: Association between an organization and a permission, including archival state.
+      allOf:
+        - $ref: ./storable.yaml#/components/schemas/Storable
+        - type: object
+          description: Permission binding details scoped to an organization.
+          additionalProperties: false
+          required:
+            - organizationRef
+            - permissionRef
+            - isArchived
+          properties:
+            organizationRef:
+              description: Identifier of the organization that owns this permission binding.
+              $ref: ./objectid.yaml#/components/schemas/ObjectId
+            permissionRef:
+              description: Identifier of the permission granted to the organization.
+              $ref: ./objectid.yaml#/components/schemas/ObjectId
+            isArchived:
+              description: Indicates whether this object is archived and inactive.
+              type: boolean

backend/contracts/sendico/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

backend/contracts/sendico/models/storable.yaml

@@ -0,0 +1,22 @@
+components:
+  schemas:
+    Storable:
+      description: Common persistence metadata included on stored entities.
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - createdAt
+        - updatedAt
+      properties:
+        id:
+          description: Unique identifier assigned to the stored entity.
+          $ref: ./objectid.yaml#/components/schemas/ObjectId
+        createdAt:
+          description: RFC 3339 timestamp indicating when the entity was created.
+          type: string
+          format: date-time
+        updatedAt:
+          description: RFC 3339 timestamp indicating the most recent entity update.
+          type: string
+          format: date-time

backend/contracts/sendico/models/wallet/wallet_asset.yaml

@@ -0,0 +1,19 @@
+components:
+  schemas:
+    WalletAsset:
+      description: Canonical managed-wallet asset identified by chain, token symbol, and optional contract address.
+      type: object
+      additionalProperties: false
+      required:
+        - chain
+        - tokenSymbol
+      properties:
+        chain:
+          description: Canonical blockchain network for the asset.
+          $ref: ../../external/chain_network.yaml#/components/schemas/ChainNetwork
+        tokenSymbol:
+          description: Upper-case asset symbol.
+          type: string
+        contractAddress:
+          description: Normalized contract address for token assets. Omitted for native assets.
+          type: string