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
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 normalizeStripeIntent() function extracts the relevant fields and maps them into the PEAC payment claim structure: 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.
Install
pnpm add @peac/rails-stripe
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 { normalizeStripeIntent } from '@peac/rails-stripe';
import { issue } from '@peac/protocol';
// PaymentIntent from webhook or API response
const paymentIntent = {
id: 'pi_3abc123def456',
amount: 2500, // $25.00 in cents
currency: 'usd',
status: 'succeeded',
};
// Normalize into PEAC payment record
const payment = normalizeStripeIntent(paymentIntent);
// {
// rail: 'stripe',
// amount: '25.00',
// currency: 'USD',
// tx_hash: 'pi_3abc123def456',
// }
// Issue a signed receipt
const receipt = await issue({
iss: 'https://billing.example.com',
aud: 'customer.example.com',
payment,
control: {
decision: 'allow',
purposes: ['user_action'],
},
});
// receipt.jws contains the compact JWS
// Attach to response via PEAC-Receipt header or evidence carrierImplementation 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 |
| 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.