# `X402.PaymentRequired`
[🔗](https://github.com/cardotrejos/x402/blob/main/lib/x402/payment_required.ex#L1)

Encodes and decodes the x402 `PAYMENT-REQUIRED` header value.

The header value is Base64-encoded JSON. This module provides safe conversion
functions that return tagged tuples instead of raising.

# `decode`
*since 0.1.0* 

```elixir
@spec decode(String.t()) :: {:ok, map()} | {:error, decode_error()}
```

Decodes a Base64 `PAYMENT-REQUIRED` value to a map.

Returns `{:error, :payload_too_large}` when the encoded value exceeds 8 KB.
Returns `{:error, :invalid_base64}` when the value cannot be Base64-decoded.
Returns `{:error, :invalid_json}` when JSON cannot be decoded to a map.

## Examples

    iex> {:ok, encoded} = X402.PaymentRequired.encode(%{"scheme" => "exact"})
    iex> X402.PaymentRequired.decode(encoded)
    {:ok, %{"scheme" => "exact"}}

    iex> X402.PaymentRequired.decode("%%%")
    {:error, :invalid_base64}

# `encode`
*since 0.1.0* 

```elixir
@spec encode(map()) :: {:ok, String.t()} | {:error, encode_error()}
```

Encodes a payment requirement payload to a Base64 header value.

## Examples

    iex> {:ok, value} = X402.PaymentRequired.encode(%{"scheme" => "exact", "maxAmountRequired" => "10"})
    iex> {:ok, decoded} = X402.PaymentRequired.decode(value)
    iex> decoded["maxAmountRequired"]
    "10"

    iex> X402.PaymentRequired.encode(nil)
    {:error, :invalid_payload}

# `header_name`
*since 0.1.0* 

```elixir
@spec header_name() :: String.t()
```

Returns the canonical x402 header name.

## Examples

    iex> X402.PaymentRequired.header_name()
    "PAYMENT-REQUIRED"

# `decode_error`

```elixir
@type decode_error() :: :invalid_base64 | :invalid_json | :payload_too_large
```

# `encode_error`

```elixir
@type encode_error() :: :invalid_payload | :invalid_json
```

# `scheme`

```elixir
@type scheme() :: String.t()
```

---

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