Stripe Mpp
@magistr/stripe-mppv2026.08.19.1
Security Notice
This extension includes AI agent skills that can modify AI assistant behavior. Review the skill files before installing.
01README
Stripe Machine Payments Protocol (MPP) — agent buyer (probe/mint/pay over HTTP-402 Payment auth), consumer buyer (grant a Shared Payment Token from a Link wallet via link-cli, spend by reference), and full seller API (challenge/verify/charge/receipt/reconcile/refund) for fiat Shared Payment Tokens, built on mppx and the Stripe preview SDK
02Models
@magistr/stripe-mppv2026.08.19.1extensions/models/stripe_mpp.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| secretKey | string | Stripe secret key (sk_test_... / sk_live_...). Use a vault reference: |
| serverSecret? | string | Seller-side HMAC secret (>=32 chars) binding challenge ids |
| networkId? | string | Stripe Business Network Profile id (profile_test_... / profile_...). |
| realm | string | Protection-space identifier advertised in seller challenges (RFC 9110). |
| stripeVersion | string | Stripe-Version header. SPT endpoints need the preview channel. |
| testMode | boolean | Gates test helpers (createTestGrantedToken). Must match the key mode. |
| allowInsecure | boolean | Test-fixture escape: permit plain http:// to loopback, allow private/ |
| timeoutMs | number | Per-request timeout for resource fetches and Stripe calls. |
| paymentMethodTypes | array | Payment method types advertised in seller challenges. |
| linkCliPath? | string | ABSOLUTE path to the installed @stripe/link-cli binary (a non-writable |
| linkCliVersion | string | Pinned link-cli version. The MCP initialize serverInfo.version is |
| allowLiveGrants | boolean | Consumer-grant live-money opt-in. Default false forces link-cli test |
fn probe()
Request a resource WITHOUT paying and record the parsed payment
fn mintToken(paymentMethodId: string, maxAmount: string, currency: string, expiresAt?: number, sellerNetworkId?: string, externalId?: string)
Mint a fiat Shared Payment Token from an existing payment method
| Argument | Type | Description |
|---|---|---|
| paymentMethodId | string | Existing payment method (pm_...). Raw-PAN creation is PCI-gated in |
| maxAmount | string | Usage-limit ceiling, minor units string. |
| currency | string | Usage-limit currency (ISO, lowercase). |
| expiresAt? | number | Unix timestamp for usage_limits.expires_at. |
| sellerNetworkId? | string | Seller network profile the token is granted to (defaults to networkId). |
| externalId? | string | Correlation id; also drives the Idempotency-Key. |
fn pay(sptId: string, maxAmount: string, currency: string, expectedNetworkId?: string, expectedRealm?: string, externalId?: string)
Pay for a resource end-to-end: request it, parse the 402 stripe
| Argument | Type | Description |
|---|---|---|
| sptId | string | Shared Payment Token (spt_...) to present. |
| maxAmount | string | Spend ceiling, minor units string. The challenge amount must not |
| currency | string | Expected challenge currency. Mismatch blocks the payment. |
| expectedNetworkId? | string | Pin the payee: the Stripe Business Network Profile (profile_...) the |
| expectedRealm? | string | Pin the challenge realm (issuing authority); mismatch blocks the payment. |
| externalId? | string | Correlation id. |
fn getIssuedToken(sptId: string)
Retrieve an issued Shared Payment Token
| Argument | Type | Description |
|---|---|---|
| sptId | string | Shared Payment Token id (spt_...). |
fn revokeToken(sptId: string)
Revoke an issued Shared Payment Token
| Argument | Type | Description |
|---|---|---|
| sptId | string | Shared Payment Token id (spt_...). |
fn createChallenge(amount: string, currency: string, description?: string, externalId?: string, expiresInSeconds?: number, networkId?: string, scope?: string)
Produce seller challenge material for a payment-gated resource:
| Argument | Type | Description |
|---|---|---|
| amount | string | Amount demanded, minor units string. |
| currency | string | Currency (ISO, lowercase). |
| description? | string | |
| externalId? | string | |
| expiresInSeconds? | number | Challenge validity window; recommended to keep challenges short-lived. |
| networkId? | string | Override the global networkId. |
| scope? | string | Bind the challenge to a specific resource/route. Carried inside the |
fn verifyCredential(authorizationHeader: string, expectedAmount?: string, expectedCurrency?: string, expectedScope?: string)
Verify a received Authorization: Payment credential — HMAC-bound
| Argument | Type | Description |
|---|---|---|
| authorizationHeader | string | The received Authorization value ("Payment <base64url>"). |
| expectedAmount? | string | |
| expectedCurrency? | string | |
| expectedScope? | string | Require the credential's challenge `opaque` to equal this route scope |
fn chargeToken(sptId?: string, amount?: string, currency?: string, authorizationHeader?: string, expectedScope?: string, description?: string, externalId?: string)
Settle a granted Shared Payment Token via a confirmed
| Argument | Type | Description |
|---|---|---|
| sptId? | string | Granted token to settle (or pass authorizationHeader). |
| amount? | string | Minor units string. |
| currency? | string | |
| authorizationHeader? | string | Full received credential; verified (HMAC + expiry) before settling. |
| expectedScope? | string | When settling from an authorizationHeader, require the challenge |
| description? | string | |
| externalId? | string |
fn issueReceipt(chargeId: string, externalId?: string)
Produce the Payment-Receipt header value for a SETTLED charge
| Argument | Type | Description |
|---|---|---|
| chargeId | string | Settled PaymentIntent id (pi_...). |
| externalId? | string |
fn getCharge(chargeId: string)
Retrieve a charge (GET /v1/payment_intents/{id}).
| Argument | Type | Description |
|---|---|---|
| chargeId | string | PaymentIntent id (pi_...). |
fn listCharges(externalId?: string, createdGte?: number, createdLte?: number, maxResults: number, pageSize: number)
Reconciliation fan-out: list charges by created range
| Argument | Type | Description |
|---|---|---|
| externalId? | string | Filter by metadata externalId (uses /v1/payment_intents/search). |
| createdGte? | number | Unix lower bound. |
| createdLte? | number | Unix upper bound. |
| maxResults | number | |
| pageSize | number |
fn refundCharge(chargeId: string, amount: string, reason?: enum, externalId?: string)
Refund a settled charge (POST /v1/refunds) with
| Argument | Type | Description |
|---|---|---|
| chargeId | string | PaymentIntent id (pi_...) to refund. |
| amount | string | Refund amount, minor units string. Must not exceed the remaining |
| reason? | enum | |
| externalId? | string |
fn getGrantedToken(sptId: string)
Retrieve a granted Shared Payment Token (seller view). Card
| Argument | Type | Description |
|---|---|---|
| sptId | string | Shared Payment Token id (spt_...). |
fn createTestGrantedToken(maxAmount: string, currency: string, paymentMethodId: string, expiresAt?: number)
TEST MODE ONLY: fabricate a granted Shared Payment Token via
| Argument | Type | Description |
|---|---|---|
| maxAmount | string | Usage-limit ceiling, minor units string. |
| currency | string | Usage-limit currency. |
| paymentMethodId | string | Payment method the fabricated granted token draws on (required by the |
| expiresAt? | number |
fn listConsumerPaymentMethods()
List the consumer's Link wallet payment methods (csmrpd_). Fan-out:
fn getSpendRequest(id: string)
Retrieve a consumer spend request by lsrq_ (single-shot; interval 0).
| Argument | Type | Description |
|---|---|---|
| id | string | Spend request id (lsrq_...). |
fn cancelSpendRequest(id: string)
Cancel a PENDING consumer spend request (read-before-cancel). Note:
| Argument | Type | Description |
|---|---|---|
| id | string | Spend request id (lsrq_...). |
fn createSpendRequest(amount: string, currency: string, context: string, networkId?: string, paymentMethodId?: string, externalId?: string)
Create a consumer Link spend request — the PRIMARY (binding) guard
| Argument | Type | Description |
|---|---|---|
| amount | string | Amount to authorise, minor-units STRING (e.g. "500" = $5.00). |
| currency | string | Currency (ISO, lowercase). US-only Link; default usd. |
| context | string | Purchase description + rationale the consumer READS when approving. |
| networkId? | string | Payee Business Network Profile (profile_...). Defaults to the global |
| paymentMethodId? | string | Consumer Link payment method (csmrpd_...). Omit to let the consumer pick |
| externalId? | string | Correlation id; also anchors the deterministic intent key persisted on |
fn paySpendRequest(id: string, maxAmount: string, currency: string, expectedNetworkId?: string, expectedRealm?: string, externalId?: string)
Spend an APPROVED consumer grant against an MPP-protected URL, by
| Argument | Type | Description |
|---|---|---|
| id | string | Approved spend request id (lsrq_...) to spend. |
| maxAmount | string | ADVISORY pre-flight ceiling (minor units). NOTE: the binding cap is the |
| currency | string | Expected challenge currency (advisory). |
| expectedNetworkId? | string | Advisory payee pin for the pre-flight challenge. |
| expectedRealm? | string | Advisory realm pin. |
| externalId? | string | Correlation id. |
Resources
challenge(infinite)— Probe result: HTTP status + parsed payment challenges.
payment(infinite)— Buyer payment attempt — written on EVERY pay outcome (audit trail).
issuedToken(infinite)— Issued Shared Payment Token (buyer view).
challengeSpec(infinite)— Seller challenge material: WWW-Authenticate value + problem+json body.
credential(infinite)— Seller-side credential verification verdict.
charge(infinite)— Seller charge (PaymentIntent) state.
receipt(infinite)— Issued Payment-Receipt header value for a settled charge.
refund(infinite)— Refund outcome — written on every refundCharge attempt (audit trail).
grantedToken(infinite)— Granted Shared Payment Token (seller view; card details trimmed).
summary(infinite)— Fan-out listing summary.
spendRequest(infinite)— Consumer Link spend-request lifecycle — written on EVERY outcome
consumerPaymentMethod(infinite)— Consumer Link payment method (csmrpd_; display as link-cli returns
03Skills
stripe-mpp2 files
04Previous Versions
2026.08.19.1
05Stats
A
100 / 100
Downloads
0
Archive size
244.4 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace06Platforms
07Labels