POSTpartial

Issue a filing payment handle

Requires the filing owner’s OAuth authority, a confirmed filing, hosted acceptance, and a separately recorded exact-fee grant for an enrolled host. The secret is shown once. Replaying its issuance key returns handle_already_issued; a new key replaces an unused handle. A consumed handle continues its existing checkout.

/api/filings/{id}/payment-handlesgetFilingPaymentHandle

Authentication and authority

Use one listed account-session, scoped OAuth, or partner credential alternative. Account tokens retain the approving account’s authority. Cookie-authenticated writes require same-origin authorization. Alternatives are OR; schemes in one alternative are AND.

AccountOAuth

Account tokens authorize only their approving account and case scope. S256 PKCE is mandatory on the code flow. Explicit reacceptance is required after Rules/disclosure changes.

Parameters

NameLocationRequirementSchema
idpathRequired{"type":"string"}
Idempotency-KeyheaderRequired{"type":"string","minLength":8,"maxLength":200}

Responses

201

One-time capability.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ok": {
      "const": true
    },
    "data": {
      "$ref": "#/components/schemas/FilingPaymentHandle",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "filingId": {
          "type": "string"
        },
        "itemHandle": {
          "type": "string",
          "pattern": "^fph_[A-Za-z0-9_-]{43}$",
          "example": "fph_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "writeOnly": false,
          "description": "One-time capability. Show only to the enrolled host; never log or persist it."
        },
        "hostId": {
          "type": "string"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "amount": {
          "type": "integer",
          "minimum": 50
        },
        "currency": {
          "const": "usd"
        }
      },
      "required": [
        "filingId",
        "itemHandle",
        "hostId",
        "expiresAt",
        "amount",
        "currency"
      ]
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "ok",
    "data"
  ]
}
403

Current account payment authority required.

409

Canonical problem response: handle_already_issued or checkout_already_created.

Example response

Successful response

{
  "ok": true,
  "data": {
    "filingId": "filingId_test",
    "itemHandle": "fph_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "hostId": "hostId_test",
    "expiresAt": "2026-08-09T12:00:00.000Z",
    "amount": 50,
    "currency": "usd"
  }
}

Errors

Read the response status and stable error code. See errors and rate limits for recovery. Refresh the resource before resolving a state or digest conflict.

Idempotency and retries

  • For throttling, honor Retry-After when present. Back off on retryable server failures.
  • Send a unique Idempotency-Key. An exact retry returns the stored result; reusing the key with a different request fails.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.