stripe.recordPayment

Records an already-settled stablecoin payment as a Stripe PaymentIntent.

Usage

The mppx stripe.create integration records settled stablecoin payments in Stripe automatically. Use this helper if that recording doesn't complete after the on-chain payment settles, for example because the process stops. Confirm settlement on the specified network before calling it; the helper doesn't transfer funds.

import Stripe from 'stripe'
import { stripe } from 'mppx/server'
 
const client = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
const result = await stripe.recordPayment(client, {
  amount: '1000000', // 1 USDC.e, with 6 decimals
  network: 'tempo',
  reference: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
})
 
console.log(result.status)
created

The helper creates a USD PaymentIntent in Stripe's transaction_verification mode, which asks Stripe to verify the on-chain transaction rather than charge the payer again. It floors six-decimal token units to whole US cents. Amounts below one cent return below_minimum without calling Stripe.

Retry safely

• Retries: reference is the transaction hash and Stripe idempotency key, matching automatic recording. Stripe retains keys for at least 24 hours; equivalent parameters return replayed within that period.
• Conflicts: Different parameters, including omitted automatic metadata, return key_conflict. Stripe caches failed responses too, so a conflict doesn't prove a PaymentIntent exists. Look it up before marking the payment recorded.
• Expired keys: Reconcile Stripe records before retrying older payments; expired keys no longer prevent duplicates.
• Fallback records: Automatic recording uses <reference>_fallback only after Stripe definitively rejects optional paymentIntentOptions (customer, tax, metadata, or receipt-email fields). Check both keys during reconciliation. This helper neither searches Stripe nor uses the fallback key.
• Other errors: Unlike automatic recording, this helper throws other Stripe errors so your recovery worker can retry.
• Verification: created and replayed mean Stripe returned a PaymentIntent, not that verification succeeded. Only paymentIntentStatus: 'succeeded' confirms it. Recheck processing or requires_action records later.

Return type

type ReturnType =
  | {
      paymentIntentId: string
      paymentIntentStatus: string
      status: 'created' | 'replayed'
    }
  | { status: 'key_conflict' }
  | { status: 'below_minimum' }

Parameters

Call stripe.recordPayment(client, parameters). client is the first argument; all other entries below are fields of the second argument.

amount

• Type: string

Settled amount in the token's raw six-decimal units, as in the Challenge request. For a Session settlement, use the newly settled amount rather than the cumulative total.

client

• Type: StripeClient

Pre-configured Stripe SDK client with paymentIntents.create support.

connect (optional)

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

Stripe Connect settings for the settled payment. Use the same connected account and settlement parameters as the original recording.

metadata (optional)

• Type: Record<string, string>
• Default: {}

Metadata attached to the PaymentIntent. This helper doesn't add automatic mppx analytics metadata: machine_payment, mpp_intent, mpp_sdk, and (for charges) mpp_challenge_id. Use equivalent metadata when recovering an existing recording attempt to avoid an idempotency conflict.

network

• Type: 'base' | 'solana' | 'tempo'

Network where the stablecoin payment settled.

reference

• Type: string

Settled transaction hash, used as Stripe's idempotency key.