Behaviour and adapter helpers for payment identifier idempotency caches.

Cache adapters are configured as {module, cache} tuples where module implements this behaviour and cache is adapter-specific runtime state (for example, a pid, a registered process name, or a connection handle).

X402.Plug.PaymentGate routes all replay-protection calls through this behaviour. The claim that prevents a payment proof from being settled twice is put_new/3, so every adapter must implement it with atomic first-writer-wins semantics: when several processes race to claim the same payment identifier, exactly one call may return :ok and all others must return {:error, :already_exists}.

Clustered deployments: double-execution hazard

Writing a distributed adapter

put_new/3 must combine "insert if absent" and "expire after TTL" in a single atomic operation of the backing store. In Redis that operation is SET key value NX PX ttl — the bundled X402.Extensions.PaymentIdentifier.RedisCache adapter implements exactly this contract over a Redix connection you supervise. For a different backing store, a minimal adapter sketch:

defmodule MyApp.RedisPaymentCache do
  @behaviour X402.Extensions.PaymentIdentifier.Cache

  @ttl_ms :timer.hours(1)

  @impl true
  def put_new(conn, payment_id, value) do
    # SET ... NX PX — atomic first-writer-wins with TTL in one command.
    case Redix.command(conn, ["SET", key(payment_id), encode(value), "NX", "PX", @ttl_ms]) do
      {:ok, "OK"} -> :ok
      {:ok, nil} -> {:error, :already_exists}
      {:error, reason} -> {:error, reason}
    end
  end

  @impl true
  def put(conn, payment_id, value) do
    case Redix.command(conn, ["SET", key(payment_id), encode(value), "PX", @ttl_ms]) do
      {:ok, "OK"} -> :ok
      {:error, reason} -> {:error, reason}
    end
  end

  @impl true
  def get(conn, payment_id) do
    case Redix.command(conn, ["GET", key(payment_id)]) do
      {:ok, nil} -> :miss
      {:ok, encoded} -> {:hit, decode(encoded)}
      {:error, reason} -> {:error, reason}
    end
  end

  @impl true
  def delete(conn, payment_id) do
    case Redix.command(conn, ["DEL", key(payment_id)]) do
      {:ok, _count} -> :ok
      {:error, reason} -> {:error, reason}
    end
  end

  defp key(payment_id), do: "x402:payment:" <> payment_id
  # encode/1 and decode/1 map `:verified | {:rejected, reason}` to a
  # string representation of your choice.
end

Configure it on the gate as:

plug X402.Plug.PaymentGate,
  payment_identifier_cache: {MyApp.RedisPaymentCache, MyApp.Redis},
  routes: [...]

Adapter errors other than {:error, :already_exists} fail closed: the gate responds with HTTP 500 and the protected handler does not run.