docs: update mppx hooks documentation

Author: brendanjryan

package.json

@@ -25,7 +25,7 @@
     "@stripe/stripe-js": "^9.3.1",
     "@vercel/blob": "^2.3.3",
     "mermaid": "^11.14.0",
-    "mppx": "0.6.20",
+    "mppx": "0.6.24",
     "react": "^19",
     "react-dom": "^19",
     "stripe": "^22.1.0",

pnpm-lock.yaml

@@ -15,6 +15,12 @@ imageDescription: "Updates on the Machine Payments Protocol"
 import { BlogPostList } from "../../components/BlogPostList";
 
 <BlogPostList posts={[
+  {
+    date: "May 18, 2026",
+    title: "Payment hooks",
+    description: <>SDKs now expose typed payment hooks for logging, monitoring, and request context.</>,
+    to: "/blog/payment-hooks",
+  },
   {
     date: "May 12, 2026",
     title: "Subscriptions",

src/pages/blog/index.mdx

@@ -0,0 +1,152 @@
+---
+layout: minimal
+outline: false
+showAskAi: false
+showFeedback: false
+showSearch: false
+description: "SDKs now expose typed payment hooks for logging, monitoring, and request context."
+imageDescription: "Monitor request status with SDK hooks"
+---
+
+<div className="blog-narrow">
+
+<a href="/blog" className="blog-back">Blog</a>
+
+<p className="blog-date" style={{ color: 'var(--vocs-color_text3)', fontSize: '14px' }}>May 18, 2026</p>
+
+# Payment hooks [Observe MPP requests with typed lifecycle events]
+
+SDKs now expose typed payment hooks for client and server payment flows. Use them to record what happened around an MPP request without rewriting your payment handler.
+
+Hooks are useful when payment telemetry belongs next to the rest of your application telemetry: logs, metrics, traces, audit records, support dashboards, or local debugging context.
+
+## What changed
+
+Client hooks observe Challenge selection, Credential creation, retry responses, and failures. Use typed helpers for common events, canonical strings for direct event names, or `*` for a single catch-all handler:
+
+```ts twoslash [client.ts]
+import { Mppx, tempo } from 'mppx/client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const account = privateKeyToAccount(process.env.MPP_PRIVATE_KEY as `0x${string}`)
+
+const mppx = Mppx.create({
+  methods: [tempo({ account })],
+  polyfill: false,
+})
+
+const log = (event: string, data: Record<string, unknown>) => {
+  console.log(event, data)
+}
+
+mppx.onChallengeReceived(({ challenge }) => {
+  // Observe the selected Challenge before the SDK creates a Credential.
+  log('payment.challenge.received', {
+    challengeId: challenge.id,
+    intent: challenge.intent,
+    method: challenge.method,
+  })
+  return undefined
+})
+
+mppx.on('payment.response', ({ challenge, response }) => {
+  // Use canonical event names when you want to share event wiring.
+  log('payment.response', {
+    challengeId: challenge.id,
+    status: response.status,
+  })
+})
+
+mppx.on('*', ({ name, payload }) => {
+  // Use `*` to send all payment events through one telemetry path.
+  log('payment.event', {
+    hasChallenge: 'challenge' in payload,
+    name,
+  })
+})
+
+mppx.onPaymentFailed(({ error, input }) => {
+  // Capture failures from Challenge parsing, Credential creation, or retry handling.
+  log('payment.failed', {
+    error: error instanceof Error ? error.message : String(error),
+    input: String(input),
+  })
+})
+
+const response = await mppx.fetch('https://api.example.com/report')
+```
+
+Server hooks observe issued Challenges, successful payments, and rejected Credentials:
+
+```ts twoslash [server.ts]
+import { Mppx, tempo } from 'mppx/server'
+
+const payment = Mppx.create({
+  methods: [tempo.charge()],
+})
+
+const log = (event: string, data: Record<string, unknown>) => {
+  console.log(event, data)
+}
+
+payment.onChallengeCreated(({ challenge, request }) => {
+  // Observe each `402` Challenge before it is returned to the client.
+  log('payment.challenge.created', {
+    amount: request.amount,
+    challengeId: challenge.id,
+    currency: request.currency,
+  })
+})
+
+payment.on('payment.success', ({ receipt, request }) => {
+  // Use canonical event names when you want to share event wiring.
+  log('payment.success', {
+    amount: request.amount,
+    currency: request.currency,
+    reference: receipt.reference,
+    status: receipt.status,
+  })
+})
+
+payment.on('*', ({ name, payload }) => {
+  // Use `*` to send all payment events through one telemetry path.
+  log('payment.event', {
+    challengeId: payload.challenge.id,
+    intent: payload.method.intent,
+    name,
+  })
+})
+
+payment.onPaymentFailed(({ challenge, error, request }) => {
+  // Record failed Credential verification with request and Challenge context.
+  log('payment.failed', {
+    amount: request.amount,
+    challengeId: challenge.id,
+    error: error.name,
+  })
+})
+```
+
+## Why hooks matter
+
+MPP keeps the payment flow close to the request flow. That makes integration simple, but production systems still need visibility.
+
+Hooks give you a typed place to attach that visibility:
+
+- **Monitoring and observability**: Count Challenges, successful payments, failed Credentials, and paid retry responses, then attach Challenge IDs, method names, intents, amounts, currencies, and Receipt references to traces.
+- **Logging**: Record enough context to debug a failed payment without logging secrets.
+- **Support**: Connect a user-facing request to the payment attempt that authorized it.
+
+## Use hooks carefully
+
+Client observation hooks don't change payment handling. If a client observation hook throws, `mppx` ignores the error and continues the payment flow.
+
+`onChallengeReceived` is the one client hook that can affect handling: return a non-empty Credential string to use it for the retry. This lets advanced clients create Credentials with custom context before falling back to `onChallenge` or the default flow.
+
+Server hooks run inline on the payment request path. Keep them short, or hand work to your logger, metrics client, or queue. `mppx` ignores thrown server hook errors so observability code doesn't block payment verification, but slow hooks still delay the response.
+
+## What's next
+
+This release starts with core lifecycle events. If there is an event or payload field you need, leave feedback on [GitHub](https://github.com/wevm/mppx/issues).
+
+</div>

src/pages/blog/payment-hooks.mdx

@@ -68,6 +68,12 @@ Controls when `Accept-Payment` is injected.
 
 Use `'same-origin'` in browsers when you only want same-origin payment discovery. Use `{ origins }` when paid APIs live on specific origins. Origin patterns support `*.` subdomain wildcards.
 
+### eventDispatcher (optional)
+
+- **Type:** `ClientEventDispatcher<methods>`
+
+Advanced shared event dispatcher. `challenge.received` handlers run before `onChallenge`; the first non-empty Credential string skips `onChallenge`.
+
 ### fetch (optional)
 
 - **Type:** `typeof globalThis.fetch`

src/pages/sdk/typescript/client/Fetch.from.mdx

@@ -63,6 +63,12 @@ Resolved `Accept-Payment` header and preference data.
 
 Controls when `Accept-Payment` is injected.
 
+### eventDispatcher (optional)
+
+- **Type:** `ClientEventDispatcher<methods>`
+
+Advanced shared event dispatcher. `challenge.received` handlers run before `onChallenge`; the first non-empty Credential string skips `onChallenge`.
+
 ### fetch (optional)
 
 - **Type:** `typeof globalThis.fetch`

src/pages/sdk/typescript/client/Fetch.polyfill.mdx

@@ -18,6 +18,37 @@ Mppx.create({
 const res = await fetch('https://mpp.dev/api/ping/paid')
 ```
 
+### With payment hooks
+
+Register hooks on the returned `mppx` instance to observe the payment flow.
+
+```ts twoslash
+import { Mppx, tempo } from 'mppx/client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const account = privateKeyToAccount('0x...')
+
+const mppx = Mppx.create({
+  methods: [tempo({ account })],
+  polyfill: false,
+})
+
+const offFailure = mppx.onPaymentFailed(({ error, input }) => {
+  console.error('payment failed:', input, error)
+})
+
+const offResponse = mppx.onPaymentResponse(({ challenge, response }) => {
+  console.log('payment response:', challenge.id, response.status)
+})
+
+const res = await mppx.fetch('https://mpp.dev/api/ping/paid')
+console.log(res.status)
+// @log: 200
+
+offFailure()
+offResponse()
+```
+
 ### Without polyfill
 
 Set `polyfill: false` to get a scoped fetch without modifying the global:
@@ -103,6 +134,16 @@ type Mppx = {
     context?: Context,
     options?: { acceptPayment?: string | AcceptPayment.Entry[] },
   ) => Promise<string>
+  /** Register a handler for any client payment event. */
+  on(name: ClientEventName | '*', handler: ClientEventHandler): Unsubscribe
+  /** Register a handler for received payment Challenges. */
+  onChallengeReceived(handler: ChallengeReceivedHandler): Unsubscribe
+  /** Register a handler for created Credentials. */
+  onCredentialCreated(handler: CredentialCreatedHandler): Unsubscribe
+  /** Register a handler for failed automatic payment handling. */
+  onPaymentFailed(handler: PaymentFailedHandler): Unsubscribe
+  /** Register a handler for payment retry responses. */
+  onPaymentResponse(handler: PaymentResponseHandler): Unsubscribe
 }
 ```
 
@@ -125,6 +166,41 @@ const mppx = Mppx.create({
 const raw = await mppx.rawFetch('https://api.example.com/ws-auth') // [!code focus]
 ```
 
+## Payment hooks
+
+Payment hooks are for logging, monitoring, tracing, and request-local context. Each registration returns an unsubscribe function.
+
+| Hook | Runs when |
+|---|---|
+| `onChallengeReceived` | A `402` Challenge is selected |
+| `onCredentialCreated` | A Credential is created for the selected Challenge |
+| `onPaymentResponse` | The retry after payment returns a successful response |
+| `onPaymentFailed` | Challenge parsing, credential creation, or retry handling fails |
+| `on('*', handler)` | Any client payment event fires |
+
+`onChallengeReceived` runs before `onChallenge`. It can return a non-empty Credential string to override the default credential flow. Other hooks are observers: thrown errors are ignored and don't change payment handling.
+
+```ts twoslash
+import { Mppx, tempo } from 'mppx/client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const account = privateKeyToAccount('0x...')
+
+const mppx = Mppx.create({
+  methods: [tempo({ account })],
+  polyfill: false,
+})
+
+mppx.onChallengeReceived(async ({ challenge, createCredential }) => {
+  console.log('challenge received:', challenge.id)
+  return createCredential()
+})
+
+mppx.on('*', ({ name }) => {
+  console.log('payment event:', name)
+})
+```
+
 ## Parameters
 
 ### acceptPaymentPolicy (optional)

src/pages/sdk/typescript/client/Mppx.create.mdx

@@ -25,6 +25,30 @@ const payment = Mppx.create({
 })
 ```
 
+### With payment hooks
+
+Register hooks on the returned `payment` instance to observe Challenges, successful payments, and failures.
+
+```ts twoslash
+import { Mppx, tempo } from 'mppx/server'
+
+const payment = Mppx.create({
+  methods: [tempo.charge()],
+})
+
+payment.onChallengeCreated(({ challenge, request }) => {
+  console.log('challenge created:', challenge.id, request.amount)
+})
+
+payment.onPaymentFailed(({ challenge, error }) => {
+  console.error('payment failed:', challenge.id, error.name)
+})
+
+payment.onPaymentSuccess(({ receipt, request }) => {
+  console.log('payment success:', receipt.reference, request.amount)
+})
+```
+
 ## Return type
 
 ```ts
@@ -34,7 +58,7 @@ import type { Mppx, Transport } from 'mppx/server'
 type ReturnType = Mppx<[Method.Server], Transport.Http>
 ```
 
-The returned object includes the method's intent functions (for example, `charge`), `compose`, and `verifyCredential`.
+The returned object includes the method's intent functions (for example, `charge`), `challenge`, `compose`, payment hooks, and `verifyCredential`.
 
 ## Parameters