MPP

MPP ist das Machine Payments Protocol: ein IETF-Draft (draft-httpauth-payment-00, co-authored Tempo Labs + Stripe, siehe paymentauth.org) der HTTP 402 Payment Required in eine echte, maschinenlesbare Challenge verwandelt. Ovra implementiert die card-Methode als Credential-Issuer. Wenn ein Merchant WWW-Authenticate: Payment ... returnt, kann dein Agent zahlen — ohne ein Formular zu rendern, einen Browser zu öffnen oder eine Kartennummer zu sehen.

Code-complete (Phase 7). Sandbox-only End-to-End. Das Credential-Envelope ist ein echtes JWE; Merchants liefern in ihrem MPP-Onboarding einen Private Key zum Entschlüsseln.

Wire-Flow

Merchant returnt 402

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment challenge="<base64-json>"

Der Challenge-Body deklariert Amount, Currency, Payee, Expiry und Resource-URL.

Agent mintet Credential

Agent ruft POST /v1/mpp/credentials/mint mit der rohen Challenge plus genehmigtem Intent und einer Karte. Ovra mintet ein JWE-wrapped Network-Token gebunden an den Intent.

Agent präsentiert Credential

Agent wiederholt den Request mit Authorization: Payment <credential>.

Merchant entschlüsselt und settlet

Merchant verwendet eigenen Private Key (RSA-OAEP-256 + A256GCM) zum Unwrap von DPAN + Cryptogram, settlet via eigenen Acquirer.

Merchant returnt Payment-Receipt

Der Receipt-Header ist der kanonische Settlement-Record.

Agent verifiziert

Agent ruft POST /v1/mpp/credentials/:id/verify (oder /by-challenge/:challengeId/verify) — Ovra führt CAS-Consume aus, treibt Intent-FSM auf completed, schreibt transactions-Row mit rail = 'mpp', feuert mpp.transaction.completed.

High-Level-Convenience: `POST /v1/mpp/pay`

Für die meisten Agent-Code-Pfade willst du den Roundtrip nicht selbst orchestrieren. Der High-Level-Endpoint macht alles:

curl -X POST https://api.getovra.com/v1/mpp/pay \
  -H "Authorization: Bearer $OVRA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://shop.example.com/api/orders",
    "intentId": "int_...",
    "cardId": "ca_..."
  }'

Was er tut:

GET die URL, erwartet 402 mit MPP-Challenge.
Mintet eine Credential gebunden an intentId + cardId.
Wiederholt den Request mit Authorization: Payment <cred>.
Empfängt Payment-Receipt, ruft Verify, schreibt die Transaktion.

Response (200):

{
  "credential_id": "mppc_a1b2c3...",
  "merchant_status": 200,
  "receipt": "eyJ2ZXJzaW9uIjoiMSIs...",
  "merchant_body": { "order_id": "ord_42" }
}

Low-Level: Mint + Verify

curl -X POST https://api.getovra.com/v1/mpp/credentials/mint \
  -H "Authorization: Bearer $OVRA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "challenge": "Payment challenge=\"eyJ2ZXJzaW9uIjoiMSIs...\"",
    "intentId": "int_...",
    "cardId": "ca_..."
  }'

curl https://shop.example.com/api/orders \
  -H "Authorization: Payment $CREDENTIAL"

curl -X POST https://api.getovra.com/v1/mpp/credentials/$CRED_ID/verify \
  -H "X-Merchant-Key: mer_sk_..."

Error-Matrix

