openapi.yaml

openapi: 3.1.0
info:
  title: StellarGate
  description: |-
    Payment gateway API built on Stellar for accepting and managing payments in
    XLM and USDC.

    ## Versioning

    `/v1` is the canonical, versioned surface — use it for all new integrations.
    The same operations are also served **unprefixed** (`POST /payments`, …) for
    backward compatibility (issue #121); those paths are **deprecated** and every
    response on them carries, per RFC 8594 / RFC 8288:

    ```
    Deprecation: true
    Link: </v1/…>; rel="successor-version"
    ```

    The deprecated operations are documented below and marked `deprecated: true`
    so a generated client surfaces the move. Operational endpoints (`/health`,
    `/ready`, `/metrics`, `/dashboard`) are infrastructure rather than contract
    and are intentionally unversioned.

    Every response also carries an `x-request-id` header — echoed from the
    caller's or generated server-side — worth quoting in a support request.
  version: 0.1.0
  license:
    name: MIT
    url: https://github.com/StellarGateLabs/StellarGate/blob/main/LICENSE

servers:
  - url: http://localhost:3000
    description: Local development

paths:
  /:
    get:
      operationId: root
      summary: Service root
      description: >-
        Content-negotiated on `Accept`, not User-Agent: a browser (`Accept:
        text/html`) is redirected to the operator dashboard, and every other
        caller — `fetch()`, `curl`, the dashboard's own version lookup, an
        uptime check — gets the plain-text version string. This exists so a
        hosting platform's "open in browser" link lands somewhere useful
        instead of a bare line of text with no hint that a UI exists one path
        away.
      security: []
      responses:
        "200":
          description: Not a browser request (or no Accept header) — plain-text version string
          content:
            text/plain:
              schema:
                type: string
                example: StellarGate API v0.1.0
        "307":
          description: >-
            Browser request (`Accept` contains `text/html`) — temporary
            redirect to /dashboard
          headers:
            Location:
              schema:
                type: string
                example: /dashboard

  /health:
    get:
      operationId: health
      summary: Health check
      # Explicitly unauthenticated. Stating this is not redundant: without it a
      # reader cannot tell "no credential required" from "the spec forgot to
      # say", which is the ambiguity this whole block exists to remove.
      security: []
      responses:
        "200":
          description: Service is up
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /ready:
    get:
      operationId: ready
      summary: Readiness probe
      description: >-
        Distinct from /health: this is what an orchestrator's readiness probe
        should target, not /health, which returns 200 unconditionally as long
        as the process is up (#103). Returns 200 only when the database
        responds AND (if a Horizon gateway is configured) Horizon is reachable
        AND the payment-detection cursor has advanced recently. A pod that
        cannot detect on-chain payments should not receive traffic even though
        the process itself is alive.
      security: []
      responses:
        "200":
          description: Database reachable, and Horizon + cursor freshness checks pass (or no gateway is configured)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyResponse"
        "503":
          description: Not ready — the database is unreachable, Horizon is unreachable, or the detection cursor has stalled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyResponse"
              examples:
                database_unreachable:
                  summary: Database unreachable
                  value:
                    status: unavailable
                    reason: database unreachable
                cursor_stalled:
                  summary: Payment detection stalled
                  value:
                    status: unavailable
                    reason: >-
                      payment detection stalled: no successful poll or stream
                      event in 900s (limit 300s)

  /metrics:
    get:
      operationId: metrics
      summary: Prometheus-compatible metrics snapshot
      description: >-
        Text-exposition-format counters and gauges covering webhook delivery,
        authentication, and background task health. Currently unauthenticated
        — see issue #250 for the access-control decision tracked against that.
      security: []
      responses:
        "200":
          description: Metrics snapshot
          content:
            text/plain; version=0.0.4:
              schema:
                type: string

  /merchants:
    post:
      operationId: provisionMerchant
      summary: Provision a new merchant
      description: >-
        There is no self-service signup; minting a merchant and its first
        credential is an operator action gated by the X-Admin-Secret header.
        The response's `api_key` is shown exactly once — the server stores
        only a hash, so this is the only time the raw key is ever recoverable.
        An unset ADMIN_PROVISIONING_SECRET disables this route entirely
        (every request gets 401), rather than leaving it open.
      security:
        - adminSecret: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProvisionMerchantRequest"
      responses:
        "201":
          description: Merchant provisioned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProvisionMerchantResponse"
        "400":
          description: rate_limit_per_sec is not a positive integer, or the body has an unrecognised field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_rate_limit:
                  summary: Non-positive rate limit
                  value:
                    error: rate_limit_per_sec must be positive
                    code: invalid_rate_limit
        "401":
          $ref: "#/components/responses/AdminUnauthorized"

  /merchants/{id}/keys:
    post:
      operationId: issueApiKey
      summary: Issue an additional API key
      description: >-
        Rotation is issue-then-revoke, not replace-in-place: the new key is
        live immediately while the old one keeps working, so a merchant can
        deploy the new credential and never has a window with no valid key.
        The response's `api_key` is shown exactly once, the same as
        provisioning.
      security:
        - adminSecret: []
      parameters:
        - name: id
          in: path
          required: true
          description: Merchant ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueKeyRequest"
      responses:
        "201":
          description: Key issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueKeyResponse"
        "400":
          description: Label exceeds 100 characters (or 400 bytes), contains a control character, or the request body has an unrecognised field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_label:
                  summary: Label too long
                  value:
                    error: label must be at most 100 characters
                    code: invalid_label
        "401":
          $ref: "#/components/responses/AdminUnauthorized"
        "404":
          description: No merchant with that ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                merchant_not_found:
                  summary: Merchant not found
                  value:
                    error: merchant not found
                    code: merchant_not_found

    get:
      operationId: listApiKeys
      summary: List a merchant's API keys
      description: >-
        Metadata only — never the secret, which is unrecoverable by design.
        `prefix` is enough for an operator to identify which key to revoke.
        Keyset (cursor) paginated with the same conventions as `GET
        /payments`: revoked keys are kept forever as an audit trail, so a
        merchant that rotates regularly accumulates rows without bound, and
        this endpoint used to return every one of them in a single unbounded
        response (issue #262).
      security:
        - adminSecret: []
      parameters:
        - name: id
          in: path
          required: true
          description: Merchant ID
          schema:
            type: string
            format: uuid
        - name: active
          in: query
          schema:
            type: boolean
          description: >-
            `true` returns only usable keys, `false` only revoked ones.
            Omitted (the default) returns both, including the revoked audit
            trail.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Page size
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque cursor for keyset pagination (returned as next_cursor)
      responses:
        "200":
          description: A page of the merchant's keys
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListApiKeysResponse"
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_cursor:
                  summary: Invalid cursor
                  value:
                    error: invalid cursor
                    code: invalid_cursor
                invalid_limit:
                  summary: limit outside 1..=100
                  value:
                    error: "limit must be between 1 and 100 (got 5000)"
                    code: invalid_limit
        "401":
          $ref: "#/components/responses/AdminUnauthorized"
        "404":
          description: No merchant with that ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                merchant_not_found:
                  summary: Merchant not found
                  value:
                    error: merchant not found
                    code: merchant_not_found

  /merchants/{id}/keys/{key_id}:
    delete:
      operationId: revokeApiKey
      summary: Revoke an API key
      description: >-
        Refuses to revoke a merchant's last active key — this API has no
        self-service recovery, so that would turn a routine revocation into an
        incident. Issue a replacement first.
      security:
        - adminSecret: []
      parameters:
        - name: id
          in: path
          required: true
          description: Merchant ID
          schema:
            type: string
            format: uuid
        - name: key_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Key revoked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevokeApiKeyResponse"
        "400":
          description: This is the merchant's only active key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                last_active_key:
                  summary: Only active key
                  value:
                    error: >-
                      cannot revoke a merchant's only active key — issue a
                      replacement first
                    code: last_active_key
        "401":
          $ref: "#/components/responses/AdminUnauthorized"
        "404":
          description: No such merchant, or no active key with that ID for this merchant
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                merchant_not_found:
                  summary: Merchant not found
                  value:
                    error: merchant not found
                    code: merchant_not_found
                key_not_found:
                  summary: Key not found
                  value:
                    error: no active key with that id for this merchant
                    code: key_not_found

  /merchants/{id}/rate-limit:
    put:
      operationId: setMerchantRateLimit
      summary: Set or clear a merchant's per-second rate-limit override
      description: >-
        Sets (or clears) an individual per-merchant quota on the authenticated
        rate limiter, independent of the global `RATE_LIMIT_REQUESTS_PER_SEC`
        default. Passing `null` for `rate_limit_per_sec` removes the override
        and returns the merchant to the configured default. Admin only.
      security:
        - adminSecret: []
      parameters:
        - name: id
          in: path
          required: true
          description: Merchant ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRateLimitRequest"
      responses:
        "200":
          description: Rate limit updated (or cleared)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetRateLimitResponse"
        "400":
          description: rate_limit_per_sec is not a positive integer, or the request body has an unrecognised field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_rate_limit:
                  summary: Non-positive rate limit
                  value:
                    error: rate_limit_per_sec must be positive
                    code: invalid_rate_limit
        "401":
          $ref: "#/components/responses/AdminUnauthorized"
        "404":
          description: No merchant with that ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                merchant_not_found:
                  summary: Merchant not found
                  value:
                    error: merchant not found
                    code: merchant_not_found

  /payments:
    post:
      operationId: createPayment
      summary: Create a payment intent
      description: >-
        The merchant that owns the intent is taken from the bearer token, not
        from the request body — there is no way to create a payment on behalf
        of a different merchant. `CreatePaymentRequest` has no `merchant_id`
        property, and the server rejects any body containing one with `400
        unknown_field` rather than silently ignoring it.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePaymentRequest"
      responses:
        "201":
          description: Payment intent created
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "200":
          description: >-
            Idempotent replay — a prior request carrying the same
            `Idempotency-Key` (for this merchant) already created this intent,
            so the original is returned rather than a duplicate.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: >-
            The request carried an `Idempotency-Key` that another in-flight
            request for the same merchant is already creating a payment for,
            and that request had not committed yet. Transient: retry after
            the interval in `Retry-After`.
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                idempotency_conflict:
                  summary: Concurrent create raced on the same idempotency key
                  value:
                    error: concurrent request conflict, please retry
                    code: idempotency_conflict
        "429":
          description: >-
            Rate limit exceeded. The request fell into the `payments` bucket,
            whose quota is RATE_LIMIT_REQUESTS_PER_SEC × 1. See the Rate
            Limiting section of the README for the full bucket/quota model.
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/XRateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                rate_limit_exceeded:
                  summary: Rate limit exceeded
                  value:
                    error: rate limit exceeded
                    code: rate_limit_exceeded
        "503":
          description: >-
            The gateway account currently has no trustline for the requested
            asset, confirmed by the recurring trustline checker (see the
            Trustlines section of the README) — an intent minted now could
            only bounce on-chain. An asset that has never been checked yet,
            or whose last check failed to reach Horizon, is not rejected on
            that basis alone.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                trustline_missing:
                  summary: No trustline for this asset
                  value:
                    error: >-
                      the gateway account currently has no trustline for
                      USDC; payments in this asset cannot be received until
                      one is established
                    code: trustline_missing

    get:
      operationId: listPayments
      summary: List payments
      description: >-
        Scoped to the merchant that owns the API key. There is no parameter for
        selecting a different merchant.


        The parameter set is closed: a query parameter not listed below is
        rejected with `400 unknown_parameter` naming it, rather than ignored.
        A discarded filter would otherwise be returned as an unfiltered `200`
        page, so `?stauts=completed` listed every payment including pending
        ones.
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/PaymentStatus"
          description: Filter by status
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Page size
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
          description: >-
            Rows to skip (offset pagination, deprecated in favour of
            `cursor`). SQLite implements OFFSET by producing and discarding
            every skipped row, so cost grows with depth; values above 10000
            are rejected with `400 invalid_offset` rather than answered.
            Mutually exclusive with `cursor`: sending both is
            `400 conflicting_pagination`, decided on presence rather than
            value, so even `offset=0` alongside a cursor is rejected.
        - name: cursor
          in: query
          schema:
            type: string
          description: >-
            Opaque cursor for keyset pagination (returned as next_cursor).
            Selects keyset mode, whose response carries `payments`, `limit` and
            `next_cursor` but no `offset` or `total`. Mutually exclusive with
            `offset`: sending both is `400 conflicting_pagination`.
        - name: include_total
          in: query
          schema:
            type: boolean
            default: false
          description: >-
            Offset pagination only; has no effect with cursor set. `total`
            costs a full COUNT(*) scan over every matching row — SQLite has no
            cached row count — so it is computed only when this is `true`,
            and the `total` field is otherwise absent from the response
            entirely (not `null`). Keyset (cursor) pagination is the
            recommended approach and has never returned `total`.
      responses:
        "200":
          description: Paginated list of payments
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPaymentsResponse"
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_status:
                  summary: Invalid status filter
                  value:
                    error: "invalid status 'foo'; valid: pending, completed, underpaid, expired"
                    code: invalid_status
                invalid_cursor:
                  summary: Invalid cursor
                  value:
                    error: invalid cursor
                    code: invalid_cursor
                invalid_offset:
                  summary: Offset beyond the maximum
                  value:
                    error: "offset exceeds maximum of 10000; use cursor pagination instead (see the `cursor` parameter and `next_cursor` in the response)"
                    code: invalid_offset
                conflicting_pagination:
                  summary: Both cursor and offset supplied
                  value:
                    error: "cursor and offset are mutually exclusive; use cursor for keyset pagination"
                    code: conflicting_pagination
                invalid_limit:
                  summary: limit outside 1..=100
                  value:
                    error: "limit must be between 1 and 100 (got 5000)"
                    code: invalid_limit
                unknown_parameter:
                  summary: Unrecognised query parameter
                  value:
                    error: "invalid query string: Failed to deserialize query string: unknown field `stauts`, expected one of `status`, `limit`, `offset`, `cursor`, `include_total`"
                    code: unknown_parameter
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/payments/webhooks:
    get:
      operationId: listMerchantWebhooks
      summary: Dead-letter view — all failed deliveries across a merchant's payments
      description: >-
        Returns webhook deliveries across **all** of the authenticated
        merchant's payments, defaulting to `status=failed`. This is the
        endpoint to reach for when a merchant says they are missing events,
        because that question arrives without a payment id —
        `GET /v1/payments/{id}/webhooks` can only answer it if you already
        know where to look.


        The parameter set is closed: an unrecognised query parameter is
        rejected with `400 unknown_parameter`. This matters most here where
        `status` defaults to `failed`: a typo'd filter would otherwise return
        the full dead-letter list and look entirely plausible.
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, delivered, failed]
            default: failed
          description: Filter deliveries by status. Defaults to failed.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Page size
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque cursor for keyset pagination (returned as next_cursor)
      responses:
        "200":
          description: A page of the merchant's webhook deliveries
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListMerchantDeliveriesResponse"
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_status:
                  summary: Invalid status filter
                  value:
                    error: "invalid delivery status 'foo'; valid: pending, delivered, failed"
                    code: invalid_status
                invalid_cursor:
                  summary: Invalid cursor
                  value:
                    error: invalid cursor
                    code: invalid_cursor
                invalid_limit:
                  summary: limit outside 1..=100
                  value:
                    error: "limit must be between 1 and 100 (got 5000)"
                    code: invalid_limit
                unknown_parameter:
                  summary: Unrecognised query parameter
                  value:
                    error: "invalid query string: Failed to deserialize query string: unknown field `staus`, expected one of `status`, `limit`, `cursor`"
                    code: unknown_parameter
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/payments/webhooks/redeliver:
    post:
      operationId: redeliverWebhooksBulk
      summary: Bulk-requeue failed webhook deliveries for retry
      description: >-
        Requeues failed deliveries so the background redrive worker retries
        them. Omit `delivery_ids` (or send an empty body) to requeue every
        failed delivery for this merchant; supply a list to requeue specific
        ones (max 100 per request).


        **This endpoint sends nothing itself.** It resets matching rows to
        `pending` with `attempts = 0` and hands them to the redrive worker,
        whose `WEBHOOK_REDRIVE_CONCURRENCY` and exponential backoff already
        bound the outbound rate. Requeueing thousands of deliveries therefore
        costs one `UPDATE` and cannot stampede a receiver that has only just
        come back up.


        Requeueing also acknowledges the deliveries, returning them to ordinary
        retention.
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RedeliverBulkRequest"
      responses:
        "200":
          description: Deliveries requeued for the redrive worker
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RedeliverBulkResponse"
        "400":
          description: More than 100 delivery_ids supplied, or the body has an unrecognised field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                too_many_delivery_ids:
                  summary: Delivery id list exceeds the cap
                  value:
                    error: "at most 100 delivery_ids per request; omit the field to requeue every failed delivery"
                    code: too_many_delivery_ids
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/payments/{id}:
    get:
      operationId: getPayment
      summary: Get a payment by ID
      description: >-
        Authentication is optional here and changes what comes back, so this is
        the one operation whose security requirement is genuinely a choice
        rather than a gate. It stays reachable without a credential so a
        checkout page can poll it directly.


        **No credential** returns a minimal public projection — `id`, `status`
        and `expires_at`. Enough to answer "has this been paid yet", and
        nothing else. It deliberately omits `merchant_id`, every amount and
        `tx_hash`: payment ids travel through logs, referrers and browser
        history, so anything on this response should be treated as effectively
        public.


        **The owning merchant's key** returns the full record.


        **Another merchant's key** returns `404`, the same answer an unknown id
        gets. A `403` would confirm the payment exists and belongs to someone
        else.


        **An invalid or revoked key** returns `401` rather than silently
        falling back to the public view, so a typo'd credential says so instead
        of leaving the caller wondering why fields are missing.
      security:
        # An empty requirement alongside the scheme is how OpenAPI expresses
        # "auth optional, but it changes the response". Flattening this to a
        # single requirement would misdocument the endpoint most likely to be
        # integrated against.
        - {}              # anonymous  -> PublicPaymentView
        - bearerAuth: []  # owner      -> Payment
      parameters:
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          description: >-
            Payment found. The schema depends on the credential: the full
            Payment for the owning merchant, PublicPaymentView for an
            anonymous caller.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Payment"
                  - $ref: "#/components/schemas/PublicPaymentView"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: >-
            No such payment, or it belongs to another merchant — the two are
            deliberately indistinguishable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/payments/{id}/webhooks:
    get:
      operationId: listWebhookDeliveries
      summary: List webhook deliveries for a payment
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, delivered, failed]
          description: Filter deliveries by status
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Page size
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque cursor for keyset pagination (returned as next_cursor)
      responses:
        "200":
          description: Webhook delivery history
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListWebhookDeliveriesResponse"
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid_cursor:
                  summary: Invalid cursor
                  value:
                    error: invalid cursor
                    code: invalid_cursor
                invalid_limit:
                  summary: limit outside 1..=100
                  value:
                    error: "limit must be between 1 and 100 (got 5000)"
                    code: invalid_limit
                unknown_parameter:
                  summary: Unrecognised query parameter
                  value:
                    error: "invalid query string: Failed to deserialize query string: unknown field `staus`, expected one of `status`, `limit`, `cursor`"
                    code: unknown_parameter
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/payments/{id}/webhooks/{delivery_id}/redeliver:
    post:
      operationId: redeliverWebhook
      summary: Re-attempt a webhook delivery
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PaymentId"
        - $ref: "#/components/parameters/DeliveryId"
      responses:
        "200":
          description: Redelivery succeeded
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/WebhookBadGateway"

  # ---------------------------------------------------------------------------
  # Deprecated unprefixed mount. These are aliases of the /v1 operations above,
  # kept served for backward compatibility (issue #121). Every response carries
  # `Deprecation` and `Link: rel="successor-version"` headers. New integrations
  # must use /v1.
  # ---------------------------------------------------------------------------

  /payments:
    post:
      operationId: createPaymentLegacy
      summary: Create a payment intent (deprecated)
      description: Deprecated alias of `POST /v1/payments`.
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePaymentRequest"
      responses:
        "201":
          description: Payment intent created
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "200":
          description: Idempotent replay — see `POST /v1/payments`.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "400":
          $ref: "#/components/responses/DeprecatedValidationError"
        "429":
          $ref: "#/components/responses/DeprecatedRateLimited"

    get:
      operationId: listPaymentsLegacy
      summary: List payments (deprecated)
      description: Deprecated alias of `GET /v1/payments`.
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/StatusFilter"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/OffsetParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          description: Paginated list of payments
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListPaymentsResponse"
        "400":
          $ref: "#/components/responses/DeprecatedValidationError"

  /payments/webhooks:
    get:
      operationId: listMerchantWebhooksLegacy
      summary: Dead-letter view — all failed deliveries (deprecated)
      description: Deprecated alias of `GET /v1/payments/webhooks`.
      deprecated: true
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, delivered, failed]
            default: failed
          description: Filter deliveries by status
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          description: A page of the merchant's webhook deliveries
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListMerchantDeliveriesResponse"
        "400":
          $ref: "#/components/responses/DeprecatedValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /payments/webhooks/redeliver:
    post:
      operationId: redeliverWebhooksBulkLegacy
      summary: Bulk-requeue failed webhook deliveries (deprecated)
      description: Deprecated alias of `POST /v1/payments/webhooks/redeliver`.
      deprecated: true
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RedeliverBulkRequest"
      responses:
        "200":
          description: Deliveries requeued
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RedeliverBulkResponse"
        "400":
          $ref: "#/components/responses/DeprecatedValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /payments/{id}:
    get:
      operationId: getPaymentLegacy
      summary: Get a payment by ID (deprecated)
      description: Deprecated alias of `GET /v1/payments/{id}`.
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          description: Payment found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "404":
          $ref: "#/components/responses/DeprecatedNotFound"

  /payments/{id}/webhooks:
    get:
      operationId: listWebhookDeliveriesLegacy
      summary: List webhook deliveries for a payment (deprecated)
      description: Deprecated alias of `GET /v1/payments/{id}/webhooks`.
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          description: Webhook delivery history
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListWebhookDeliveriesResponse"
        "404":
          $ref: "#/components/responses/DeprecatedNotFound"

  /payments/{id}/webhooks/{delivery_id}/redeliver:
    post:
      operationId: redeliverWebhookLegacy
      summary: Re-attempt a webhook delivery (deprecated)
      description: >-
        Deprecated alias of
        `POST /v1/payments/{id}/webhooks/{delivery_id}/redeliver`.
      deprecated: true
      parameters:
        - $ref: "#/components/parameters/PaymentId"
        - $ref: "#/components/parameters/DeliveryId"
      responses:
        "200":
          description: Redelivery succeeded
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestId"
            Deprecation:
              $ref: "#/components/headers/Deprecation"
            Link:
              $ref: "#/components/headers/Link"
        "404":
          $ref: "#/components/responses/DeprecatedNotFound"
        "502":
          $ref: "#/components/responses/DeprecatedWebhookBadGateway"

