stripe.create

Creates Stripe SPT and stablecoin server methods with deposit-address resolution and payment recording.

Usage

Pass a deposit-address resolver, then use defaultMethods() to offer Tempo stablecoins and Stripe Shared Payment Tokens. mppx records successful Tempo payments as Stripe PaymentIntent objects.

import Stripe from 'stripe'
import { Mppx, stripe } from 'mppx/server'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
const payments = stripe.create({
  client,
  depositAddresses: (network) => stripe.findOrCreateDepositAddress(client, network),
  livemode: false,
  metadata: { plan: 'pro' },
  networkId: process.env.STRIPE_NETWORK_ID!,
})
 
const mppx = Mppx.create({
  methods: await payments.defaultMethods(),
  secretKey: process.env.MPP_SECRET_KEY!,
})
 
export async function handler(request: Request) {
  const result = await mppx.charge({
    amount: '1.00',
    description: 'Premium API access',
  })(request)
 
  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: '...' }))
}

Test mode uses pathUSD on Tempo testnet. Live mode uses USDC.e on Tempo mainnet. The SPT method defaults to cards and Link in both modes.

Configure one PaymentIntent

Pass paymentIntentOptions with route options to associate a Stripe Customer, apply an existing Tax Calculation, attach metadata, or send a receipt email. mppx keeps these options server-side and excludes them from the Challenge.

import Stripe from 'stripe'
import { Mppx, stripe } from 'mppx/server'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
const payments = stripe.create({
  client,
  livemode: false,
  metadata: { plan: 'pro' },
  networkId: process.env.STRIPE_NETWORK_ID!,
})
const mppx = Mppx.create({
  methods: payments.defaultMethods(),
  secretKey: process.env.MPP_SECRET_KEY!,
})
 
const handler = mppx.charge({
  amount: '1.00',
  description: 'Premium API access',
  paymentIntentOptions: {
    customer: 'cus_123',
    hooks: { inputs: { tax: { calculation: 'taxcalc_123' } } },
    metadata: { requestId: 'req_123' },
    receipt_email: 'customer@example.com',
  },
})

Request-scoped metadata overrides matching integration-level and per-method keys. For completed stablecoin payments, these options are best-effort: if Stripe rejects them, mppx retries the recording once without the optional fields. SPT payments don't use this fallback.

Resolve PaymentIntent options

Pass a resolver when options depend on the verified Credential or canonical request. The resolver runs after non-mutating method validation, when available, and immediately before the terminal payment operation.

import Stripe from 'stripe'
import { Mppx, stripe } from 'mppx/server'
 
declare function findOrCreateTaxCalculation(parameters: {
  amount: unknown
  idempotencyKey: string
}): Promise<string>
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
const payments = stripe.create({
  client,
  livemode: false,
  networkId: process.env.STRIPE_NETWORK_ID!,
})
const mppx = Mppx.create({
  methods: payments.defaultMethods(),
  secretKey: process.env.MPP_SECRET_KEY!,
})
 
const handler = mppx.charge({
  amount: '1.00',
  description: 'Premium API access',
  paymentIntentOptions: async ({
    challenge,
    request,
  }: stripe.ResolvePaymentIntentOptionsContext) => ({
    hooks: {
      inputs: {
        tax: {
          calculation: await findOrCreateTaxCalculation({
            amount: request.amount,
            idempotencyKey: challenge.id,
          }),
        },
      },
    },
    metadata: { challengeId: challenge.id },
  }),
})

The resolver receives challenge, credential, optional verified envelope, and canonical request fields. It can return options or a Promise of options. mppx doesn't call it for the initial Challenge or Credential failures detected before method execution. Stripe can still reject an SPT after the resolver runs.

The same Credential can invoke the resolver again on retry. Make external work idempotent and return equivalent options for the same Challenge. Resolver errors prevent SPT PaymentIntent creation and server-broadcast stablecoin payments. For push-mode stablecoin payments, the client broadcasts before the resolver runs, so an error prevents resource delivery and Stripe recording—not the transfer.

Advanced options

Sponsor Tempo transaction fees

Set hostedFeePayer: true to use Stripe's hosted Tempo fee payer for charge and Sessions methods created by this integration.

import Stripe from 'stripe'
import { stripe } from 'mppx/server'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
const payments = stripe.create({
  client,
  depositAddresses: (network) => stripe.findOrCreateDepositAddress(client, network),
  hostedFeePayer: true,
  livemode: true,
  networkId: process.env.STRIPE_NETWORK_ID!,
})

The hosted fee payer requires a compatible Stripe Node SDK client and a live-mode integration. It doesn't support Stripe Connect account routing.

SPT only

Omit depositAddresses when you only accept cards and Link through SPTs. defaultMethods() then returns the SPT method synchronously and doesn't call Stripe's deposit-address API.

With selected default methods

Exclude spt or tempo when you don't want both default charge methods.