Status	Code	Bedeutung
400	`E_MPP_CRED_MALFORMED_CHALLENGE`	Challenge nicht parsbar
400	`E_MPP_CRED_AMOUNT_MISMATCH`	Intent-Amount ≠ Challenge-Amount
400	`E_MPP_CRED_MERCHANT_MISMATCH`	Intent-Merchant ≠ Challenge-`payTo`
400	`E_MPP_CRED_PAR_REQUIRED`	PAR ist mandatory aber fehlt
403	`E_MPP_CRED_INTENT_NOT_APPROVED`	Intent nicht in `approved`-State
403	`E_MPP_CRED_INTENT_MISMATCH`	Intent-Owner ≠ Caller
404	`E_MPP_CRED_MERCHANT_NOT_FOUND`	Kein Merchant für die Challenge-Realm registriert
410	`E_MPP_CRED_INTENT_EXPIRED`	Intent jenseits `expiresAt`
410	`E_MPP_CRED_CARD_CONSUMED`	Single-use-Card bereits verbrannt
502	`E_UPSTREAM_ERROR`	Card-Issuer- oder PCI-Proxy-Upstream-Failure

Verify-Failures nutzen RFC-9457 Problem Details (application/problem+json) mit Type-URIs invalid-challenge oder verification-failed — niemals ein Oracle. Replays returnen 402 invalid-challenge egal welche Underlying-Cause.

Merchant-Onboarding

Wenn du einen Merchant betreibst der MPP akzeptieren möchte, registriere via POST /v1/merchants mit Invite-Code:

curl -X POST https://api.getovra.com/v1/merchants \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inviteCode": "INVITE-2026-...",
    "name": "Acme Shop",
    "encryptionJwk": { "kty": "RSA", "alg": "RSA-OAEP-256", "use": "enc", ... },
    "webhookUrl": "https://shop.acme.com/ovra/webhooks"
  }'

Response (One-Shot-Reveal, speichern):

{
  "id": "mer_...",
  "slug": "acme-shop",
  "merchant_secret_key": "mer_sk_a1b2c3...",
  "warning": "Save merchant_secret_key now — it will not be shown again."
}

mer_sk_* zum Aufruf von /verify verwenden. Der JWK validiert ausschließlich als RSA-OAEP-256 + A256GCM; Downgrades werden zur Write-Time abgelehnt.

Webhooks

Event	Wann
`mpp.credential.minted`	Credential via `/mint` ausgestellt
`mpp.credential.consumed`	Credential erfolgreich verifiziert
`mpp.credential.expired`	Reserviert (Sweep ist Future Work; Expiry surfaced heute via 410 von Mint und 402 von Verify)
`mpp.transaction.completed`	Verifizierte MPP-Transaktion settled

Sacred Guarantees

Null Card-Data im Agent-Kontext. Das Credential-Envelope ist eine base64url-nopad JWE; nur der Private Key des Merchants kann sie entschlüsseln. Selbst wenn der Agent die volle Mint-Response loggt blutet kein PAN/DPAN/Cryptogram.
Single-use. CAS-Consume bei Verify — Replay returnt 402.
Gebunden an einen Intent. Wiederverwendete Intent-IDs über Challenges hinweg werden mit E_MPP_CRED_INTENT_MISMATCH abgelehnt.

Weiter

CUA

Der andere Pay-Modus — für Merchants ohne MPP.

Pay-Übersicht

Wie MPP und CUA ein Produktnarrativ teilen.

Intents

Die Approval-Primitive an die jede Credential bindet.

Webhooks

mpp.* Events für Echtzeit-Updates abonnieren.

Erste Schritte

Die sechs Säulen

Kern-Primitive

Zahlungsmodi

Plattform

Wire-Flow

High-Level-Convenience: `POST /v1/mpp/pay`

Low-Level: Mint + Verify

Error-Matrix

Merchant-Onboarding

Webhooks

Sacred Guarantees

Weiter

CUA

Pay-Übersicht

Intents

Webhooks

​Wire-Flow

​High-Level-Convenience: POST /v1/mpp/pay

​Low-Level: Mint + Verify

​Error-Matrix

​Merchant-Onboarding

​Webhooks

​Sacred Guarantees

​Weiter

CUA

Pay-Übersicht

Intents

Webhooks

Wire-Flow

High-Level-Convenience: `POST /v1/mpp/pay`

Low-Level: Mint + Verify

Error-Matrix

Merchant-Onboarding

Webhooks

Sacred Guarantees

Weiter