> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fd.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoints

> Prism Gateway API endpoint reference for payment preparation, merchant checkout, and UCP gateway.

Reference for each Prism Gateway API endpoint. See [Introduction](/prism/api-reference/introduction) for base URLs, authentication, and error handling.

All authenticated endpoints require the `X-API-Key` header. Request and response bodies are JSON.

***

## x402 Settlement

Facilitator endpoints for the x402 payment flow. The [server-side SDKs](/prism/sdk/overview) call these automatically. Use them directly for custom integrations.

### Get Payment Requirements

Generate x402 payment requirements for a resource. Returns the accepted payment methods, token amounts, and settlement addresses.

```
POST /api/v2/payment/requirements
```

**Request Body**

| Field | Type | Required | Description |
| - | - | - | - |
| `resourceUrl` | string | Yes | URL of the protected resource |
| `requestedAmount` | number | Yes | Amount to charge (in the resource's currency) |
| `description` | string | No | Human-readable description of the resource |
| `mimeType` | string | No | MIME type of the resource content |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://prism-gw.fd.xyz/api/v2/payment/requirements \
  -H "X-API-Key: your-project-identify-token" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceUrl": "https://api.example.com/premium/data",
    "requestedAmount": 0.50,
    "description": "Premium API access"
  }'
```

**Response** (`PaymentRequiredResponse`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "x402Version": 2,
  "resource": {
    "url": "https://api.example.com/premium/data",
    "description": "Premium API access"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "amount": "500000",
      "payTo": "0x1234...abcd",
      "maxTimeoutSeconds": 300,
      "asset": "0xUSDC...addr",
      "extra": null,
      "protocolVersion": 2
    }
  ],
  "protocolVersion": 2
}
```

The `accepts` array contains one entry per token/chain combination the merchant supports. Clients pick one and construct a signed authorization against it.

***

### Verify Payment

Verify a signed x402 payment authorization without settling it on-chain.

```
POST /api/v2/payment/verify
```

**Request Body** (`PaymentSubmissionRequest2`)

| Field | Type | Required | Description |
| - | - | - | - |
| `paymentPayload` | object | Yes | Signed payment authorization (see below) |
| `paymentRequirements` | object | Yes | The accepted payment requirement this authorization targets |

<Expandable title="paymentPayload fields">
  | Field | Type | Required | Description |
  | - | - | - | - |
  | `x402Version` | integer | Yes | Protocol version (2) |
  | `accepted` | object | Yes | The `accepts` entry the payer selected |
  | `payload` | object | Yes | Signed authorization data (scheme-specific) |
  | `resource` | object | No | Resource metadata |
  | `extensions` | object | No | Protocol extensions |
</Expandable>

<Expandable title="paymentRequirements fields">
  | Field | Type | Required | Description |
  | - | - | - | - |
  | `scheme` | string | Yes | Payment scheme (e.g. `"exact"`) |
  | `network` | string | Yes | Chain identifier (e.g. `"base"`) |
  | `amount` | string | Yes | Token amount in smallest unit |
  | `payTo` | string | Yes | Merchant settlement address |
  | `maxTimeoutSeconds` | integer | Yes | Max time before authorization expires |
  | `asset` | string | Yes | Token contract address |
</Expandable>

**Response** (`VerifyResponse2`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "isValid": true,
  "payer": "0xPayerAddress...1234"
}
```

| Field | Type | Description |
| - | - | - |
| `isValid` | boolean | Whether the authorization is valid |
| `payer` | string | Payer wallet address (if valid) |
| `invalidReason` | string | Reason for rejection (if invalid) |

***

### Settle Payment

Settle a verified payment on-chain. Executes the `transferWithAuthorization` (ERC-3009) call to move tokens from the payer to the merchant.

```
POST /api/v2/payment/settle
```

**Request Body** (`PaymentSubmissionRequest2`)

Same structure as [Verify Payment](#verify-payment).

**Response** (`SettleResponse`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "payer": "0xPayerAddress...1234",
  "transaction": "0xTransactionHash...abcd",
  "network": "base"
}
```

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether settlement succeeded |
| `payer` | string | Payer wallet address |
| `transaction` | string | On-chain transaction hash |
| `network` | string | Chain the settlement executed on |
| `errorReason` | string | Reason for failure (if unsuccessful) |

