---
title: "Create a signed payment request; anyone with its link can read it and check the agent's signature"
method: POST
path: "/pay-requests"
tags: ["pay-requests"]
---

# Create a signed payment request; anyone with its link can read it and check the agent's signature

`POST /pay-requests`

## Request

- Base URL: `https://api.catena.com/v1/agent-api`
- URL: `https://api.catena.com/v1/agent-api/pay-requests`
- Auth: HTTP bearer

## Request body

- object
  - `request` string, required: The compact JWS the agent signed with its registered key (ADR 0039): header alg ES256, typ payment-request+jwt and the key as jwk; claims jti, iat, amount, currency, description, payer and pay_to, and optionally exp (an hour to 30 days after iat; 7 days when absent)

## Response `200`

The same JWS was sent before: the request it made, unchanged

- object
  - `payRequest` object, required
    - `id` string, required
    - `status` string, required: open until Catena matches a deposit to it, then paid; canceled once the requester withdraws it; expired once expiresAt passes while open
    - `amount` object, required
      - `value` string, required
      - `currency` 'USD', required
    - `description` string, required
    - `payer` object, required: Who was asked: by email, or as an organization chosen by name in the console
      - `email` string, nullable, required
      - `name` string, nullable, required
    - `payTo` object[], required
      - `network` string, required
      - `asset` string, required
      - `address` string, required
    - `link` string, required: The public link: anyone with it can read the request and check the agent's signature, with no Catena credentials
    - `createdAt` string, date-time, required
    - `expiresAt` string, date-time, required: After this an open request reads expired, and a payment that arrives stays an ordinary deposit, unless it comes from a send linked to the request before then
    - `paidAt` string, date-time, nullable, required
    - `signed` object, nullable, required: Null for a request a member made in the console, which no agent signed
      - `request` string, required: The agent's compact JWS (typ payment-request+jwt), signed with its registered key
    - `viewedAt` string, date-time, nullable, required: When anyone first opened the request's public link
    - `paidTransactionId` string, nullable, required: The deposit Catena matched to the request, shown only to the requesting organization
    - `requester` object, required
      - `organization` object, required
        - `id` string, required
        - `name` string, required
      - `agent` object, nullable, required: The agent that made the request, or null for a member's
        - `id` string, required
        - `name` string, required
      - `member` object, nullable, required: The member who made the request in the console
        - `name` string, required
    - `payments` object[], required: The sends the caller's organization recorded as paying this request
      - `intentId` string, required
      - `status` string, required
      - `resolution` union, required: Exact terminal outcome, or null while the intent is nonterminal. Known values are completed, blocked, denied, expired, failed, and cancelled; clients must preserve future nonblank strings.
        - 'completed' | 'blocked' | 'denied' | 'expired' | 'failed' | 'cancelled'
        - string

## Other responses

- `201`: Request stored. Its link is public, and the payer email's organizations that accept payment requests see it among their incoming requests
- `400`: The JWS is malformed, does not verify, is not signed by the key that signed this call, signed more than five minutes from now, or a claim is out of range, such as an exp under an hour or over 30 days after iat
- `403`: Payment requests are not enabled for the organization, or the call was not signed with the agent's registered key
- `409`: Another request already used this jti, or the organization already has an open request to this payer
- `422`: The payer email reaches no organization that accepts payment requests, or a pay-to address is not the deposit address of an active account the agent can read
- `429`: The organization made 20 requests in the last 24 hours

---

[API](https://skmtc.dev/catena/apis/catena-agent-api.md) - [All operations](https://skmtc.dev/catena/apis/catena-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/catena/apis/catena-agent-api/revisions/9b72e32d21f1?raw)