stripe.spt

Creates the Stripe charge method for one-time payments with Shared Payment Tokens (SPTs).

Usage

import Stripe from 'stripe'
import { Mppx } from 'mppx/server/core'
import { stripe } from 'mppx/stripe/server/spt'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
const mppx = Mppx.create({
  methods: [
    stripe.spt({
      client,
      networkId: process.env.STRIPE_NETWORK_ID!,
      paymentMethodTypes: ['card', 'link'],
    }),
  ],
  secretKey: process.env.MPP_SECRET_KEY!,
})
 
export async function handler(request: Request) {
  const result = await mppx.charge({
    amount: '1',
    currency: 'usd',
    decimals: 2,
    description: 'Premium API access',
    paymentIntentOptions: {
      customer: 'cus_123',
      hooks: { inputs: { tax: { calculation: 'taxcalc_123' } } },
      metadata: { requestId: 'req_123' },
      receipt_email: 'customer@example.com',
    },
  })(request)
 
  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: '...' }))
}

mppx derives each Stripe PaymentIntent idempotency key from the Challenge ID and SPT, using the SDK-independent mpp_ prefix.

These lightweight entrypoints omit unrelated payment rails. Use mppx/server when the same server also accepts other methods.

Resolve options after verification

Pass a function to resolve paymentIntentOptions from the verified Credential or canonical request immediately before Stripe creates the PaymentIntent.

import Stripe from 'stripe'
import { Mppx } from 'mppx/server/core'
import { stripe } from 'mppx/stripe/server/spt'
 
declare function findOrCreateTaxCalculation(parameters: {
  amount: unknown
  idempotencyKey: string
}): Promise<string>
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
const mppx = Mppx.create({
  methods: [
    stripe.spt({
      client,
      networkId: process.env.STRIPE_NETWORK_ID!,
      paymentMethodTypes: ['card', 'link'],
    }),
  ],
  secretKey: process.env.MPP_SECRET_KEY!,
})
 
const handler = mppx.charge({
  amount: '1',
  currency: 'usd',
  decimals: 2,
  description: 'Premium API access',
  paymentIntentOptions: async ({ challenge, request }) => ({
    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. mppx doesn't call it for the initial Challenge or Credential failures detected before method execution. Stripe can still reject an expired, revoked, or fabricated 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 to preserve Stripe idempotency. Resolver errors prevent PaymentIntent creation.

With Stripe Connect

Set a fixed settlement policy or return one from a resolver for each verified Credential.

import Stripe from 'stripe'
import { stripe } from 'mppx/stripe/server/spt'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
const method = stripe.spt({
  client,
  connect: {
    applicationFeeAmount: 10,
    stripeAccount: 'acct_123',
  },
  networkId: process.env.STRIPE_NETWORK_ID!,
  paymentMethodTypes: ['card'],
})

Return type

import type { Method } from 'mppx'
 
type ReturnType = Method.Server

Parameters

canOffer (optional)

• Type: Method.CanOfferFn

Returns whether this offer is available when an HTTP handler composes multiple methods. Stripe's currency minimum runs before this hook.

client

• Type: StripeClient

Pre-configured Stripe SDK client. Provide either client or secretKey.

connect (optional)

• Type: ConnectSettlement | ((context) => MaybePromise<ConnectSettlement | undefined>)

Fixed or per-Credential Stripe Connect settlement policy. Properties are applicationFeeAmount, onBehalfOf, stripeAccount, transferData, and transferGroup.

html (optional)

• Type: { createTokenUrl: string; publishableKey: string; ...Html.Config }

Renders a Stripe Elements payment form for browser requests. See the payment links guide.

metadata (optional)

• Type: Record<string, string>

Metadata included in the Challenge and attached to the Stripe PaymentIntent. mppx adds machine_payment, mpp_challenge_id, mpp_intent, and mpp_sdk analytics keys by default; matching method- or request-scoped metadata overrides them.

networkId

• Type: string

Stripe Business Network profile ID.

onPaymentSuccess (optional)

• Type: Method.OnPaymentSuccessFn<typeof stripe.Methods.charge>

Runs after this SPT payment succeeds. The hook receives the optional associated Challenge, canonical request, its Receipt, the HTTP input when available, and the resolved pre-transform requestInput when route options are available. Hook errors are isolated from payment handling.

paymentMethodTypes

• Type: string[]

Allowed Stripe payment method types, such as ['card', 'link'].

secretKey

• Type: string

Stripe secret API key. Provide either client or secretKey.

Request parameters

amount

• Type: string

Payment amount in human-readable units.

currency

• Type: string

ISO currency code, such as 'usd'.

decimals

• Type: number

Number of decimal places used to display the amount.

description (optional)

• Type: string

Human-readable description of the payment request.

externalId (optional)

• Type: string

External identifier bound to the Challenge and Credential.

paymentIntentOptions (optional)

• Type: PaymentIntentOptions | ((context: ResolvePaymentIntentOptionsContext) => MaybePromise<PaymentIntentOptions | undefined>)

Request-scoped Stripe PaymentIntent options or a deferred resolver. Use customer to associate a Stripe Customer, hooks.inputs.tax.calculation to apply an existing Tax Calculation, metadata to attach key-value pairs, and receipt_email to send a receipt. Metadata overrides matching method-level keys. mppx keeps these options server-side, excludes them from the Challenge, and resolves or forwards them immediately before Stripe creates the PaymentIntent.