Returns `502 Bad Gateway` with a [ProblemDetails](/prism/api-reference/introduction#error-format) body if the on-chain transaction fails.

***

## Merchant

Endpoints for UCP and ACP merchants. The UCP flow has two calls: fetch the handlers declaration for your UCP version, and call Payment Requirements at checkout. ACP merchants use the same Payment Requirements call and fetch the declaration from `/api/v2/merchant/acp/handlers`, which needs the API key.

### Get Handlers

Returns the `xyz.fd.prism_payment` handler declaration for a UCP version. Put it in your storefront's UCP profile. Cache it. This route is public and needs no API key.

```
GET /ucp/{ucpVersion}/handlers
```

It returns the `2026-10-07` handler for UCP `2026-01-23`, `2026-04-08` and `2026-08-25`. See [Prism contract selection](/prism/integrations/ucp/supported-versions#prism-contract-selection).

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://prism-gw.fd.xyz/ucp/2026-08-25/handlers
```

An unsupported version returns `422 version_unsupported`.

The unversioned `GET /api/v2/merchant/ucp/handlers` stays as a legacy route for older plugins. The versioned `/api/v2/merchant/ucp/{ucpVersion}/handlers` form was removed. Use the route above.

**Response** (`UcpHandlersResponse`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "xyz.fd.prism_payment": [
    {
      "id": "xyz.fd.prism_payment",
      "version": "2026-10-07",
      "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
      "schema": "https://prism-gw.fd.xyz/ucp/schema.json",
      "available_instruments": [{ "type": "x402" }],
      "config": {}
    }
  ]
}
```

**Unsupported version** (`422`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{"title":"version_unsupported","detail":"Version 2099-01-01 is not supported. Enabled versions: 2026-01-23, 2026-04-08, 2026-08-25."}
```

***

### Payment Requirements

Convert a fiat amount into the raw x402 PaymentRequired object. Call it at checkout, when a buyer selects items. The response has no protocol wrapper and does not depend on the UCP version. Requires the API key.

```
POST /api/v2/merchant/payment-requirements
```

**Request Body**

| Field | Type | Required | Description |
| - | - | - | - |
| `amount` | string | Yes | Fiat amount (e.g. `"10.00"`) |
| `currency` | string | Yes | Fiat currency code (e.g. `"USD"`) |
| `resource` | object | Yes | Resource being purchased |
| `resource.url` | string | Yes | URL identifying the resource |
| `resource.description` | string | No | Human-readable description |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://prism-gw.fd.xyz/api/v2/merchant/payment-requirements   -H "X-API-Key: your-project-identify-token"   -H "Content-Type: application/json"   -d '{"amount":"10.00","currency":"USD","resource":{"url":"https://shop.example/checkout/1"}}'
```

**Response**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "x402Version": 2,
  "resource": { "url": "https://shop.example/checkout/1" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "payTo": "0xMerchant...addr",
      "maxTimeoutSeconds": 300,
      "asset": "0xUSDC...addr",
      "amount": "10000000"
    }
  ]
}
```

The response has one `accepts` entry per token and chain the merchant supports, with `amount` resolved from the fiat price. It may also include `promotions`.

Returns `404` if the merchant is not configured in Prism Console.

Build the UCP checkout entry from the handlers declaration for your UCP version and this object:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "xyz.fd.prism_payment": [
    { "id": "<declaration id>", "version": "<declaration version>", "config": { "x402Version": 2, "resource": {}, "accepts": [] } }
  ]
}
```

***

## Gateway

Public endpoints serving the UCP handler reference. No authentication required.

### Handler Schema

Returns the JSON schema for the `xyz.fd.prism_payment` handler. The handler config schema is the entry `schema`. The instrument schema is linked at `$defs["xyz.fd.prism_payment"].instrument`.

```
GET /ucp/schema.json
```

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://prism-gw.fd.xyz/ucp/schema.json
```

***

### Handler Specification

Returns the human-readable specification for the `xyz.fd.prism_payment` handler in Markdown format.

```
GET /ucp/prism.md
```

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://prism-gw.fd.xyz/ucp/prism.md
```

```
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.