Wallet quickstart

The Wallet Portal is the principal's control plane. The reference implementation runs at wallet.oid4pay.com; you can also operate your own wallet against the OID4Pay AS. This page is the operator-level guide.

What a wallet does

1. Authenticates the principal (password + WebAuthn 2FA in the reference impl).
2. Registers agents on behalf of the principal (RFC 7591 DCR through the AS).
3. Renders consent screens for incoming PAR requests.
4. Stores the SD-JWT VC mandates the AS issues at consent time.
5. Presents mandates to merchants at charge time (or proxies the agent's KB-JWT minting).
6. Surfaces audit, dispute, and revocation tooling for the principal.

Step 1: register as an OIDC RP with the AS

curl -sS https://as.oid4pay.com/oauth/register \
  -H "content-type: application/json" \
  -d '{
    "client_name": "my-wallet",
    "token_endpoint_auth_method": "private_key_jwt",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "redirect_uris": ["https://my-wallet.example.com/callback"],
    "scope": "openid email profile wallet:read wallet:write",
    "jwks": {"keys": [...]}
  }'

Step 2: implement the OIDC login flow

The wallet acts as an OIDC RP against the AS for principal authentication. Required scopes are openid, email, profile, wallet:read, wallet:write. PKCE S256 is mandatory; nonce and state are mandatory. See OIDC discovery metadata for the full contract.

Step 3: implement the consent screen

When an agent posts a PAR with authorization_details of type oid4ac_mandate, the wallet's consent screen MUST render:

• The agent's client_name from DCR.
• The merchant's display_name from the Discovery directory.
• The Offer body in plain language: SKU, item name, price, currency.
• The mandate scope: spend cap, currency, merchant allowlist, validity.
• An approve / decline button with WebAuthn re-auth required.

Step 4: issue the SD-JWT VC mandate

On approval the wallet calls the AS /oauth/authorize endpoint with the consent decision; the AS issues the SD-JWT VC mandate. The wallet stores the compact form keyed by mandate_id. See the SD-JWT VC mandate for the mandate contract.

Step 5: implement the audit + revocation surface

• List active mandates with their spend_cap_minor, current spent total, and merchant scope.
• Revoke any mandate (POST to the /oauth/revoke endpoint).
• Show the principal's audit log (the per-tenant audit chain entries scoped to actor.type=account and matching actor.id).
• Surface dispute filing (links to the merchant's dispute address plus the four-signature evidence pack).

Step 6: register the wallet in the Wallet Registry (planned)

Once the Wallet Registry lands, your wallet identity is verified against a JWKS the AS publishes; until then, agent registration is wallet-agnostic (any RP can issue mandates against the same AS).

Reference

• The reference wallet is open source and built on SvelteKit and Bun.
• The OIDC contract: OIDC discovery metadata.
• The mandate wire shape: SD-JWT VC mandate.