GET

Payments

List payment requests

/api/v2/payment-requests

AUTHENTICATIONBearer token · payments:readService ownerpayment-serviceContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Find payment requests involving the active workspace and reconcile whether each request is open, awaiting a later authorization, cancelled, satisfied, or expired.

When to use it

Call this for accounts-receivable and accounts-payable queues, before acting on a named request, and after an ambiguous request-bound payment attempt.

OUTCOME · Discover and reconcile

What changes

Read-only. It returns exact-decimal request terms and lifecycle evidence without accepting a request, reserving funds, creating a payment, or claiming settlement.

WHY IT MATTERS

Gives finance teams and agents one owner-isolated queue for money requested and money owed.
Makes expired and pending states explicit so a client does not duplicate a payment or falsely report completion.

ISOLATION + AUTHORITY

Core derives the active workspace from the signed gateway request. Only requests where that workspace is the payee or named payer are listed; profile, tenant, database, credential, and unrelated-workspace data are excluded.

BEFORE YOU CALL

A bearer token with payments:read.
An authenticated active workspace; use direction=incoming for named payer requests and direction=outgoing for requests issued by this workspace.

WHAT TO DO NEXT

For an OPEN incoming request, confirm its exact version, amount, and currency before creating a linked intent.
For PAYMENT_PENDING, locate the linked payment and inspect its current state.

AGENT GUIDANCE

Filter with the documented uppercase state values and continue pagination only with next_cursor from the same filter set.
Treat PAYMENT_PENDING as a linked authorization-required intent—not as paid, confirmed, or settled.
Use amount as a decimal string and never convert it through binary floating point.

Contract reference

Use the deployed OpenAPI for exact parameters, schemas and security requirements. The tables below provide integration guidance.

Open this operation in OpenAPI

Request and response

Make the request

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing payments:read authority.EXAMPLEBearer hc_live_…

cursorqueryOptional

32-character lowercase hexadecimal cursor · nullableCursor returned by the preceding page; reuse only with identical state and direction filters.EXAMPLEb4f2ed5fcfa7474d90f976a838670b14

limitqueryOptional

integer · 1–200 · nullableMaximum records to return; defaults to 50 and cannot exceed 200.Schema range: 0 to unboundedEXAMPLE50

statequeryOptional

OPEN | PAYMENT_PENDING | SATISFIED | CANCELLED | EXPIRED · nullableExact payment-request lifecycle filter. Omit it to use the documented default or unfiltered behavior.EXAMPLEOPEN

directionqueryOptional

incoming | outgoing | all · nullableRelationship to the authenticated workspace: incoming, outgoing, or all.EXAMPLEall

X-Request-IDheaderOptional

stringOptional caller correlation identifier. The gateway emits the effective value on the response.

RESPONSES

Status and payload examples

200Incoming requests name the authenticated workspace as payer; outgoing requests were created by it. OPEN is payable, PAYMENT_PENDING has an authorization-required intent, and no state is settlement proof.Read completed · JSON RESPONSE+

{
  "direction": "example-direction",
  "items": [
    {
      "amount": "100.00",
      "balance_mutation_performed": true,
      "created_at": "2026-09-02T18:30:00Z",
      "currency": "USD",
      "expires_at": "2026-09-02T18:30:00Z",
      "external_reference": "example-external-reference",
      "memo": "example-memo",
      "payee_workspace_id": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
      "payer_workspace_id": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
      "pending_payment_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
      "request_commitment": "example-request-commitment",
      "request_uuid": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB",
      "settlement_authority_granted": true,
      "state_commitment": "example-state-commitment",
      "status": "example-status",
      "updated_at": "2026-09-02T18:30:00Z",
      "version": 0
    }
  ],
  "limit": 0,
  "next_cursor": "example-next-cursor"
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then for an OPEN incoming request, confirm its exact version, amount, and currency before creating a linked intent.
RETRY SAFETY: For another page, send the returned opaque cursor unchanged with the same filters. Restart without a cursor when a new snapshot is required.
STATE RECONCILIATION: Use returned identifiers and versions as the comparison point for later reads. Re-read the owner-visible request or payment record and compare its status, version, exact decimal terms, commitments, and explicit safety flags before reusing the same Idempotency-Key with an equivalent mutation.

401Bearer credential is missing, expired, or invalid.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. Do not replay an expired signature.
STATE RECONCILIATION: Authentication failed before an authoritative read was returned for the owner-isolated payment-request and authorization-required intent control plane; authorization, reservation, rail execution, settlement, refunds, and receipts remain separate capabilities.
ESCALATE WHEN: Escalate when a record progressed beyond AUTHORIZATION_REQUIRED, source or rail state is ambiguous, a linked request cannot be reconciled, or a caller needs value movement, settlement, refund, or receipt authority that the implemented Payments control plane does not provide.

403The principal lacks the required scope, role, tenant, or step-up authority.Authority or policy denied · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for the owner-isolated payment-request and authorization-required intent control plane; authorization, reservation, rail execution, settlement, refunds, and receipts remain separate capabilities.
ESCALATE WHEN: Escalate when a record progressed beyond AUTHORIZATION_REQUIRED, source or rail state is ambiguous, a linked request cannot be reconciled, or a caller needs value movement, settlement, refund, or receipt authority that the implemented Payments control plane does not provide.

422A cursor, direction, limit, or state filter is invalid.Request must change · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. A corrected read may be sent as a new attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read the owner-visible request or payment record and compare its status, version, exact decimal terms, commitments, and explicit safety flags before reusing the same Idempotency-Key with an equivalent mutation.
ESCALATE WHEN: Escalate when a record progressed beyond AUTHORIZATION_REQUIRED, source or rail state is ambiguous, a linked request cannot be reconciled, or a caller needs value movement, settlement, refund, or receipt authority that the implemented Payments control plane does not provide.

503The authoritative service or read model is unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Treat the failure as transient and preserve the last known good representation without presenting it as fresh.
RETRY SAFETY: Retry with bounded exponential backoff and jitter; stop after the integration's failure budget is exhausted.
STATE RECONCILIATION: Re-read the owner-visible request or payment record and compare its status, version, exact decimal terms, commitments, and explicit safety flags before reusing the same Idempotency-Key with an equivalent mutation.
ESCALATE WHEN: Escalate when a record progressed beyond AUTHORIZATION_REQUIRED, source or rail state is ambiguous, a linked request cannot be reconciled, or a caller needs value movement, settlement, refund, or receipt authority that the implemented Payments control plane does not provide.

OPERATIONAL NOTES

Security and lifecycle guarantees

List owner-visible incoming or outgoing exact-decimal payment requests, filter by lifecycle state, and distinguish OPEN requests from requests with an authorization-required intent. Authoritative owner: payment-service.
The Rust gateway validates the public contract and routes only to the authoritative owner; clients never address internal services directly.
The tables and examples are derived from the current gateway source OpenAPI. Re-fetch the deployed OpenAPI before execution; deployment status is shown separately on this page.
Only parameters present in the OpenAPI operation are accepted; undocumented query keys fail closed with HTTP 422.

Reference version and availability details

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-10-02T23:27:55.510Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation Return to the V2 directory