# `X402.PaymentRequirements`
[🔗](https://github.com/cardotrejos/x402/blob/v0.9.0/lib/x402/payment_requirements.ex#L1)

Validation and matching helpers for x402 v2 payment requirements.

A client's `PaymentPayload.accepted` value must preserve every core field
advertised by the resource server. Server-declared `extra` values are matched
as a recursive subset so clients may append scheme-specific metadata without
changing the server's payment terms.

# `validation_error`

```elixir
@type validation_error() ::
  {:missing_fields, [String.t()]} | {:invalid_fields, [String.t()]}
```

# `extensions_match?`
*since 0.4.0* 

```elixir
@spec extensions_match?(term(), term()) :: boolean()
```

Returns whether client extension echoes preserve advertised extension values.

Omitting extensions is accepted for compatibility with the reference SDK.
When the client echoes an advertised extension, every server-provided value
must be retained.

## Examples

    iex> advertised = %{"example" => %{"info" => %{"required" => true}}}
    iex> echoed = %{"example" => %{"info" => %{"required" => true, "client" => "value"}}}
    iex> X402.PaymentRequirements.extensions_match?(advertised, echoed)
    true

# `match?`
*since 0.4.0* 

```elixir
@spec match?(term(), term()) :: boolean()
```

Returns whether a client-selected requirement preserves the server requirement.

Core fields must be equal. The client may add fields under `extra`, but it
cannot remove or change values advertised by the server.

## Examples

    iex> required = %{"scheme" => "exact", "extra" => %{"name" => "USDC"}}
    iex> accepted = %{"scheme" => "exact", "extra" => %{"name" => "USDC", "version" => "2"}}
    iex> X402.PaymentRequirements.match?(required, accepted)
    true

    iex> required = %{"scheme" => "exact", "extra" => %{"name" => "USDC"}}
    iex> X402.PaymentRequirements.match?(required, %{"scheme" => "exact", "extra" => %{}})
    false

# `validate`
*since 0.4.0* 

```elixir
@spec validate(term()) ::
  :ok | {:error, validation_error() | :invalid_payment_requirements}
```

Validates the required x402 v2 `PaymentRequirements` fields.

## Examples

    iex> requirements = %{
    ...>   "scheme" => "exact",
    ...>   "network" => "eip155:84532",
    ...>   "amount" => "10000",
    ...>   "asset" => "0xasset",
    ...>   "payTo" => "0xreceiver",
    ...>   "maxTimeoutSeconds" => 60,
    ...>   "extra" => %{}
    ...> }
    iex> X402.PaymentRequirements.validate(requirements)
    :ok

    iex> X402.PaymentRequirements.validate(%{})
    {:error, {:missing_fields, ["amount", "asset", "extra", "maxTimeoutSeconds", "network", "payTo", "scheme"]}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*