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

# List payments

> List the receive and send Payments visible to your app.

Filter by `accountId` or `externalUserId`, `externalReference` (exact match against your order, invoice or transfer reference), `intent` and `status`. Results include only Payments your app can see. Page with `limit` (up to 100, default 20) and `cursor`.

List items are canonical Payment resources without checkout credentials or transient next actions. [Get the Payment](/api-reference/payments/get-payment) when you need its current action.


## OpenAPI

````yaml openapi.json GET /v2/payments
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: Backend API for UPAs, Payments, activity, and optional financial products.
  description: >

    Use this API from a trusted partner backend with an app ID and app secret.


    ## Recommended integration


    1. Call `GET /v2/partners/config` to verify credentials and discover enabled
    capabilities.

    2. Create a UPA only when your product needs a persistent Stableyard
    account.

    3. Create a receive or send Payment with `POST /v2/payments`.

    4. Redirect a payer to the returned `paymentUrl` or pass the Payment
    credentials to an official Stableyard interface SDK.

    5. Process signed webhooks and fetch the Payment by ID for reconciliation.


    Checkout execution and account-bound browser endpoints are documented in the
    separate Interfaces & SDKs reference.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Sandbox
security: []
tags:
  - name: Authentication
    x-displayName: API authentication
    description: Verify your app ID and app secret before calling UPA APIs.
  - name: Accounts
    x-displayName: UPA Accounts
    description: Create Universal Payment Accounts and manage account settings.
  - name: Deposit Addresses
    description: Create reusable receive addresses and verify inbound deposits.
  - name: Identity & KYC
    description: >-
      Verify the UPA email and run identity verification. Managed vaults and
      fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create policy-controlled stablecoin vaults and manage policy updates for
      accounts.
  - name: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
  - name: Balances & Transactions
    description: >-
      Read Stableyard-posted financial activity. Balances are ledger projections
      of activity Stableyard processed; they are not live balances of externally
      controlled wallets.
paths:
  /v2/payments:
    get:
      tags:
        - Payments
      summary: List payments
      description: >-
        Lists canonical receive and send Payments visible to the authenticated
        app. Filter by either the Stableyard account ID or your external user
        ID; only Payments visible to your app are returned. List items are
        canonical Payment resources and intentionally omit checkout credentials
        and transient next actions. Fetch one Payment when you need its current
        action.
      operationId: listPayments
      parameters:
        - name: accountId
          in: query
          required: false
          schema:
            type: string
            example: acct_123
        - name: externalUserId
          in: query
          required: false
          schema:
            type: string
            example: user_123
        - name: externalReference
          in: query
          required: false
          description: Exact match against your order, invoice, or transfer reference.
          schema:
            type: string
            minLength: 1
            maxLength: 256
            example: invoice_1042
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque cursor returned as nextCursor by the previous page.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: intent
          in: query
          schema:
            type: string
            enum:
              - receive
              - send
        - name: status
          in: query
          schema:
            type: string
            enum:
              - requires_payment_method
              - requires_action
              - processing
              - accepted
              - succeeded
              - failed
              - cancelled
              - expired
        - name: Stableyard-Version
          in: header
          required: false
          schema:
            type: string
            enum:
              - '2026-09-09'
          description: >-
            Optional contract-version assertion. Omit it to use the app
            environment's pinned version. A different supported version is
            accepted only after that environment is explicitly migrated.
      responses:
        '200':
          description: Payments
          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/CanonicalPaymentListResponse'
              examples:
                firstPage:
                  summary: First page of Payments
                  value:
                    payments:
                      - id: payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR
                        apiVersion: '2026-09-09'
                        intent: receive
                        amountMode: collect_exact
                        status: requires_payment_method
                        offrampStatus: null
                        stage: awaiting_payment
                        operationalState: normal
                        operationalReasonCode: null
                        operationalUpdatedAt: null
                        statusVersion: 1
                        paymentAmount:
                          amount: '25.00'
                          amountAtomic: '25000000'
                          assetType: crypto
                          assetCode: USDC
                          decimals: 6
                          chainId: 42161
                          tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                        participants:
                          - role: recipient
                            accountId: acct_123
                        destination:
                          type: upa
                          accountId: acct_123
                        settlement:
                          type: settlement_destination
                          settlementDestinationId: destination_123
                          destinationType: connected_wallet
                          destinationAddress: '0x1111111111111111111111111111111111111111'
                          chainId: 42161
                          assetCode: USDC
                          tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                          decimals: 6
                        fees:
                          version: 1
                          pricingStatus: quoted
                          platformFeeBps: 50
                          partnerFeeBps: 0
                          platformFeeAmountAtomic: '125000'
                          partnerFeeAmountAtomic: '0'
                          merchantNetAmountAtomic: '24875000'
                        funding: null
                        externalReference: order_1042
                        description: 'Invoice #1042'
                        metadata: {}
                        expiresAt: '2026-08-28T10:10:00.000Z'
                        acceptedAt: null
                        succeededAt: null
                        cancelledAt: null
                        failure: null
                        refundSummary:
                          status: none
                          count: 0
                          requestedAmountAtomic: '0'
                          confirmedAmountAtomic: '0'
                        incidentRecoverySummary:
                          count: 0
                          pendingCount: 0
                          confirmedCount: 0
                          failedCount: 0
                          requiresInterventionCount: 0
                          requestedAmountAtomic: '0'
                          confirmedAmountAtomic: '0'
                        createdAt: '2026-08-28T10:00:00.000Z'
                        updatedAt: '2026-08-28T10:00:00.000Z'
                    nextCursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - partnerBasicAuth: []
