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

    LedgerEndpoint:
      description: Internal ledger-based endpoint used as payment source or destination.
      type: object
      additionalProperties: false
      required:
        - ledger_account_ref
      properties:
        ledger_account_ref:
          description: Reference of the primary ledger account.
          type: string
        contra_ledger_account_ref:
          description: Optional contra ledger account reference for balancing entries.
          type: string

    ManagedWalletEndpoint:
      description: Endpoint referencing a managed wallet within the platform.
      type: object
      additionalProperties: false
      required:
        - managed_wallet_ref
      properties:
        managed_wallet_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/Asset
        address:
          description: Target blockchain address.
          type: string
        memo:
          description: Optional destination memo or tag required by some chains.
          type: string

    CardEndpoint:
      description: Raw card details endpoint used for card-based payment flows.
      type: object
      additionalProperties: false
      required:
        - pan
      properties:
        pan:
          description: Primary account number of the card.
          type: string
        firstName:
          description: Cardholder first name.
          type: string
        lastName:
          description: Cardholder last name.
          type: string
        exp_month:
          description: Card expiration month.
          type: integer
          format: int32
          minimum: 0
        exp_year:
          description: Card expiration year.
          type: integer
          format: int32
          minimum: 0
        country:
          description: Card issuing country code.
          type: string

    CardTokenEndpoint:
      description: Tokenized card endpoint used instead of raw PAN details.
      type: object
      additionalProperties: false
      required:
        - token
      properties:
        token:
          description: Provider-issued card token.
          type: string
        masked_pan:
          description: Masked PAN representation for display and auditing.
          type: string

    WalletEndpoint:
      description: Generic wallet endpoint identified by wallet ID.
      type: object
      additionalProperties: false
      required:
        - walletId
      properties:
        walletId:
          description: Unique identifier of the wallet.
          type: string

    Endpoint:
      description: Polymorphic payment endpoint definition.
      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.
          oneOf:
            - $ref: ./payment.yaml#/components/schemas/LedgerEndpoint
            - $ref: ./payment.yaml#/components/schemas/ManagedWalletEndpoint
            - $ref: ./payment.yaml#/components/schemas/ExternalChainEndpoint
            - $ref: ./payment.yaml#/components/schemas/CardEndpoint
            - $ref: ./payment.yaml#/components/schemas/CardTokenEndpoint
            - $ref: ./payment.yaml#/components/schemas/WalletEndpoint
        metadata:
          description: Optional key-value metadata attached to the endpoint.
          type: object
          additionalProperties:
            type: string

    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

    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.
      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.
          $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
        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

    PaymentQuote:
      description: Pricing result for a specific payment intent.
      type: object
      additionalProperties: false
      properties:
        quoteRef:
          description: Unique identifier of the payment quote.
          type: string
        intentRef:
          description: Reference to the payment intent used for quoting.
          type: string
        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

    PaymentOperation:
      description: Execution step record captured during payment processing.
      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
        operationRef:
          description: External operation reference identifier reported by the gateway.
          type: string
        gateway:
          description: Gateway microservice type handling the operation.
          type: string
        failureCode:
          description: Machine-readable failure code when operation fails.
          type: string
        failureReason:
          description: Human-readable failure reason when operation fails.
          type: string
        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

    Payment:
      description: Persisted payment aggregate with status, quote, and operation history.
      type: object
      additionalProperties: false
      properties:
        paymentRef:
          description: Unique payment reference identifier.
          type: string
        idempotencyKey:
          description: Idempotency key used to safely deduplicate create requests.
          type: string
        state:
          description: Current lifecycle state of the payment.
          $ref: ../../external/payment_state.yaml#/components/schemas/PaymentState
        failureCode:
          description: Failure code set when the payment cannot be completed.
          type: string
        failureReason:
          description: Human-readable explanation of the failure.
          type: string
        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
        meta:
          description: Additional metadata captured for the payment.
          type: object
          additionalProperties:
            type: string