> ## 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` (always combined with tenant visibility), `externalReference` (exact match against your order, invoice or transfer reference), `intent` and `status`. 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-staging 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 intentionally documented in the separate Interfaces & SDKs reference. Console endpoints are dashboard implementation details and are not part of the partner integration contract. x-stableyard-documentation-surface: partner 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: 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 provider-neutral identity verification. Managed vaults and fiat payment rails use this same verified UPA identity. - name: Vaults description: >- Create Safe/Zodiac 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; the account filter is always combined with tenant visibility. 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 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: {} 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. 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: BadRequest response value: error: code: bad_request message: The request is invalid details: example 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 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 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 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: Conflict response value: error: code: bad_request message: The request is invalid details: example FailedDependency: description: Required chain, network, or provider configuration is missing 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: FailedDependency response value: error: code: bad_request message: The request is invalid details: example TooManyRequests: description: >- Rate limit, payment-option limit, selection cooldown, or temporary abuse block 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: TooManyRequests response value: error: code: bad_request message: The request is invalid details: example 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.