> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Bootstrap the client account

> Load the account, recent activity, pending actions and capability hints for a client.

Returns the account bundle, recent Stableyard-recorded activity, pending actions and capability hints for the account fixed by the client access token from [Exchange a client session token](/api-reference/client-sessions/exchange-client-session).


## OpenAPI

````yaml frontend-openapi.json GET /v2/client/bootstrap
openapi: 3.1.0
info:
  title: Stableyard Interfaces & SDK API
  version: 2.0.0-staging
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: >-
    Advanced browser API used by Stableyard Checkout, Add Money, and
    account-bound interfaces.
  description: >

    These endpoints power Stableyard's official interface SDKs, hosted checkout,
    Add Money, and advanced custom browser integrations.


    Most partners should use `@stableyard/react` or `@stableyard/sdk` instead of
    calling these routes directly. A browser must never receive an app secret.
    Public checkout uses a Payment-scoped client secret, while account-bound
    experiences use a short-lived client bearer token created by the partner
    backend.
  x-stableyard-documentation-surface: frontend
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Staging
  - url: http://localhost:3001
    description: Local
security: []
tags:
  - name: Authentication
    x-displayName: API authentication
    description: Verify your app ID and app secret before calling UPA APIs.
  - name: Client API
    description: >-
      Account-bound browser and mobile routes authenticated with a short-lived
      client bearer token. App secrets never enter client code.
  - name: Identity & KYC
    description: >-
      Verify the UPA email and run provider-neutral identity verification.
      Managed vaults and fiat payment rails use this same verified UPA identity.
  - name: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
paths:
  /v2/client/bootstrap:
    get:
      tags:
        - Client API
      summary: Bootstrap client account
      description: >-
        Returns the account bundle, recent Stableyard-recorded activity, pending
        actions, and capability hints for the account fixed by the client access
        token.
      operationId: clientBootstrap
      responses:
        '200':
          description: Client account bootstrap
          headers:
            Stableyard-Version:
              description: >-
                Effective date-based Stableyard API contract version for this
                response.
              schema:
                type: string
                enum:
                  - '2026-09-09'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientBootstrapResponse'
              examples:
                example:
                  summary: Bootstrap client account 200 response
                  value:
                    account:
                      id: acct_123
                      externalUserId: user_123
                      subjectType: individual
                      status: active
                      paymentAcceptance:
                        publicReceiveEnabled: false
                        version: 1
                      metadata: {}
                      createdAt: '2026-08-28T10:00:00.000Z'
                      updatedAt: '2026-08-28T10:00:00.000Z'
                    connectedWallets:
                      - id: wallet_123
                        accountId: acct_123
                        kind: evm
                        chainId: 42161
                        address: '0x1111111111111111111111111111111111111111'
                        label: Connected wallet
                        status: active
                        ownershipVerificationStatus: unverified
                        ownershipVerificationMethod: eip712_signature
                        settlementProfileId: settle_123
                        createdAt: '2026-08-28T10:00:00.000Z'
                        updatedAt: '2026-08-28T10:00:00.000Z'
                    activityTotals:
                      - {}
                    permissions:
                      - account:read
                    capabilities:
                      chainId: 42161
                      asset:
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                        symbol: USDC
                        decimals: 6
                        kind: token
                      canCreatePayments: true
                      paymentReadiness:
                        canInitiate: true
                        sourceReady: true
                        executableMethods:
                          - connected_wallet
                        blockedReasons:
                          - Requested by partner
                        checkedAt: '2026-08-28T10:00:00.000Z'
                      canReceiveDeposits: true
                      canCreateDepositAddresses: true
                      smartWalletModes:
                        - external_owner
                    recentTransactions:
                      - id: txn_123
                        accountId: acct_123
                        senderAccountId: acct_sender123
                        receiverAccountId: acct_receiver123
                        direction: sent
                        status: pending
                        amount:
                          asset:
                            chainId: 42161
                            tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                            symbol: USDC
                            decimals: 6
                            kind: token
                          amount: '1250000'
                        description: USDC payment
                        sourceType: payment
                        sourceId: payment_123
                        paymentId: payment_123
                        financialLegKind: collection
                    recentPayments:
                      - id: payment_123
                        apiVersion: '2026-09-09'
                        intent: receive
                        amountMode: collect_exact
                        status: requires_payment_method
                        offrampStatus: null
                        stage: null
                        operationalState: normal
                        operationalReasonCode: null
                        operationalUpdatedAt: null
                        statusVersion: 1
                        paymentAmount:
                          amount: '50.00'
                          amountAtomic: '50000000'
                          assetType: crypto
                          assetCode: USDC
                          decimals: 6
                          chainId: 8453
                          tokenAddress: '0x1111111111111111111111111111111111111111'
                        sourceAmount:
                          amount: '50.00'
                          amountAtomic: '50000000'
                          assetType: crypto
                          assetCode: USDC
                          decimals: 6
                          chainId: 8453
                          tokenAddress: '0x1111111111111111111111111111111111111111'
                        participants:
                          - role: sender
                            accountId: acct_123
                        recipientDisplay:
                          displayName: Example account
                          logoUrl: null
                        destination:
                          type: upa
                          accountId: acct_123
                        settlement:
                          type: settlement_destination
                          settlementDestinationId: null
                          destinationType: example
                          destinationAddress: '0x1111111111111111111111111111111111111111'
                          chainId: 1
                          assetCode: USDC
                          tokenAddress: '0x1111111111111111111111111111111111111111'
                          decimals: 0
                        fees:
                          version: null
                          pricingStatus: quote_pending
                          platformFeeBps: 0
                          partnerFeeBps: 0
                          platformFeeAmountAtomic: null
                          partnerFeeAmountAtomic: null
                          merchantNetAmountAtomic: null
                        funding:
                          mode: escrow
                          required:
                            amount: '1000000'
                            amountAtomic: '1000000'
                            assetType: crypto
                            assetCode: USDC
                            decimals: 0
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                          providerPrincipal:
                            amount: '1000000'
                            amountAtomic: '1000000'
                            assetType: crypto
                            assetCode: USDC
                            decimals: 0
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                          providerFee:
                            amount: '1000000'
                            amountAtomic: '1000000'
                            assetType: crypto
                            assetCode: USDC
                            decimals: 0
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                          platformFee:
                            amount: '1000000'
                            amountAtomic: '1000000'
                            assetType: crypto
                            assetCode: USDC
                            decimals: 0
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                          partnerFee:
                            amount: '1000000'
                            amountAtomic: '1000000'
                            assetType: crypto
                            assetCode: USDC
                            decimals: 0
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                          totalFees:
                            amount: '1000000'
                            amountAtomic: '1000000'
                            assetType: crypto
                            assetCode: USDC
                            decimals: 0
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                          exchangeRate:
                            rate: '1000000'
                            baseAssetCode: USDC
                            quoteAssetCode: USDC
                          quoteExpiresAt: null
                          depositAddress:
                            address: '0x1111111111111111111111111111111111111111'
                            chainId: 1
                            tokenAddress: '0x1111111111111111111111111111111111111111'
                            assetCode: USDC
                            decimals: 0
                            amount: '1000000'
                            amountAtomic: '1000000'
                        externalReference: null
                        description: null
                        metadata: {}
                        expiresAt: null
                        acceptedAt: null
                        succeededAt: null
                        cancelledAt: null
                        failure:
                          code: null
                          message: null
                        refundSummary:
                          status: none
                          count: 0
                          requestedAmountAtomic: '1000000'
                          confirmedAmountAtomic: '1000000'
                        incidentRecoverySummary:
                          count: 0
                          pendingCount: 0
                          confirmedCount: 0
                          failedCount: 0
                          requiresInterventionCount: 0
                          requestedAmountAtomic: '1000000'
                          confirmedAmountAtomic: '1000000'
                        createdAt: '2026-08-28T10:00:00.000Z'
                        updatedAt: '2026-08-28T10:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - clientBearerAuth: []
