Stripe Integration
Normalize payment intents and settlement events into verifiable PEAC receipts. The receipt provides portable billing evidence that can be verified independently, used for dispute resolution, and carried across transports.
Package: @peac/rails-stripe (source-only; not published to npm in v0.15.0)
What It Does
The Stripe rail normalizes fiat payment events into the PEAC payment claim format. Payment intents, charges, and settlement confirmations are mapped into a portable record that can be signed and verified independently of the payment processor.
1. Payment event occurs
A fiat payment is processed through a card or account-based payment method. The payment processor returns a settlement confirmation with an intent ID, amount, currency, and status.
2. Normalize into PEAC format
The fromPaymentIntent() function extracts the relevant fields and maps them into PEAC commerce extension fields: rail, amount, currency, and settlement reference.
3. Issue a signed receipt
The normalized payment record is included in a PEAC receipt, signed with the issuer's Ed25519 key, and delivered as a compact JWS. The receipt can travel via the PEAC-Receipt header or any evidence carrier.
Availability
@peac/rails-stripe is source-only in v0.15.0: it is not published to npm. Build it from the repository (packages/rails/stripe). The mapping example below is a source-repository usage example. The published package for issuing and verifying the resulting records is @peac/protocol.
PaymentIntent Mapping
The primary integration point is the PaymentIntent object. After a payment succeeds, the intent is normalized into a PEAC payment record.
| PaymentIntent Field | PEAC Payment Claim | Notes |
|---|---|---|
id | tx_hash | PaymentIntent ID as settlement reference |
amount | amount | Converted from cents to decimal string |
currency | currency | ISO 4217 code, uppercased |
| (constant) | rail | Set to "stripe" |
Settlement Reference Mapping
The PaymentIntent id (such as pi_3abc...) is used as the tx_hash settlement reference. This allows a verifier to correlate the PEAC receipt with the original payment event when they have access to the payment processor records.
| Source | Reference Format | Example |
|---|---|---|
| PaymentIntent | pi_* | pi_3abc123def456 |
| Charge | ch_* | ch_1abc123def456 |
Usage Example
import { fromPaymentIntent } from '@peac/rails-stripe';
import { issue } from '@peac/protocol';
import { generateKeypair } from '@peac/crypto';
const { privateKey } = await generateKeypair();
// PaymentIntent observed from a Stripe webhook or API response
const paymentIntent = {
id: 'pi_3abc123def456',
amount: 2500, // $25.00 in cents
currency: 'usd',
status: 'succeeded',
};
// Normalize the observed intent into PEAC commerce extension fields
const commerce = fromPaymentIntent(paymentIntent);
// Issue a signed Wire 0.2 record observing the payment (PEAC does not process it)
const { jws } = await issue({
iss: 'https://billing.example.com',
kind: 'evidence',
type: 'org.peacprotocol/payment',
pillars: ['commerce'],
extensions: { 'org.peacprotocol/commerce': commerce },
privateKey,
kid: 'peac-2026-03',
});
// jws is the compact JWS; attach via PEAC-Receipt header or evidence carrierSPT Delegation Evidence
Stripe Payment Tokens (SPT) enable delegated payment authority. The rail records delegation lifecycle events separately from payment observations:
| Event | Type | Commerce Event |
|---|---|---|
delegated_payment_granted | Delegation lifecycle | None (not a payment event) |
delegated_payment_presented | Delegation lifecycle | None (not a payment event) |
delegated_payment_deactivated | Delegation lifecycle | None (not a payment event) |
succeeded | Payment observation | settlement |
requires_capture | Payment observation | authorization |
SPT grants and uses are delegation lifecycle events, not payment finality. Only fromStripePaymentIntentObservation() produces commerce events, and only when the upstream PaymentIntent explicitly proves the claimed state.
Implementation Examples
The Stripe rail supports multiple payment flows. PEAC records evidence of the settlement regardless of the underlying payment method.
| Flow | Type | Evidence Field |
|---|---|---|
| Stripe PaymentIntent | Fiat (card/bank) | payment_intent_id |
| SPT Delegation | Token lifecycle | delegation_id |
| Stripe x402 crypto profile (Base/USDC) | Crypto rail via x402 | tx_hash |
For x402 crypto flows, see the x402 integration page. The @peac/rails-x402 package handles the crypto settlement normalization.
Payment Claim Structure
The payment claim in the receipt payload contains the normalized settlement data:
| Field | Type | Description |
|---|---|---|
rail | string | Payment rail identifier ("stripe") |
amount | string | Settlement amount as a decimal string (converted from cents) |
currency | string | ISO 4217 currency code, uppercased |
tx_hash | string | PaymentIntent ID or Charge ID as settlement reference |
Links
Portable Payment Evidence
Receipts issued from fiat payment events are portable across all PEAC transports. The same receipt can travel through MCP, A2A, ACP, UCP, x402, and HTTP. A verifier needs only the issuer's public key to confirm the payment evidence; no direct access to the payment processor is required.