Method.toServer

Extends a payment method with server-side validation and payment-finalization hooks.

Usage

import { Mppx } from 'mppx/server'
import { Method, Receipt } from 'mppx'
import * as Methods from './methods'
 
// Create server-configured method.
const charge = Method.toServer(Methods.charge, {
  async broadcast({ credential, request }) {
    return Receipt.from({
      method: 'tempo',
      reference: '0x...',
      status: 'success',
      timestamp: new Date().toISOString(),
    })
  },
  async validate({ credential, request }) {
    return {
      challenge: credential.challenge,
      credential,
      details: {},
      intent: 'charge',
      method: 'tempo',
      request,
    }
  },
})
 
// Create Mppx server with the method configured.
const mppx = Mppx.create({
  methods: [charge],
})

import { Method, z } from 'mppx'
 
export const charge = Method.from({
  intent: 'charge',
  name: 'tempo',
  schema: {
    credential: {
      payload: z.object({
        signature: z.string(),
        type: z.literal('transaction'),
      }),
    },
    request: z.object({
      amount: z.string(),
      currency: z.string(),
      recipient: z.string(),
    }),
  },
})

Return type

type ReturnType = Method.Server<method, defaults, transportOverride>

A server-configured method that can be passed to Mppx.create.

Payment lifecycle

Implement validate and broadcast for new server methods. mppx runs validate before the terminal broadcast hook. validate is a non-mutating pre-check; broadcast must revalidate its state before it reserves, signs, broadcasts, or otherwise accepts payment.

Use this split when a method calls a relay or needs to apply policy between a Credential check and payment acceptance. verify is the deprecated combined hook for older methods and cannot be combined with broadcast.

Parameters

method

• Type: Method

The base payment method definition (created with Method.from).

options

• Type: Method.toServer.Options<method>

Server defaults and lifecycle callbacks for this payment method.

broadcast

• Type: (parameters: { credential: Credential; request: request }) => Promise<Receipt>

Completes payment and returns its Receipt. Revalidate any external or on-chain state before the terminal operation, because a previous validate result is advisory.

canOffer (optional)

• Type: Method.CanOfferFn<method>

Returns whether this method's configured offer is available when an HTTP handler composes multiple offers. The hook receives a cloned incoming request and a schema-normalized, deeply immutable payment request. It doesn't run for direct method handlers or successfully matched Credentials.

defaults (optional)

• Type: Partial<request>

Default request parameters merged into every Challenge issued for this method.

onPaymentSuccess (optional)

• Type: Method.OnPaymentSuccessFn<method>

Runs after this method completes successfully. The hook receives the optional associated challenge; the canonical, deeply immutable request; its receipt; the HTTP input when available; and an optional requestInput containing server-side method input before request-schema output transforms. Standalone Credential verification omits requestInput when no route options are supplied. Mppx.create scopes the hook to the method's name and intent, awaits it inline, and ignores thrown errors.

request (optional)

• Type: (options: { credential?: Credential; request: request }) => request

Transform function called before Challenge creation. Use to modify or enrich request parameters.

respond (optional)

• Type: (parameters: { credential: Credential; input: Request; receipt: Receipt; request: request }) => Response | undefined

Called after payment succeeds. Return a Response to short-circuit the handler (for example, for channel open/close management responses). Return undefined to let the server handler serve content via withReceipt(response). HTTP-only—MCP transports do not invoke this hook.

transport (optional)

• Type: Transport

Override the transport for this method.

validate (optional)

• Type: (parameters: { credential: Credential; request: request }) => Promise<Method.Validation>

Validates a Credential without settling, reserving, broadcasting, or otherwise consuming payment state.

verify (deprecated)

• Type: (parameters: { credential: Credential; request: request }) => Promise<Receipt>

Legacy combined validation and settlement function. Use validate and broadcast for new methods.