components:
  schemas:
    ClientBootstrapResponse:
      type: object
      additionalProperties: false
      required:
        - account
        - connectedWallets
        - activityTotals
        - capabilities
        - permissions
        - recentTransactions
        - recentPayments
      properties:
        account:
          $ref: '#/components/schemas/Account'
        paymentHandle:
          $ref: '#/components/schemas/PaymentHandle'
        connectedWallets:
          type: array
          items:
            $ref: '#/components/schemas/ConnectedWallet'
        settlementProfile:
          $ref: '#/components/schemas/SettlementProfile'
        activityTotals:
          type: array
          items:
            type: object
            additionalProperties: true
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/ClientPermission'
        capabilities:
          type: object
          additionalProperties: false
          required:
            - chainId
            - asset
            - canCreatePayments
            - paymentReadiness
            - canReceiveDeposits
            - canCreateDepositAddresses
            - smartWalletModes
          properties:
            chainId:
              type: integer
              example: 42161
            asset:
              $ref: '#/components/schemas/Asset'
            canCreatePayments:
              type: boolean
              description: >-
                Compatibility summary of paymentReadiness.canInitiate after
                client-token permission narrowing.
            paymentReadiness:
              type: object
              additionalProperties: false
              required:
                - canInitiate
                - sourceReady
                - executableMethods
                - blockedReasons
                - checkedAt
              properties:
                canInitiate:
                  type: boolean
                  description: >-
                    A preflight hint that the configured source and client
                    permissions are usable. Preview or quote remains
                    authoritative for a specific Payment.
                sourceReady:
                  type: boolean
                  description: >-
                    True when the selected source passes its persisted readiness
                    checks.
                executableMethods:
                  type: array
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                      - connected_wallet
                      - vault
                      - deposit_balance
                      - smart_wallet
                blockedReasons:
                  type: array
                  uniqueItems: true
                  items:
                    type: string
                    minLength: 1
                    maxLength: 128
                checkedAt:
                  type: string
                  format: date-time
            canReceiveDeposits:
              type: boolean
              description: True when the account has an active settlement profile.
            canCreateDepositAddresses:
              type: boolean
              description: >-
                True when the account can receive deposits and the client token
                carries the deposit-address module scope.
            smartWalletModes:
              type: array
              items:
                type: string
                enum:
                  - external_owner
                  - managed
        recentTransactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        recentPayments:
          type: array
          items:
            $ref: '#/components/schemas/CanonicalPaymentResource'
    Account:
      type: object
      additionalProperties: false
      required:
        - id
        - externalUserId
        - subjectType
        - status
        - paymentAcceptance
        - metadata
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: acct_123
        externalUserId:
          type: string
          maxLength: 128
          example: user_123
          description: >-
            The partner-owned external user ID supplied when this account was
            created. Unicode control characters are rejected.
        subjectType:
          type: string
          enum:
            - individual
            - business
            - unclassified
          example: individual
          description: >-
            Legal subject represented by the UPA. New accounts are individual or
            business. unclassified is returned only for historical accounts
            awaiting an audited classification and cannot initiate regulated
            rails.
        status:
          type: string
          enum:
            - active
            - suspended
            - closed
        displayProfile:
          $ref: '#/components/schemas/AccountDisplayProfile'
        paymentAcceptance:
          $ref: '#/components/schemas/AccountPaymentAcceptance'
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Optional partner metadata. Must be JSON-safe, at most 4096 bytes,
            depth 3, 25 keys per object, 512 characters per string, and 50 items
            per array.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaymentHandle:
      type: object
      required:
        - id
        - accountId
        - namespace
        - handle
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: handle_123
        accountId:
          type: string
          example: acct_123
        namespace:
          type: string
          example: partner
        handle:
          type: string
          example: alice
        status:
          type: string
          enum:
            - active
            - disabled
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ConnectedWallet:
      type: object
      required:
        - id
        - accountId
        - kind
        - chainId
        - address
        - status
        - ownershipVerificationStatus
        - settlementProfileId
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: wallet_123
        accountId:
          type: string
          example: acct_123
        kind:
          type: string
          enum:
            - evm
            - tron
            - solana
            - movement
        chainId:
          type: integer
          enum:
            - 42161
            - 1
            - 8453
            - 137
            - 56
            - 43114
            - 4663
            - 4217
            - 10103
            - 10002
            - 728126428
          example: 42161
          description: >-
            Supported connected-wallet chain IDs: Arbitrum=42161, Ethereum=1,
            Base=8453, Polygon=137, BNB Smart Chain=56, Avalanche=43114,
            Robinhood Chain=4663, Tempo=4217, Solana=10103, Movement=10002,
            Tron=728126428. Address family must match the selected chain ID.
        address:
          type: string
          example: '0x1111111111111111111111111111111111111111'
          description: >-
            Wallet address. EVM addresses are normalized to lowercase before
            storage; other address families retain their submitted casing.
        label:
          type:
            - string
            - 'null'
          example: Connected wallet
        status:
          type: string
          enum:
            - active
            - disabled
          description: Whether this wallet link can be used by the account.
        ownershipVerificationStatus:
          type: string
          enum:
            - unverified
            - verified
          description: >-
            Ownership is unverified until Stableyard records a successful proof.
            Linking a wallet alone never verifies ownership.
        ownershipVerificationMethod:
          type:
            - string
            - 'null'
          example: eip712_signature
        ownershipVerifiedAt:
          type:
            - string
            - 'null'
          format: date-time
        settlementProfileId:
          type:
            - string
            - 'null'
          example: settle_123
          description: >-
            The active settlement profile id when this wallet is the account
            settlement wallet; otherwise null.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SettlementProfile:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - version
        - connectedWalletId
        - settlementDestinationId
        - status
        - destinationType
        - chainId
        - destinationAddress
        - assetSymbol
        - tokenAddress
        - snapshot
      properties:
        id:
          type: string
          example: settle_123
        accountId:
          type: string
          example: acct_123
        version:
          type: integer
          minimum: 1
          example: 2
        connectedWalletId:
          type:
            - string
            - 'null'
          example: wallet_123
        settlementDestinationId:
          type:
            - string
            - 'null'
          example: destination_123
        status:
          type: string
          enum:
            - draft
            - active
            - inactive
            - failed
        destinationType:
          type: string
          enum:
            - smart_wallet
            - connected_wallet
            - external_wallet
        chainId:
          type: integer
          enum:
            - 42161
            - 1
            - 8453
            - 137
            - 56
            - 43114
            - 4663
            - 4217
            - 10103
            - 10002
          description: >-
            Supported settlement chain IDs: Arbitrum=42161, Ethereum=1,
            Base=8453, Polygon=137, BNB Smart Chain=56, Avalanche=43114,
            Robinhood Chain=4663, Tempo=4217, Solana=10103, Movement=10002.
            Settlement currently supports EVM, Solana, and Movement token
            destinations. Movement also supports THBT, while Polygon supports
            direct same-chain JPYC settlement. Tron is deposit-only for
            settlement-fee escrow.
        destinationAddress:
          type: string
          example: '11111111111111111111111111111111'
        assetSymbol:
          type: string
          enum:
            - USDC
            - USDT
            - THBT
            - JPYC
            - USDG
        tokenAddress:
          type: string
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
        snapshot:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ClientPermission:
      type: string
      enum:
        - account:read
        - payments:read
        - payments:write
        - deposits:read
        - deposits:write
        - vault_payments:write
      description: >-
        Account-bound browser/mobile authority granted by the partner backend.
        This is narrower than the issuing app credential and cannot enable a
        disabled app product.
    Asset:
      type: object
      required:
        - chainId
        - tokenAddress
        - symbol
        - decimals
      properties:
        chainId:
          type: integer
          enum:
            - 42161
            - 1
            - 8453
            - 137
            - 56
            - 43114
            - 4663
            - 4217
            - 10103
            - 10002
            - 728126428
            - 10001
          description: >-
            Supported deposit chain IDs: Arbitrum=42161, Ethereum=1, Base=8453,
            Polygon=137, BNB Smart Chain=56, Avalanche=43114, Robinhood
            Chain=4663, Tempo=4217, Solana=10103, Movement=10002,
            Tron=728126428, Bitcoin=10001.
        tokenAddress:
          type: string
          description: >-
            Contract/mint address for tokens, the EVM zero address for native
            EVM assets, native for BTC, or the Solana System Program address for
            SOL.
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
        symbol:
          type: string
          enum:
            - USDC
            - USDT
            - THBT
            - JPYC
            - USDG
            - BTC
            - ETH
            - POL
            - BNB
            - SOL
        decimals:
          type: integer
          enum:
            - 6
            - 8
            - 9
            - 18
        kind:
          type: string
          enum:
            - token
            - native
          description: >-
            Present on deposit-address supportedAssets entries to distinguish
            contract tokens from native gas assets.
    Transaction:
      type: object
      required:
        - id
        - accountId
        - status
        - amount
        - description
        - sourceType
        - sourceId
      properties:
        offrampDetails:
          $ref: '#/components/schemas/OfframpTransactionDetails'
        id:
          type: string
          example: txn_123
        accountId:
          type: string
          example: acct_123
          description: Account whose perspective this response is for.
        senderAccountId:
          type: string
          example: acct_sender123
          description: Present when the perspective account is the sender.
        receiverAccountId:
          type: string
          example: acct_receiver123
          description: Present when the perspective account is the receiver.
        direction:
          type: string
          enum:
            - sent
            - received
            - self
            - related
        perspective:
          $ref: '#/components/schemas/TransactionPerspective'
        status:
          type: string
          enum:
            - pending
            - completed
            - posted
            - failed
            - reversed
        amount:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: >-
            Amount for the requested account's perspective. For a Send, the
            sender sees the gross source debit and the recipient sees the net
            destination amount actually settled.
        description:
          type: string
          example: USDC payment
        sourceType:
          type: string
          enum:
            - payment
            - deposit
            - vault_funding
            - fee
            - refund
            - adjustment
        sourceId:
          type: string
          example: payment_123
        paymentId:
          type: string
          pattern: ^payment_[A-Za-z0-9_-]+$
          description: Canonical Payment associated with this financial leg.
        financialLegKind:
          type: string
          enum:
            - collection
            - send_execution
            - settlement
            - fee_payout
            - refund
            - adjustment
        sourceTransfer:
          type: object
          additionalProperties: false
          required:
            - amount
          properties:
            amount:
              $ref: '#/components/schemas/Money'
            txHash:
              type: string
              description: >-
                Source-chain transaction hash when the financial leg originated
                from an on-chain transfer.
            logIndex:
              type: integer
              minimum: 0
              description: >-
                Source-chain event index when the transfer was detected from an
                indexed token event.
            fromAddress:
              type: string
              description: >-
                On-chain sender address that funded this financial leg, when
                captured from the source chain.
        settlement:
          type: object
          additionalProperties: false
          required:
            - amount
            - txHash
          properties:
            amount:
              $ref: '#/components/schemas/Money'
            txHash:
              type:
                - string
                - 'null'
    CanonicalPaymentResource:
      type: object
      additionalProperties: false
      required:
        - id
        - apiVersion
        - intent
        - amountMode
        - status
        - offrampStatus
        - stage
        - operationalState
        - operationalReasonCode
        - operationalUpdatedAt
        - statusVersion
        - paymentAmount
        - participants
        - destination
        - settlement
        - fees
        - funding
        - externalReference
        - description
        - metadata
        - expiresAt
        - acceptedAt
        - succeededAt
        - cancelledAt
        - failure
        - refundSummary
        - incidentRecoverySummary
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^payment_[A-Za-z0-9_-]+$
        apiVersion:
          $ref: '#/components/schemas/StableyardApiVersion'
        intent:
          type: string
          enum:
            - receive
            - send
        amountMode:
          type: string
          enum:
            - collect_exact
            - deliver_exact
        status:
          type: string
          enum:
            - requires_payment_method
            - requires_action
            - processing
            - accepted
            - succeeded
            - failed
            - cancelled
            - expired
          description: >-
            Customer-facing financial lifecycle. Operational recovery never
            regresses a succeeded Payment or replaces this value with
            requires_intervention.
        offrampStatus:
          type:
            - string
            - 'null'
          enum:
            - not_started
            - processing
            - failed
            - refunding
            - refunded
            - succeeded
            - null
          description: >-
            External payout outcome. failed requires a verified terminal payout
            failure after confirmed treasury funding; any pre-funding failure is
            not_started. refunding means an operations recovery has reserved the
            treasury-held source amount for the sending UPA's frozen preferred
            crypto settlement destination, and refunded means that settlement is
            confirmed. Null for other Payment types.
        stage:
          type:
            - string
            - 'null'
          enum:
            - escrow_provisioning
            - awaiting_payment
            - destination_verifying
            - provider_processing
            - quote_pending
            - transaction_broadcast
            - receipt_verifying
            - payment_detected
            - settlement_pending
            - settlement_broadcast
            - settlement_confirming
            - settlement_returned
            - payout_pending
            - payout_processing
            - payout_confirming
            - refund_pending
            - refund_broadcast
            - null
          description: >-
            Current financial-processing stage. Operational review is
            represented separately by operationalState.
        operationalState:
          type: string
          enum:
            - normal
            - retrying
            - requires_intervention
          description: >-
            Operational health of the Payment. requires_intervention means
            Stableyard operations must act; it is not a financial payment
            status.
        operationalReasonCode:
          type:
            - string
            - 'null'
          enum:
            - collection_requires_intervention
            - custody_after_failure
            - duplicate_payment_detected
            - fee_payout_failed
            - fee_payout_requires_intervention
            - fee_payout_retry_scheduled
            - late_payment_received
            - payment_execution_requires_intervention
            - payment_execution_retry_scheduled
            - escrow_provisioning_retry_scheduled
            - payment_session_requires_intervention
            - payout_failed
            - payout_requires_intervention
            - payout_retry_scheduled
            - refund_failed
            - refund_requires_intervention
            - refund_retry_scheduled
            - settlement_failed
            - settlement_requires_intervention
            - settlement_retry_scheduled
            - settlement_unconfirmed
            - null
          description: >-
            Machine-readable operational reason when operationalState is not
            normal.
        operationalUpdatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the operational state or reason last changed.
        statusVersion:
          type: integer
          minimum: 1
        paymentAmount:
          $ref: '#/components/schemas/CanonicalPaymentAmount'
        sourceAmount:
          $ref: '#/components/schemas/CanonicalPaymentAmount'
          description: >-
            Frozen source debit including commercial fees, exposed for Send
            execution to callers permitted to view sender fees.
        participants:
          type: array
          items:
            $ref: '#/components/schemas/CanonicalPaymentParticipant'
          description: >-
            Only participant UPAs owned by the authenticated tenant are
            returned. The array can be empty for creator-only visibility.
        recipientDisplay:
          oneOf:
            - title: Recipient display snapshot
              type: object
              additionalProperties: false
              required:
                - displayName
                - logoUrl
              properties:
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 120
                logoUrl:
                  type:
                    - string
                    - 'null'
                  format: uri
                  maxLength: 2048
            - title: No recipient display snapshot
              type: 'null'
          description: >-
            Immutable payer-facing recipient identity captured when the Payment
            was created.
        destination:
          $ref: '#/components/schemas/CanonicalPaymentDestination'
        settlement:
          description: >-
            Immutable receive-side settlement snapshot. Null for Payment types
            that do not use a receive settlement destination.
          oneOf:
            - $ref: '#/components/schemas/CanonicalPaymentSettlement'
              title: Settlement destination
            - title: No settlement destination
              type: 'null'
        fees:
          oneOf:
            - title: Commercial fee quote pending
              type: object
              additionalProperties: false
              required:
                - version
                - pricingStatus
                - platformFeeBps
                - partnerFeeBps
                - platformFeeAmountAtomic
                - partnerFeeAmountAtomic
                - merchantNetAmountAtomic
              properties:
                version:
                  type:
                    - string
                    - number
                    - 'null'
                pricingStatus:
                  type: string
                  const: quote_pending
                platformFeeBps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                partnerFeeBps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                platformFeeAmountAtomic:
                  type: 'null'
                partnerFeeAmountAtomic:
                  type: 'null'
                merchantNetAmountAtomic:
                  type: 'null'
            - title: Quoted commercial fee snapshot
              type: object
              additionalProperties: false
              required:
                - version
                - pricingStatus
                - platformFeeBps
                - partnerFeeBps
                - platformFeeAmountAtomic
                - partnerFeeAmountAtomic
                - merchantNetAmountAtomic
              properties:
                version:
                  type:
                    - string
                    - number
                    - 'null'
                pricingStatus:
                  type: string
                  const: quoted
                platformFeeBps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                partnerFeeBps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                platformFeeAmountAtomic:
                  type: string
                  maxLength: 80
                  pattern: ^(0|[1-9][0-9]*)$
                partnerFeeAmountAtomic:
                  type: string
                  maxLength: 80
                  pattern: ^(0|[1-9][0-9]*)$
                merchantNetAmountAtomic:
                  type: string
                  maxLength: 80
                  pattern: ^(0|[1-9][0-9]*)$
            - title: Fees unavailable
              type: 'null'
          description: >-
            Commercial fee terms are returned only to the partner that owns
            them. quote_pending exposes frozen BPS but keeps exact monetary
            amounts null until the provider quote is frozen; quoted exposes
            immutable exact atomic amounts, including genuine zero values.
        funding:
          description: >-
            Create-time funding quote for an external fiat send rail. required
            is the exact source amount shown before Vault authorization;
            creation itself does not debit funds or submit the destination
            payout. Null for ordinary receive and direct-send Payments.
          oneOf:
            - $ref: '#/components/schemas/CanonicalExternalQrFunding'
              title: External provider payout funding
            - title: No separate funding collection
              type: 'null'
        externalReference:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        acceptedAt:
          type:
            - string
            - 'null'
          format: date-time
        succeededAt:
          type:
            - string
            - 'null'
          format: date-time
        cancelledAt:
          type:
            - string
            - 'null'
          format: date-time
        failure:
          oneOf:
            - title: Failure details
              type: object
              additionalProperties: false
              required:
                - code
                - message
              properties:
                code:
                  type:
                    - string
                    - 'null'
                message:
                  type:
                    - string
                    - 'null'
            - title: No failure
              type: 'null'
        refundSummary:
          $ref: '#/components/schemas/CanonicalPaymentRefundSummary'
        incidentRecoverySummary:
          $ref: '#/components/schemas/CanonicalPaymentIncidentRecoverySummary'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              minLength: 1
              maxLength: 128
              example: bad_request
            message:
              type: string
              minLength: 1
              maxLength: 1000
              example: The request is invalid
            details: {}
    AccountDisplayProfile:
      type: object
      additionalProperties: false
      required:
        - displayName
        - logoUrl
        - version
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 120
          example: Acme Downtown
        logoUrl:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2048
          example: https://cdn.example.com/acme-downtown.png
        version:
          type: integer
          minimum: 1
          example: 2
      description: >-
        Account-level recipient presentation. It identifies who is being paid
        and is distinct from app branding.
    AccountPaymentAcceptance:
      type: object
      additionalProperties: false
      required:
        - publicReceiveEnabled
        - version
      properties:
        publicReceiveEnabled:
          type: boolean
          example: false
        version:
          type: integer
          minimum: 0
          example: 1
      description: >-
        Per-UPA opt-in for public receive Payment creation. App-level public
        Payment policy is enforced separately.
    OfframpTransactionDetails:
      type: object
      additionalProperties: false
      description: >-
        Frozen off-ramp quote and recipient details. Bank account numbers are
        represented by their last four characters; unavailable recipient fields
        are null. Amounts are exact atomic strings and the exchange rate retains
        its direction.
      required:
        - version
        - country
        - destinationType
        - fiatAmount
        - fundingAmount
        - providerPrincipal
        - fees
        - exchangeRate
        - receiver
      properties:
        version:
          type: integer
          const: 1
        country:
          type: string
        destinationType:
          type: string
          enum:
            - external_qr
            - external_bank
            - bank_account
        fiatAmount:
          type: object
          additionalProperties: false
          required:
            - amountAtomic
            - assetCode
            - decimals
          properties:
            amountAtomic:
              type:
                - string
                - 'null'
              pattern: ^[0-9]+$
              description: >-
                Exact fiat amount scaled by the accompanying decimals
                (exact-input payout receipts can use six decimals), or null when
                unknown when this transaction snapshot was recorded (for
                example, an exact-input payout before provider completion). Null
                is not zero or proof of payout failure. Read the associated
                Payment for its current payout result.
            assetCode:
              type: string
            decimals:
              type: integer
        fundingAmount:
          oneOf:
            - $ref: '#/components/schemas/OfframpTransactionAmount'
            - type: 'null'
        providerPrincipal:
          oneOf:
            - $ref: '#/components/schemas/OfframpTransactionAmount'
            - type: 'null'
        fees:
          type: object
          additionalProperties: false
          required:
            - provider
            - platform
            - partner
          properties:
            provider:
              oneOf:
                - $ref: '#/components/schemas/OfframpTransactionAmount'
                - type: 'null'
            platform:
              oneOf:
                - $ref: '#/components/schemas/OfframpTransactionAmount'
                - type: 'null'
            partner:
              oneOf:
                - $ref: '#/components/schemas/OfframpTransactionAmount'
                - type: 'null'
        exchangeRate:
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - rate
                - baseAssetCode
                - quoteAssetCode
              properties:
                rate:
                  type: string
                baseAssetCode:
                  type: string
                quoteAssetCode:
                  type: string
            - type: 'null'
        receiver:
          type: object
          additionalProperties: false
          required:
            - name
            - bankName
            - bankCode
            - accountNumberLast4
          properties:
            name:
              type:
                - string
                - 'null'
            bankName:
              type:
                - string
                - 'null'
            bankCode:
              type:
                - string
                - 'null'
            accountNumberLast4:
              type:
                - string
                - 'null'
    TransactionPerspective:
      type: object
      additionalProperties: false
      required:
        - accountId
        - direction
      properties:
        accountId:
          type: string
          example: acct_sender123
        direction:
          type: string
          enum:
            - sent
            - received
            - self
            - related
          description: >-
            Direction from the perspective of the account that requested or
            matched this transaction.
        counterpartyAccountId:
          type: string
          example: acct_receiver123
          description: Other Stableyard account on the transaction when known.
    Money:
      type: object
      required:
        - asset
        - amount
      properties:
        asset:
          $ref: '#/components/schemas/Asset'
        amount:
          type: string
          description: Atomic units for the token asset.
          example: '1250000'
    StableyardApiVersion:
      type: string
      enum:
        - '2026-08-28'
        - '2026-09-09'
      example: '2026-09-09'
      description: >-
        Immutable date-based contract recorded on the resource. Historical
        values may appear on existing records; only versions advertised in
        x-stableyard-supported-api-versions are accepted for new requests.
    CanonicalPaymentAmount:
      type: object
      additionalProperties: false
      required:
        - amount
        - amountAtomic
        - assetType
        - assetCode
        - decimals
      properties:
        amount:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$
          example: '50.00'
        amountAtomic:
          type: string
          minLength: 1
          maxLength: 80
          pattern: ^[1-9][0-9]*$
          example: '50000000'
        assetType:
          type: string
          enum:
            - crypto
            - fiat
        assetCode:
          type: string
          example: USDC
        decimals:
          type: integer
          minimum: 0
          maximum: 36
          example: 6
        chainId:
          type: integer
          minimum: 1
          example: 8453
        tokenAddress:
          type: string
    CanonicalPaymentParticipant:
      type: object
      additionalProperties: false
      required:
        - role
        - accountId
      properties:
        role:
          type: string
          enum:
            - sender
            - recipient
        accountId:
          type: string
          description: >-
            A UPA account belonging to the authenticated organization, app, and
            environment. Participants owned by another tenant are omitted.
    CanonicalPaymentDestination:
      title: Resolved payment destination
      oneOf:
        - title: UPA account
          type: object
          additionalProperties: false
          required:
            - type
            - accountId
          properties:
            type:
              type: string
              const: upa
            accountId:
              type: string
        - title: Payment handle
          type: object
          additionalProperties: false
          required:
            - type
            - paymentHandle
            - accountId
          properties:
            type:
              type: string
              const: payment_handle
            paymentHandle:
              type: string
            accountId:
              type: string
        - title: External crypto wallet
          type: object
          additionalProperties: false
          required:
            - type
            - chainId
            - address
            - assetCode
            - tokenAddress
          properties:
            type:
              type: string
              const: crypto_wallet
            chainId:
              type: integer
              minimum: 1
            address:
              type: string
            assetCode:
              type: string
            tokenAddress:
              type: string
        - title: External merchant QR
          type: object
          additionalProperties: false
          required:
            - type
            - country
            - currency
            - dynamic
            - merchant
          properties:
            type:
              type: string
              const: external_qr
            country:
              type: string
              pattern: ^[A-Z]{2}$
              example: PH
            currency:
              type: string
              pattern: ^[A-Z]{3}$
              example: PHP
            dynamic:
              type: boolean
            merchant:
              oneOf:
                - title: Merchant details
                  type: object
                  additionalProperties: false
                  required:
                    - name
                    - city
                  properties:
                    name:
                      type:
                        - string
                        - 'null'
                    city:
                      type:
                        - string
                        - 'null'
                - title: Merchant details unavailable
                  type: 'null'
        - title: External bank beneficiary
          type: object
          additionalProperties: false
          required:
            - type
            - country
            - currency
            - beneficiary
          properties:
            type:
              type: string
              const: external_bank
            country:
              type: string
              pattern: ^[A-Z]{2}$
              example: VN
            currency:
              type: string
              pattern: ^[A-Z]{3}$
              example: VND
            beneficiary:
              type: object
              additionalProperties: false
              required:
                - accountHolderName
                - accountNumberLast4
                - bankCode
                - bankName
                - country
              properties:
                accountHolderName:
                  type:
                    - string
                    - 'null'
                  maxLength: 200
                accountNumberLast4:
                  type:
                    - string
                    - 'null'
                  pattern: ^[A-Za-z0-9]{4}$
                bankCode:
                  type:
                    - string
                    - 'null'
                  maxLength: 64
                bankName:
                  type:
                    - string
                    - 'null'
                  maxLength: 200
                country:
                  type:
                    - string
                    - 'null'
                  pattern: ^[A-Z]{2}$
        - title: Verified linked bank account
          type: object
          additionalProperties: false
          required:
            - type
            - bankAccountId
            - country
            - currency
            - bankName
            - accountNumberLast4
            - rail
          properties:
            type:
              type: string
              const: bank_account
            bankAccountId:
              type: string
              pattern: ^bank_[A-Za-z0-9_-]{3,59}$
              example: bank_123
            country:
              type: string
              pattern: ^[A-Z]{2}$
              example: US
            currency:
              type: string
              pattern: ^[A-Z]{3}$
              example: USD
            bankName:
              type: string
              minLength: 1
              maxLength: 160
              example: Example Bank
            accountNumberLast4:
              type: string
              pattern: ^[A-Za-z0-9]{4,8}$
              example: '6789'
            rail:
              type: string
              minLength: 1
              maxLength: 64
              example: ach
      discriminator:
        propertyName: type
    CanonicalPaymentSettlement:
      type: object
      additionalProperties: false
      required:
        - type
        - settlementDestinationId
        - destinationType
        - destinationAddress
        - chainId
        - assetCode
        - tokenAddress
        - decimals
      properties:
        type:
          type: string
          enum:
            - settlement_destination
            - crypto_wallet
        settlementDestinationId:
          type:
            - string
            - 'null'
        destinationType:
          type: string
        destinationAddress:
          type: string
        chainId:
          type: integer
          minimum: 1
        assetCode:
          type: string
        tokenAddress:
          type: string
        decimals:
          type: integer
          minimum: 0
          maximum: 36
    CanonicalExternalQrFunding:
      type: object
      additionalProperties: false
      required:
        - required
        - providerPrincipal
        - providerFee
        - platformFee
        - partnerFee
        - totalFees
        - exchangeRate
        - quoteExpiresAt
        - depositAddress
      properties:
        mode:
          type: string
          enum:
            - escrow
            - vault_treasury
          description: >-
            New external payouts use a unique Payment escrow. vault_treasury is
            returned only for legacy direct-funded records that remain under
            reconciliation.
        required:
          $ref: '#/components/schemas/CanonicalFundingAmount'
        providerPrincipal:
          oneOf:
            - $ref: '#/components/schemas/CanonicalFundingAmount'
            - type: 'null'
        providerFee:
          oneOf:
            - $ref: '#/components/schemas/CanonicalFundingAmount'
            - type: 'null'
        platformFee:
          oneOf:
            - $ref: '#/components/schemas/CanonicalFundingAmount'
            - type: 'null'
        partnerFee:
          oneOf:
            - $ref: '#/components/schemas/CanonicalFundingAmount'
            - type: 'null'
        totalFees:
          description: >-
            Total payout fees in the funding asset: providerFee + platformFee
            (Stableyard) + partnerFee (app partner). Already included in
            required; do not add again. Null when fee visibility is restricted
            or a frozen component is unavailable. Excludes any additional fee
            quoted separately by a selected funding method.
          oneOf:
            - $ref: '#/components/schemas/CanonicalFundingAmount'
            - type: 'null'
        exchangeRate:
          description: >-
            Directional rate frozen from the payout quote. One unit of
            baseAssetCode equals rate units of quoteAssetCode.
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - rate
                - baseAssetCode
                - quoteAssetCode
              properties:
                rate:
                  type: string
                  pattern: ^(?=.*[1-9])(?:0|[1-9][0-9]*)(?:\.[0-9]{1,18})?$
                baseAssetCode:
                  type: string
                quoteAssetCode:
                  type: string
            - type: 'null'
        quoteExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
        depositAddress:
          description: >-
            Where the sender must deposit the collection asset before Stableyard
            forwards net proceeds to the provider. Null until the collection
            escrow is provisioned and live.
          oneOf:
            - $ref: '#/components/schemas/CanonicalPaymentDepositInstructions'
            - type: 'null'
    CanonicalPaymentRefundSummary:
      type: object
      additionalProperties: false
      required:
        - status
        - count
        - requestedAmountAtomic
        - confirmedAmountAtomic
      properties:
        status:
          type: string
          enum:
            - none
            - pending
            - partially_refunded
            - refunded
            - failed
            - requires_intervention
        count:
          type: integer
          minimum: 0
        requestedAmountAtomic:
          type: string
          pattern: ^[0-9]+$
        confirmedAmountAtomic:
          type: string
          pattern: ^[0-9]+$
      description: >-
        Aggregate progress for Refund resources attached to this Payment.
        Supported direct receive refunds are created through the Partner API;
        eligible failed external payouts use a separate operations recovery
        after confirmed treasury receipt.
    CanonicalPaymentIncidentRecoverySummary:
      type: object
      additionalProperties: false
      required:
        - count
        - pendingCount
        - confirmedCount
        - failedCount
        - requiresInterventionCount
        - requestedAmountAtomic
        - confirmedAmountAtomic
      properties:
        count:
          type: integer
          minimum: 0
        pendingCount:
          type: integer
          minimum: 0
        confirmedCount:
          type: integer
          minimum: 0
        failedCount:
          type: integer
          minimum: 0
        requiresInterventionCount:
          type: integer
          minimum: 0
        requestedAmountAtomic:
          type: string
          pattern: ^[0-9]+$
        confirmedAmountAtomic:
          type: string
          pattern: ^[0-9]+$
      description: >-
        Recovery of duplicate, late, overpaid, or underpaid receipts. These
        amounts never contribute to refundSummary for the accepted merchant
        payment.
    OfframpTransactionAmount:
      type: object
      additionalProperties: false
      required:
        - amountAtomic
        - assetCode
        - decimals
        - chainId
        - tokenAddress
      properties:
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
        assetCode:
          type: string
        decimals:
          type: integer
        chainId:
          type: integer
        tokenAddress:
          type: string
    CanonicalFundingAmount:
      type: object
      additionalProperties: false
      required:
        - amount
        - amountAtomic
        - assetType
        - assetCode
        - decimals
        - chainId
        - tokenAddress
      properties:
        amount:
          type: string
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
        assetType:
          type: string
          const: crypto
        assetCode:
          type: string
        decimals:
          type: integer
          minimum: 0
          maximum: 36
        chainId:
          type: integer
          minimum: 1
        tokenAddress:
          type: string
    CanonicalPaymentDepositInstructions:
      type: object
      additionalProperties: false
      required:
        - address
        - chainId
        - tokenAddress
        - assetCode
        - decimals
        - amount
        - amountAtomic
      description: >-
        The exact on-chain deposit to make. Send precisely amountAtomic of
        tokenAddress on chainId to address; anything else will not be recognized
        as this Payment's funding.
      properties:
        address:
          type: string
        chainId:
          type: integer
          minimum: 1
        tokenAddress:
          type: string
        assetCode:
          type: string
        decimals:
          type: integer
          minimum: 0
          maximum: 36
        amount:
          type: string
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
  responses:
    Unauthorized:
      description: Unauthorized
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: Unauthorized response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
    NotFound:
      description: Not found
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: NotFound response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
  securitySchemes:
    clientBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Stableyard client access token
      description: >-
        Short-lived account-bound token returned by POST
        /v2/client/auth/exchange.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.