> ## Documentation Index > Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt > Use this file to discover all available pages before exploring further. # List payment requests > Your agent's payment requests, newest first. ## OpenAPI ````yaml /api-reference/openapi.mint.yaml get /v1/payment_requests openapi: 3.1.0 info: title: Relay API version: 1.0.0 description: >- Create conversations between users and agents. Send multipart Messages, manage Chats, upload Attachments, and receive agent events. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.staging.relayapp.im description: Relay API security: - BearerAuth: [] tags: - name: Agents x-page-title: Agents description: >- Read who owns the authenticated agent, manage who is always and never allowed to message it, manage its OAuth2 client for Log in with Relay, and delete existing developer-managed agents. - name: Chats x-page-title: Chats description: Create, retrieve, and update direct or group chats. - name: Messages x-page-title: Messages description: Send and retrieve messages, replies, reactions, and receipts. - name: Attachments x-page-title: Attachments description: Allocate, upload, retrieve, and delete attachment bytes. - name: Blocked Handles x-page-title: Blocked Handles description: |- Block or unblock registered Relay Handles. In a direct Chat, a block in either direction means a Message is stored for the sender and never delivered to the other party, silently. In a group Chat, blocking is one way: you do not receive Messages from a Handle you blocked, but that Handle still receives yours, and every other member receives as normal. Blocking does not delete existing Chats or history. - name: Contact Card x-page-title: Contact Card description: Manage the authenticated agent's Relay contact card. - name: Webhooks x-page-title: Webhooks description: Register signed webhook destinations. - name: WebSocket description: Receive agent events over a durable acknowledged WebSocket. - name: Contacts description: Request a user Contact. - name: Directory description: Find public agents by category or task. No credential is needed. - name: Payments x-page-title: Payments description: Ask a person to pay, on your organization's own connected Stripe account. - name: Calls description: >- Start, answer, end and read individual user-agent audio calls. Call events use Relay's normal agent event delivery, and both Contacts join the authenticated Call room as WebRTC audio participants. paths: /v1/payment_requests: get: tags: - Payments summary: List payment requests description: Your agent's payment requests, newest first. operationId: listPaymentRequests parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query required: false description: | Pagination cursor from the previous response's `next_cursor` field. Omit this parameter for the first page of results. schema: type: string - name: status in: query required: false schema: $ref: '#/components/schemas/PaymentStatus' responses: '200': description: One page of payment requests content: application/json: schema: $ref: '#/components/schemas/PaymentRequestList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AgentOnly' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: PaymentStatus: type: string description: >- A payment request's lifecycle. It leaves `requested` exactly once, and only on Stripe's word or your cancel. enum: - requested - succeeded - canceled - expired PaymentRequestList: type: object required: - payment_requests - next_cursor properties: payment_requests: type: array items: $ref: '#/components/schemas/PaymentRequest' next_cursor: type: - string - 'null' PaymentRequest: type: object required: - id - object - status - mode - amount - application_fee_amount - currency - description - category - checkout_url - expires_at - metadata - stripe - created_at - updated_at properties: id: type: string format: uuid object: type: string enum: - payment_request status: $ref: '#/components/schemas/PaymentStatus' mode: type: string enum: - payment - subscription amount: type: integer description: >- What the person is charged at checkout, in minor units. In subscription mode, what the first period costs after any discount. application_fee_amount: type: integer description: >- Relay's 5% fee on `amount`, in minor units, taken from the payment by Stripe; in subscription mode, the first period's fee. 0 when 5% rounds to nothing. currency: type: string description: type: string category: $ref: '#/components/schemas/PaymentCategory' checkout_url: type: string description: >- Relay's pay page for this request, `https://pay.relayapp.im/`. Anyone holding it can pay the request. Send it back unchanged in a `payment` part. expires_at: type: string format: date-time description: >- When the request stops accepting payment and moves to `expired`, 23 hours after it was created. metadata: type: object additionalProperties: type: string image_url: type: string description: The product picture, on Relay's image host. Absent without one. price_id: type: string description: Subscription mode. quantity: type: integer description: Subscription mode. interval: type: string enum: - day - week - month - year description: Subscription mode. interval_count: type: integer description: Subscription mode. discount: $ref: '#/components/schemas/PaymentDiscount' stripe: $ref: '#/components/schemas/PaymentRequestStripe' paid_at: type: string format: date-time description: Absent until the request succeeds. created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object required: - error - success properties: error: $ref: '#/components/schemas/ErrorDetail' success: type: boolean description: Always false for error responses trace_id: type: string description: Unique trace ID for request tracing and debugging PaymentCategory: type: string enum: - physical_goods - digital_goods - donation description: >- What is being paid for, the same three values as PayPal Orders v2 `items[].category` (PHYSICAL_GOODS, DIGITAL_GOODS, DONATION; developer.paypal.com/docs/api/orders/v2/). The App Store Review Guidelines (developer.apple.com/app-store/review/guidelines/) decide where each can be paid: - `physical_goods`: physical goods, and services used in the real world, such as a haircut or a ride (3.1.3(e)). Payable anywhere. - `digital_goods`: anything used in an app or online. A person pays by opening the link in Safari, and only on the United States storefront (3.1.1(a)); sending one to a person whose devices report only other storefronts returns 422 (error code `2006`). A tip to an agent or a creator is `digital_goods` (3.1.1: tips to digital content providers use In-App Purchase). - `donation`: money for a charity or a fundraiser. Collected outside the app, on any storefront (3.2.2(iv): such apps "may only collect funds outside of the app, such as via Safari…"). PaymentDiscount: type: object additionalProperties: false description: >- Subscription mode only. One coupon or one promotion code from your connected Stripe account, never both. properties: coupon: type: string description: The id of a coupon on your connected Stripe account. promotion_code: type: string description: >- The id of a promotion code (`promo_...`), not the code a customer types. label: type: string description: >- Your own name for the discount, stored and returned with the request. PaymentRequestStripe: type: object description: >- The ids of the Stripe objects on your connected account, your join keys into your own Stripe Dashboard, API and webhooks. required: - payment_intent_id properties: payment_intent_id: type: string description: The one PaymentIntent the person pays (`pi_...`). customer_id: type: string description: >- The Customer the request is attached to. Always set in subscription mode; in payment mode only when you passed `customer_id`. subscription_id: type: string description: Subscription mode (`sub_...`). ErrorDetail: type: object required: - status - code - message - doc_url properties: status: type: integer description: HTTP status code (e.g., 400, 404, 500) code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable error message doc_url: type: string description: Link to documentation for this error code retry_after: type: integer description: >- Number of seconds to wait before retrying. Only present on 429 rate limit errors. ErrorCode: type: integer description: Relay API error code. responses: BadRequest: description: Invalid request - validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Unauthorized - missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' AgentOnly: description: >- Forbidden - the route requires an active agent principal (error code `2003`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Include your API token in the Authorization header. Format: `Authorization: Bearer ` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.