Stripe Payments

Overview

A Stripe payment resolves in stages that are hours or days apart. The PaymentIntent succeeds in seconds, the resulting charge produces a balance transaction that becomes available later, and the payout that moves the money to a bank account arrives later still. Instrumenting only the API call that creates the intent captures the first moment and none of the rest. Mirador’s Stripe hint ties a PaymentIntent to a trace by its ID. The backend stripehint processor polls Stripe and emits the settlement lifecycle onto that same trace:

StripeHintAdded → StripeTrackingStarted
StripePaymentSucceeded (charge and balance transaction resolved)
StripeFundsAvailable (gross, fee, and net, with the availability date)
StripePayoutPaid (the payout that settled the funds)
StripeTrackingFinished (terminal)

You record the hint once. The lifecycle is filled in for you.

Stripe hints are emitted over OpenTelemetry only. Unlike the Web3 hints, there is no Web SDK method — no Web3Plugin, no trace.payment.* namespace. Emit the reserved span event described below.

Recording a Payment Hint

Add the mirador.payment.stripe.intenthint event to the active span once Stripe has returned a PaymentIntent ID.

span.addEvent('mirador.payment.stripe.intenthint', {
  'stripe.payment_intent_id': paymentIntent.id,
});

span.AddEvent("mirador.payment.stripe.intenthint", trace.WithAttributes(
    attribute.String("stripe.payment_intent_id", paymentIntent.ID),
))

span.add_event("mirador.payment.stripe.intenthint", {
    "stripe.payment_intent_id": payment_intent.id,
})

The PaymentIntent ID is the only attribute Mirador needs. Amounts, currency, charge IDs, fees, and payout details are resolved server-side from Stripe’s API.

Attributes

Attribute	Type	Required	Description
`stripe.payment_intent_id`	string	Yes	The PaymentIntent ID (`pi_…`)
`stripe.account_id`	string	No	A Stripe Connect connected account (`acct_…`) to route API calls to

No chain attribute applies. Stripe is not a blockchain hint, so chain.id and chain.name do not affect tracking — like any extra attribute, they are preserved on the event as context.

Connected Accounts

On a Stripe Connect platform, pass the connected account that owns the payment so Mirador queries the right account.

span.addEvent('mirador.payment.stripe.intenthint', {
  'stripe.payment_intent_id': paymentIntent.id,
  'stripe.account_id': connectedAccountId,
});

Omit stripe.account_id when observing payments on your own account.

Lifecycle Events

The hint opens a synthetic stripehint span on the trace, and the lifecycle nests inside it.

Event	Emitted when	Carries
`StripeHintAdded`	The hint is accepted	PaymentIntent ID, optional account ID
`StripeTrackingStarted`	The processor begins polling Stripe	PaymentIntent ID
`StripePaymentSucceeded`	The intent reaches a resolved state	Payment status, amount, charge ID, balance transaction ID
`StripeFundsAvailable`	The balance transaction becomes available	Gross, fee, net, availability date
`StripePayoutPaid`	The settling payout is paid	Payout ID, amount, status, arrival date, automatic flag
`StripeTrackingFinished`	The lifecycle reaches a terminal state	Terminal status, PaymentIntent, charge, payout, net amount

Monetary values use Stripe’s native representation: an integer in the currency’s minor unit (cents for USD) plus a lowercase ISO currency code. This mirrors Stripe’s own amount/currency pair exactly, so no precision is lost.

Terminal Statuses

StripeTrackingFinished closes the lifecycle with one of:

Status	Meaning
`SUCCESS`	Payment succeeded and funds were paid out
`PAYMENT_FAILED`	The PaymentIntent failed or was canceled
`REFUNDED`	The charge was refunded
`DISPUTED`	The charge was disputed or charged back
`PAYOUT_FAILED`	The payout to the bank account failed
`TIMEOUT`	Tracking gave up before reaching a terminal phase
`NOT_FOUND`	The PaymentIntent was never found in Stripe

A payment that settles normally but has not yet paid out is still in flight, not failed. TIMEOUT means Mirador stopped watching, not that Stripe failed.

End-to-End Example

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('checkout');

await tracer.startActiveSpan('checkout-flow', async (span) => {
  try {
    // 1. Create the PaymentIntent
    const paymentIntent = await stripe.paymentIntents.create({
      amount: 4999,
      currency: 'usd',
    });

    // 2. Tie it to the trace — only after Stripe returns the ID
    span.addEvent('mirador.payment.stripe.intenthint', {
      'stripe.payment_intent_id': paymentIntent.id,
    });

    // 3. Confirm the payment. Nothing further is needed Mirador-side — the
    //    stripehint processor emits the charge, funds-available, and payout
    //    events onto this trace as Stripe reports them.
    await confirmPayment(paymentIntent);
  } finally {
    span.end();
  }
});

Combining With Other Hints

Stripe hints compose freely with the Web3 hints. A flow that charges a card and then settles onchain can carry both, and each resolves independently onto the same trace.

span.addEvent('mirador.payment.stripe.intenthint', {
  'stripe.payment_intent_id': paymentIntent.id,
});

span.addEvent('mirador.web3.evm.txhint', {
  'tx.hash': settlementTx.hash,
  'chain.id': 8453,
});

Next Steps

Enrichment Hints

The full reserved-event catalog and attribute contract

Market Rates

Resolve asset spot rates and USD notionals

Traces over OTLP

Exporter configuration and span mapping

Automation Rules

Alert on payment failures and disputes

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

Overview

Recording a Payment Hint

Attributes

Connected Accounts

Lifecycle Events

Terminal Statuses

End-to-End Example

Combining With Other Hints

Next Steps

Enrichment Hints

Market Rates

Traces over OTLP

Automation Rules

​Overview

​Recording a Payment Hint

​Attributes

​Connected Accounts

​Lifecycle Events

​Terminal Statuses

​End-to-End Example

​Combining With Other Hints

​Next Steps

Enrichment Hints

Market Rates

Traces over OTLP

Automation Rules

Overview

Recording a Payment Hint

Attributes

Connected Accounts

Lifecycle Events

Terminal Statuses

End-to-End Example

Combining With Other Hints

Next Steps