import Stripe from 'stripe'
import { Mppx, stripe } from 'mppx/server'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
const payments = stripe.create({
  client,
  depositAddresses: (network) => stripe.findOrCreateDepositAddress(client, network),
  livemode: false,
  networkId: process.env.STRIPE_NETWORK_ID!,
})
 
const mppx = Mppx.create({
  methods: await payments.defaultMethods({ exclude: ['spt'] }),
  secretKey: process.env.MPP_SECRET_KEY!,
})

With static deposit addresses

Provide deposit addresses to create the default methods synchronously and avoid Stripe API lookup during startup.

import Stripe from 'stripe'
import { Mppx, stripe } from 'mppx/server'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
const payments = stripe.create({
  client,
  depositAddresses: {
    tempo: '0x20C0000000000000000000000000000000000001', // Stripe Tempo deposit address
  },
  livemode: true,
  networkId: process.env.STRIPE_NETWORK_ID!,
})
 
const mppx = Mppx.create({
  methods: payments.defaultMethods(),
  secretKey: process.env.MPP_SECRET_KEY!,
})

Return type

type StripeMachinePayments = {
  base: {
    charge(parameters: BaseChargeParameters): Method.Server
  }
  defaultMethods(parameters?: {
    exclude?: ('spt' | 'tempo')[]
  }): readonly Method.Server[] | PromiseLike<readonly Method.Server[]>
  findOrCreateDepositAddress<N extends 'base' | 'solana' | 'tempo'>(
    network: N,
  ): Promise<stripe.DepositAddress<N>>
  spt: {
    charge(parameters?: { paymentMethodTypes?: string[] }): Method.Server
  }
  tempo: {
    charge(parameters: TempoChargeParameters): Method.Server
    session(parameters: TempoSessionParameters): Method.Server
  }
}

With a Tempo deposit address, defaultMethods() returns Tempo charge followed by SPT charge. Without depositAddresses, it returns only SPT. A function resolver makes the result awaitable; static addresses or no resolver return synchronously. Chain .additional({ ... }) before awaiting to add Base charge, Tempo session, or a Solana method factory.

Stripe-managed stablecoin charge methods created directly or through .additional() require at least 0.01 USD. Below that amount, mppx excludes the method before returning a Challenge. Tempo sessions don't use this minimum.

Returned methods

base.charge

Creates a Base x402 charge method for a Stripe Base deposit address. Pass the branded address from findOrCreateDepositAddress('base') and an x402 facilitator configuration. Pass metadata to add or override Stripe PaymentIntent metadata for this method.

defaultMethods

Returns an SPT charge method plus each stablecoin method with a configured deposit address. Pass { exclude: ['spt'] } or { exclude: ['tempo'] } to omit a default.

Call .additional(config) before awaiting asynchronous address resolution. The config accepts base, solana, and tempo.session entries. Stablecoin charge methods record successful payments in Stripe without replacing their existing onPaymentSuccess hooks.

Function resolvers run in parallel. If one network fails, mppx logs a warning, excludes that network's methods, and keeps the methods whose addresses resolved.

findOrCreateDepositAddress

Returns a branded Stripe deposit address for 'base', 'solana', or 'tempo'. See stripe.findOrCreateDepositAddress.

spt.charge

Creates an SPT charge method. paymentMethodTypes defaults to ['card', 'link'].

tempo.charge

Creates a Tempo charge method for a Stripe deposit address. Currency and network derive from livemode. Pass metadata to add or override Stripe PaymentIntent metadata for this method.

tempo.session

Creates a Tempo session method for a Stripe deposit address. Pass the remaining tempo.session configuration.

Parameters

client

• Type: StripeClient

Stripe SDK client with rawRequest() support. Use Stripe SDK v15 or newer.

connect (optional)

• Type: { applicationFeeAmount?: number; onBehalfOf?: string; stripeAccount: string; transferData?: { amount?: number; destination: string }; transferGroup?: string }

Stripe Connect account and settlement configuration. stripeAccount scopes deposit-address lookup and recorded PaymentIntent objects to the connected account.

depositAddresses (optional)

• Type: Partial<Record<'base' | 'solana' | 'tempo', string>> | ((network) => Promise<string>)

Static deposit addresses or an asynchronous resolver. Use stripe.findOrCreateDepositAddress(client, network) in the resolver to fetch and cache Stripe addresses. When omitted, defaultMethods() returns only the SPT method.

hostedFeePayer (optional)

• Type: boolean

Uses Stripe's hosted Tempo fee payer for charge and Sessions methods. Requires livemode: true, a compatible Stripe Node SDK client, and no connect configuration.

livemode

• Type: boolean

Selects live or test networks and currencies for built-in stablecoin methods.

metadata (optional)

• Type: Record<string, string>

Key-value pairs attached to Stripe PaymentIntent objects created or recorded by SPT and stablecoin charge methods. Per-method metadata on base.charge() or tempo.charge() overrides matching keys. mppx adds machine_payment, mpp_challenge_id, mpp_intent, and mpp_sdk analytics keys by default; matching integration-, method-, or request-scoped metadata overrides them.

networkId

• Type: string

Stripe Business Network profile ID used by the SPT method.