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

# Payments Facilitator

> The Nevermined Payments Facilitator verifies and settles both x402 and MPP payments against the same Nevermined Payment Plans — smart accounts, programmable contracts, and credit metering.

The Nevermined Payments Facilitator is an **enforcement and settlement engine** for HTTP-native agent payments. It lets any API, agent, MCP tool, or protected resource get paid without running on-chain infrastructure — and it speaks **two sibling payment protocols that settle against the same Nevermined Payment Plans**:

* **[x402](/docs/development-guide/nevermined-x402)** — payment terms travel in a `payment-required` header and the payment is presented in `payment-signature`. Covers standard "pay-per-request" x402 and Nevermined's programmable extension (`nvm:erc4337` and `nvm:card-delegation` schemes, with smart accounts, session keys, and contract settlement).
* **[MPP (Merchant Payment Protocol)](/docs/products/payments-facilitator/mpp-seller)** — the same plan, credits, and delegation, negotiated with an RFC 7235 `WWW-Authenticate: Payment …` challenge and an `Authorization: Payment …` credential instead.

A request that costs 2 credits burns 2 whether it was paid over x402 or MPP: **one meter, one delegation budget, two wire protocols.**

<Note>
  For the complete technical specification of the x402 extension, see the [x402 Smart Accounts Extension Spec](/docs/specs/x402-smart-accounts). For the MPP seller integration, see [Accepting MPP payments](/docs/products/payments-facilitator/mpp-seller).
</Note>

The Facilitator sits in the payment flow — when a server receives a payment token, it delegates verification and settlement to the Facilitator rather than handling it directly. See [how the x402 flow works end to end](/docs/development-guide/nevermined-x402).

## Why use a Facilitator?

A facilitator is the third party that:

* verifies payment proofs
* simulates/enforces what is allowed (amount, plan, merchant/agent binding)
* executes settlement on-chain
* returns a canonical receipt (e.g., transaction hash)

This is particularly important for **programmable x402**, where settlement may be more than a single ERC-20 transfer (credits, subscriptions, policy-based settlement).

## Facilitator API

### Environments

| Environment    | URL                                          | Purpose                               |
| -------------- | -------------------------------------------- | ------------------------------------- |
| **Sandbox**    | `https://facilitator.sandbox.nevermined.app` | Testing and development with testnets |
| **Production** | `https://facilitator.live.nevermined.app`    | Live mainnet transactions             |

<Note>
  Use the sandbox environment for development and testing. Switch to production only when you're ready to process real payments.
</Note>

### Core Endpoints

Each protocol has its own verify/settle route pair. The plan, the credits, and the delegation underneath are identical — only the wire shape differs.

**x402** — verify then settle around your workload:

<CardGroup cols={2}>
  <Card title="Verify Endpoint" icon="shield-check">
    **POST** `/api/v1/x402/verify`

    Validates payment authorization, checks permissions, and simulates on-chain settlement before workload execution.
  </Card>

  <Card title="Settle Endpoint" icon="credit-card">
    **POST** `/api/v1/x402/settle`

    Executes on-chain settlement after workload completion and returns transaction receipt.
  </Card>
</CardGroup>

**MPP** — a seller mints a challenge, then verifies and settles the credential the buyer returns:

<CardGroup cols={3}>
  <Card title="Challenge Endpoint" icon="flag">
    **POST** `/api/v1/mpp/challenge`

    Mints the HMAC-bound `WWW-Authenticate: Payment` challenge to return with your `402`.
  </Card>

  <Card title="Verify Endpoint" icon="shield-check">
    **POST** `/api/v1/mpp/verify`

    Checks a returned credential without burning credits.
  </Card>

  <Card title="Settle Endpoint" icon="credit-card">
    **POST** `/api/v1/mpp/settle`

    Verifies **and** burns the credits, returning the `Payment-Receipt`.
  </Card>
</CardGroup>

Buyers mint their access token at `POST /api/v1/x402/permissions` (x402) or `POST /api/v1/mpp/permissions` (MPP). A token minted for one protocol is refused on the other's routes — see [protocol isolation](/docs/products/payments-facilitator/mpp-seller#protocol-isolation). Full MPP seller reference: [Accepting MPP payments](/docs/products/payments-facilitator/mpp-seller).

## How it works

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server as Resource Server (API/Agent)
    participant Facilitator as Nevermined Payments Facilitator
    participant Chain as Blockchain

    Client->>Server: Request
    Server-->>Client: 402 + payment-required header

    Client->>Client: Generate x402 token via SDK
    Client->>Server: Retry + payment-signature header

    Server->>Facilitator: /verify (simulate + validate)
    Facilitator->>Chain: Policy + balance checks
    Facilitator-->>Server: Verification OK

    Server->>Server: Execute workload

    Server->>Facilitator: /settle (execute settlement)
    Facilitator->>Chain: Execute contract settlement
    Facilitator-->>Server: Receipt + txHash

    Server-->>Client: Response + payment-response header
```

## Nevermined's programmable x402 extension

Standard x402 is often implemented as an "exact transfer" authorization (e.g., EIP-3009). Nevermined extends x402 to support:

* **Smart Accounts (ERC-4337)** and delegated **session keys**
* **Smart-contract settlement** (credits, subscriptions, PAYG, dynamic charging)
* **Policy enforcement** (merchant allowlists, spend caps, validity windows)

This keeps the HTTP handshake the same, but upgrades settlement from "transfer" to **programmable execution**.

## Facilitator responsibilities

### Verification

* x402 envelope structure/version
* signature authenticity
* session key validity + scoped permissions
* plan state + subscriber balance
* simulation of allowed on-chain actions (UserOps)

### Settlement

After the server completes its work, the facilitator can execute the settlement action permitted by the payment payload, such as:

* `order` (purchase/top-up)
* `redeem` / `burn` (consume credits)
* "exact" transfers (when using standard x402)

## Getting started

<CardGroup cols={2}>
  <Card title="Express.js Integration" icon="node-js" href="/docs/integrate/add-to-your-agent/express">
    One-line payment protection with Express middleware
  </Card>

  <Card title="How It Works" icon="gears" href="/docs/products/payments-facilitator/how-it-works">
    End-to-end flow (client + server) with x402 headers and facilitator calls
  </Card>

  <Card title="Accepting MPP payments" icon="handshake" href="/docs/products/payments-facilitator/mpp-seller">
    Advertise your plan-protected endpoint as MPP-payable, metered exactly like x402
  </Card>

  <Card title="Payment Models" icon="calculator" href="/docs/integrate/patterns/payment-models">
    Credits, subscriptions, and dynamic pricing using programmable settlement
  </Card>

  <Card title="x402 Protocol" icon="plug" href="/docs/development-guide/nevermined-x402">
    Integrate x402 into your API/agent
  </Card>

  <Card title="Google A2A" icon="sparkles" href="/docs/integrations/google-a2a">
    Use x402 with A2A + AP2-style payment intent messaging
  </Card>
</CardGroup>


## Related topics

- [How the Payments Facilitator Works](/docs/products/payments-facilitator/how-it-works.md)
- [Nevermined x402](/docs/development-guide/nevermined-x402.md)
- [API Providers](/docs/solutions/api-providers.md)
- [LangChain Integration](/docs/api-reference/python/langchain-module.md)
- [Payment Models](/docs/integrate/patterns/payment-models.md)