DOCUMENTATIONv2

GET

Payments

List payment requests

/api/v2/payment-requests

AUTHENTICATIONBearer token · payments:readAUTHORITATIVE OWNERpayment-serviceCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

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

WHEN THIS CALL IS USEFUL

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.

MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

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.

DOCUMENTATION STATUS

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-09-11T06:35:11.572Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation ↗Return to the V2 directory ↗