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.

defaults (optional)

• Type: Partial<request>

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

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.