components:
  headers:
    XRequestId:
      description: >-
        Correlation id for the request, echoed from the caller's `x-request-id`
        or generated server-side as a UUID. Present on every response.
      schema:
        type: string
        format: uuid
    Deprecation:
      description: >-
        Present on responses from the deprecated unprefixed mount (RFC 8594).
        Always the literal string `true`.
      schema:
        type: string
        enum: ["true"]
    Link:
      description: >-
        Present on responses from the deprecated unprefixed mount (RFC 8288).
        Points at the canonical `/v1` successor of the requested path.
      schema:
        type: string
      example: '</v1/payments>; rel="successor-version"'
    RetryAfter:
      description: >-
        Seconds to wait before retrying, in delta-seconds per RFC 9110. Sent on
        a `429`; derived from the limiter's own state and never less than 1.
      schema:
        type: integer
        minimum: 1
    XRateLimitLimit:
      description: >-
        The per-second request quota for the bucket this request fell into.
        Present on every response, throttled or not.
      schema:
        type: integer
    XRateLimitRemaining:
      description: >-
        Requests remaining before the bucket throttles. Present on every
        response.
      schema:
        type: integer
        minimum: 0
    XRateLimitReset:
      description: >-
        Seconds until the bucket refills to its full quota. Present on every
        response.
      schema:
        type: integer
        minimum: 0

  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional client-chosen key that makes creating a payment safe to retry
        after a network blip. Scoped per merchant; an empty value is treated as
        absent. Reusing a key returns the original intent with `200 OK` instead
        of minting a duplicate.
      schema:
        type: string
    PaymentId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    DeliveryId:
      name: delivery_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    StatusFilter:
      name: status
      in: query
      required: false
      description: Filter by status
      schema:
        $ref: "#/components/schemas/PaymentStatus"
    LimitParam:
      name: limit
      in: query
      required: false
      description: Page size
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    OffsetParam:
      name: offset
      in: query
      required: false
      description: Rows to skip (offset pagination)
      schema:
        type: integer
        minimum: 0
        default: 0
    CursorParam:
      name: cursor
      in: query
      required: false
      description: Opaque cursor for keyset pagination (returned as next_cursor)
      schema:
        type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Merchant API key, issued by POST /merchants or POST
        /merchants/{id}/keys and sent as `Authorization: Bearer <key>`. The
        merchant is derived from the key — it is never taken from a request
        body or query parameter — so a key scopes every payment operation to
        exactly one tenant.
    adminSecret:
      type: apiKey
      in: header
      name: X-Admin-Secret
      description: >-
        Operator secret from ADMIN_PROVISIONING_SECRET. Guards merchant
        provisioning and the API-key lifecycle routes only; it is never
        accepted on a payment route. An unset ADMIN_PROVISIONING_SECRET
        disables those routes entirely rather than leaving them open.

  responses:
    Unauthorized:
      description: >-
        Missing, malformed, invalid, or revoked credential. Uses the standard
        error envelope with code `unauthorized`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing_key:
              summary: No Authorization header
              value:
                error: missing or invalid Authorization header
                code: unauthorized
            invalid_key:
              summary: Key did not match any merchant
              value:
                error: invalid API key
                code: unauthorized
    NotFound:
      description: Resource not found
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            payment_not_found:
              summary: Payment not found
              value:
                error: payment not found
                code: payment_not_found
            delivery_not_found:
              summary: Delivery not found (redelivery only)
              value:
                error: delivery not found
                code: delivery_not_found
    WebhookBadGateway:
      description: Webhook endpoint returned an error
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            webhook_delivery_failed:
              summary: Redelivery failed
              value:
                error: webhook delivery failed
                code: webhook_delivery_failed

    # Deprecated-mount twins: identical bodies, plus the `Deprecation` and `Link`
    # headers that `mark_deprecated` stamps on every unprefixed response.
    DeprecatedValidationError:
      description: Validation error
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
        Deprecation:
          $ref: "#/components/headers/Deprecation"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    DeprecatedNotFound:
      description: Resource not found
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
        Deprecation:
          $ref: "#/components/headers/Deprecation"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    DeprecatedRateLimited:
      description: Rate limit exceeded
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
        Deprecation:
          $ref: "#/components/headers/Deprecation"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    DeprecatedWebhookBadGateway:
      description: Webhook endpoint returned an error
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
        Deprecation:
          $ref: "#/components/headers/Deprecation"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    MethodNotAllowed:
      description: >-
        The path exists, but not for this HTTP method. Generated by axum's
        router itself rather than a handler; rewritten into the standard
        error envelope by `json_error_envelope_middleware` (issue #256).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            method_not_allowed:
              summary: Unsupported method for this path
              value:
                error: method not allowed
                code: method_not_allowed

    PayloadTooLarge:
      description: >-
        Request body exceeds the configured maximum (`MAX_BODY_BYTES`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            payload_too_large:
              summary: Body exceeds MAX_BODY_BYTES
              value:
                error: request body exceeds the maximum allowed size
                code: payload_too_large

    RequestTimeout:
      description: >-
        The request did not complete within `REQUEST_TIMEOUT_SECS`.
        Generated by `TimeoutLayer` rather than a handler; rewritten into the
        standard error envelope by `json_error_envelope_middleware` (issue
        #256).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            request_timeout:
              summary: Handler exceeded REQUEST_TIMEOUT_SECS
              value:
                error: request timed out
                code: request_timeout

    AdminUnauthorized:
      description: >-
        Missing, wrong, or unconfigured X-Admin-Secret. Uses the standard
        error envelope with code `unauthorized`. An unset
        ADMIN_PROVISIONING_SECRET produces this on every request rather than
        leaving the route open.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing_or_invalid_admin_secret:
              summary: Missing or invalid X-Admin-Secret
              value:
                error: missing or invalid admin secret
                code: unauthorized

  schemas:
    HealthResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          example: ok

    ReadyResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [ok, unavailable]
        reason:
          type: string
          description: Present only when status is unavailable
          example: database unreachable

    ProvisionMerchantRequest:
      type: object
      additionalProperties: false
      properties:
        rate_limit_per_sec:
          type: ["integer", "null"]
          description: >-
            Optional per-merchant rate-limit override, in requests per second.
            Omit to leave the merchant on the global RATE_LIMIT_REQUESTS_PER_SEC
            default. Must be a positive integer.
          example: 50

    ProvisionMerchantResponse:
      type: object
      required: [merchant_id, api_key, key_id]
      properties:
        merchant_id:
          type: string
          format: uuid
        api_key:
          type: string
          example: sg_1a2b3c4d5e6f...
          description: >-
            Shown exactly once. The server persists only a hash, so this value
            cannot be retrieved again through any endpoint — store it
            immediately. If it's lost, issue a new key
            (POST /merchants/{id}/keys) and revoke this one.
        key_id:
          type: string
          format: uuid
          description: ID of the API key created alongside the merchant
        rate_limit_per_sec:
          type: ["integer", "null"]
          description: >-
            Per-merchant rate-limit override set at provisioning time, in
            requests per second. Null when the merchant uses the global
            default (RATE_LIMIT_REQUESTS_PER_SEC).

    IssueKeyRequest:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          maxLength: 100
          description: Optional free-text label to help identify this key later
          example: rotation-2026-08

    IssueKeyResponse:
      type: object
      required: [key_id, api_key]
      properties:
        key_id:
          type: string
          format: uuid
        api_key:
          type: string
          example: sg_9f8e7d6c5b4a...
          description: >-
            Shown exactly once, the same as POST /merchants — the server
            persists only a hash, so this value cannot be retrieved again.
        prefix:
          type: string
          description: First characters of the key, safe to display in a list
          example: sg_9f8e7d6c
        label:
          type: [string, "null"]

    ApiKeySummary:
      type: object
      required: [key_id, prefix, created_at, active]
      description: A key as exposed to an operator. Never carries the secret.
      properties:
        key_id:
          type: string
          format: uuid
        prefix:
          type: string
          example: sg_9f8e7d6c
        label:
          type: [string, "null"]
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: [string, "null"]
          format: date-time
        revoked_at:
          type: [string, "null"]
          format: date-time
        active:
          type: boolean
          description: true when revoked_at is null

    ListApiKeysResponse:
      type: object
      required: [merchant_id, keys, limit]
      properties:
        merchant_id:
          type: string
          format: uuid
        keys:
          type: array
          items:
            $ref: "#/components/schemas/ApiKeySummary"
        limit:
          type: integer
        next_cursor:
          type: [string, "null"]
          description: Pass as cursor on the next request to get the following page

    RevokeApiKeyResponse:
      type: object
      required: [key_id, revoked]
      properties:
        key_id:
          type: string
          format: uuid
        revoked:
          type: boolean
          example: true

    PaymentStatus:
      type: string
      enum: [pending, completed, underpaid, expired]

    Payment:
      type: object
      required:
        - id
        - merchant_id
        - destination_address
        - memo
        - amount
        - asset
        - status
        - created_at
        - updated_at
        - expires_at
      properties:
        id:
          type: string
          format: uuid
        merchant_id:
          type: string
          example: my-shop
        destination_address:
          type: string
          description: Stellar public key the user must pay to
          example: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
        memo:
          type: string
          description: 8-character memo the user must include in their transaction
          example: A1B2C3D4
        amount:
          type: string
          description: Requested amount as a decimal string
          example: "10.00"
        asset:
          type: string
          enum: [XLM, USDC]
        status:
          $ref: "#/components/schemas/PaymentStatus"
        tx_hash:
          type: [string, "null"]
          description: On-chain transaction hash once settled
        paid_amount:
          type: [string, "null"]
          description: Cumulative amount received
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    PublicPaymentView:
      type: object
      description: >-
        What GET /payments/{id} returns to a caller with no credential. Enough
        to poll for completion, with nothing that identifies the merchant or
        the sum involved.
      required: [id, status, expires_at]
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/PaymentStatus"
        expires_at:
          type: string
          format: date-time

    CreatePaymentRequest:
      type: object
      required: [amount]
      # The server rejects any field not listed here with 400 unknown_field.
      # `merchant_id` used to be documented but was never read — the merchant is
      # taken from the API key — so sending it now fails loudly instead of
      # silently binding the intent to whichever merchant owns the key.
      additionalProperties: false
      properties:
        amount:
          type: string
          description: >-
            Positive decimal, up to 7 decimal places. May also be bounded by
            the deployment's MAX_PAYMENT_AMOUNT / MIN_PAYMENT_AMOUNT
            configuration (optionally per asset); exceeding a configured
            bound returns 400 amount_out_of_range naming the limit.
          example: "10.00"
        asset:
          type: string
          enum: [XLM, USDC]
          default: XLM
          description: >-
            Defaults to XLM when omitted. Because the default applies silently,
            a misspelled field name (e.g. `assset`) would otherwise create an
            XLM intent; it is rejected as unknown_field instead.
        webhook_url:
          type: string
          format: uri
          description: Webhook endpoint URL. Must be HTTPS in production.
          example: https://yourapp.com/webhooks/stellar

    ListPaymentsResponse:
      type: object
      description: >-
        One shape per pagination mode, chosen by the request. Keyset mode
        (`cursor` set) returns `payments`, `limit` and `next_cursor`. Offset
        mode (`cursor` absent) returns those plus `offset`, and `total` when
        `include_total=true`. The modes cannot be combined: `cursor` together
        with `offset` is `400 conflicting_pagination`.
      required: [payments, limit]
      properties:
        payments:
          type: array
          items:
            $ref: "#/components/schemas/Payment"
        total:
          type: integer
          description: >-
            Total matching rows. Offset pagination only, and only present when
            the request set `include_total=true` — computing it is a full
            `COUNT(*)` scan, so it is opt-in rather than sent on every
            request. Omitted from the response (not `null`) when not
            requested.
        limit:
          type: integer
        offset:
          type: integer
          description: >-
            Rows skipped. Offset pagination only; absent in keyset (cursor)
            mode.
        next_cursor:
          type: [string, "null"]
          description: Pass as cursor on the next request to get the following page

    WebhookDelivery:
      type: object
      required: [id, url, event, status, attempts, manual_attempts, created_at]
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        event:
          type: string
          description: >-
            The event this delivery carries. Redelivery reuses it as the
            X-StellarGate-Event header, so it always matches the payload.
          example: payment.underpaid
        status:
          type: string
          enum: [pending, delivered, failed]
        attempts:
          type: integer
          description: >-
            Automatic delivery attempts (inline dispatch + background redrive).
            Capped by WEBHOOK_REDRIVE_MAX_ATTEMPTS.
        manual_attempts:
          type: integer
          description: >-
            Merchant-initiated redeliveries via POST .../redeliver. Does not
            consume the automatic redrive budget and does not refresh
            last_attempt / backoff.
        last_attempt:
          type: [string, "null"]
          format: date-time
        acknowledged_at:
          type: [string, "null"]
          format: date-time
          description: >-
            Set when the delivery is requeued via POST .../redeliver or
            POST /v1/payments/webhooks/redeliver. A non-null value means
            somebody has acted on this failure, and the row returns to
            ordinary retention.
        created_at:
          type: string
          format: date-time

    ListWebhookDeliveriesResponse:
      type: object
      required: [payment_id, deliveries, limit]
      properties:
        payment_id:
          type: string
          format: uuid
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDelivery"
        limit:
          type: integer
          description: Page size applied to this response
        next_cursor:
          type: [string, "null"]
          description: Pass as cursor on the next request to get the following page

    SetRateLimitRequest:
      type: object
      additionalProperties: false
      properties:
        rate_limit_per_sec:
          type: ["integer", "null"]
          description: >-
            Per-second request quota for this merchant on the authenticated
            rate limiter. Pass null (or omit) to remove the override and
            return the merchant to the global default.
          example: 50

    SetRateLimitResponse:
      type: object
      required: [merchant_id]
      properties:
        merchant_id:
          type: string
          format: uuid
        rate_limit_per_sec:
          type: ["integer", "null"]
          description: The new effective override, or null if the override was cleared.

    RedeliverBulkRequest:
      type: object
      additionalProperties: false
      properties:
        delivery_ids:
          type: array
          maxItems: 100
          items:
            type: string
            format: uuid
          description: >-
            Specific delivery IDs to requeue. Omit the field (or send an
            empty list) to requeue every failed delivery this merchant has.
            Maximum 100 per request.

    RedeliverBulkResponse:
      type: object
      required: [requeued, detail]
      properties:
        requeued:
          type: integer
          description: Number of delivery rows reset to pending for the redrive worker.
        detail:
          type: string
          description: Human-readable note explaining what happens next.
          example: >-
            requeued deliveries are retried by the background redrive worker,
            subject to its concurrency limit and backoff

    ListMerchantDeliveriesResponse:
      type: object
      required: [deliveries, status, limit]
      description: >-
        Dead-letter view: all webhook deliveries for the authenticated
        merchant, across all of their payments. Defaults to failed deliveries.
      properties:
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDelivery"
        status:
          type: string
          enum: [pending, delivered, failed]
          description: The status filter that was applied
        limit:
          type: integer
          description: Page size applied to this response
        next_cursor:
          type: [string, "null"]
          description: Pass as cursor on the next request to get the following page

    ErrorResponse:
      type: object
      description: Standard error envelope for public API failures.
      required: [error, code]
      example:
        error: The provided amount is invalid
        code: invalid_amount
      properties:
        error:
          type: string
          description: Human-readable explanation of the failure.
          example: The provided amount is invalid
        code:
          type: string
          description: >-
            Stable machine-readable error code for programmatic handling. Public
            values currently include unauthorized, internal_error,
            invalid_request, unknown_field, unsupported_media_type,
            payload_too_large, unsupported_asset, invalid_amount,
            amount_out_of_range, invalid_webhook_url, invalid_status,
            invalid_cursor, invalid_limit, invalid_offset,
            conflicting_pagination, payment_not_found,
            delivery_not_found, rate_limit_exceeded, not_found, webhook_target_blocked,
            webhook_delivery_failed, idempotency_conflict, merchant_not_found,
            invalid_label, last_active_key, trustline_missing, and
            key_not_found.
          example: invalid_amount