components:
  schemas:
    CanonicalPaymentListResponse:
      type: object
      additionalProperties: false
      required:
        - payments
        - nextCursor
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/CanonicalPaymentResource'
        nextCursor:
          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: the payout failed after funding; a
            failure before funding is not_started. refunding: Stableyard is
            returning the source amount to the sender's preferred crypto
            settlement destination. refunded: the return 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 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 that belong to your app 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 payout 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 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: {}
    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 that belong to another app 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: >-
            `escrow`: source funds are collected into a Payment-specific escrow.
            Every new external payout uses it. `vault_treasury` may appear on
            older records.
        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
            executes the payout. Null until the collection escrow is ready.
          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.
        Returns of failed external payouts are reported through `offrampStatus`,
        not here.
    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.
    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:
    BadRequest:
      description: Bad request
      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: bad_request
              value:
                error:
                  code: bad_request
                  message: The request is invalid
    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
              value:
                error:
                  code: unauthorized
                  message: Authentication is required
    Forbidden:
      description: The app secret does not include the required scope
      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: forbidden
              value:
                error:
                  code: forbidden
                  message: The credential does not allow this operation
    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: not_found
              value:
                error:
                  code: not_found
                  message: The resource was not found
    Conflict:
      description: Conflict
      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: idempotency_conflict
              value:
                error:
                  code: idempotency_conflict
                  message: >-
                    The Idempotency-Key was already used with a different
                    request
    FailedDependency:
      description: This feature is not configured for your app or environment
      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: chain_config_missing
              value:
                error:
                  code: chain_config_missing
                  message: The requested network is not configured for this environment
    TooManyRequests:
      description: Too many requests. Retry after the `Retry-After` interval.
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
        Retry-After:
          description: Seconds until the caller should retry.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          description: Quota for the most constrained policy.
          schema:
            type: integer
            minimum: 1
        RateLimit-Remaining:
          description: Requests remaining in that policy window.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: Seconds until that policy window resets.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: rate_limited
              value:
                error:
                  code: rate_limited
                  message: Too many requests
  securitySchemes:
    partnerBasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth. Username is the Stableyard app ID. Password is the app
        secret. The optional Stableyard-Version request header must match the
        environment pin.

````

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