Skip to main content

Scoped Authorizations

KleePay does not hand agents an unrestricted card. The system is deny-by-default: when a merchant tries to charge a card, the charge is approved only if it matches an active scoped authorization — right amount range, right merchant, inside the time window. Everything else is declined. Authorizations are created and signed by the local signer daemon.

An authorization describes exactly what a payment actor is allowed to do before money moves.

Why deny-by-default matters​

  • Leaked card details are useless. The number, expiry, and CVV alone cannot move money. A charge must match an active authorization's amount, merchant, and time window — stolen details match nothing.
  • Save your card anywhere without worry. Leaving the card with a small merchant or a site you do not fully trust does not expose you: the merchant can only charge what was authorized, when it was authorized, even if their checkout or storage is weak.
  • No surprise charges. A merchant that kept your card on file cannot bill you months later out of the blue. Without a fresh matching authorization, the charge is declined.

This is the key difference from ordinary cards, where possession of the card number is effectively permission to charge it.

One scope note: deny-by-default governs online (card-not-present) charges — the channel agents use through klw. When you tap in person at a physical terminal with Apple Pay or Google Wallet, the card behaves like a normal debit card and no authorization is needed. That path is protected by device tokenization: the wallet stores a device-specific token in the secure chip — never your real card number — and every tap carries a one-time cryptographic proof (plus your phone's own unlock check when you pay with a phone).

Scope fields​

Authorizations can be bounded by:

  • card
  • amount and currency
  • merchant domain or merchant identifier
  • TTL

The agent sees safe card metadata such as card_id, label, last four, status, and balance. Raw PAN and CVV stay out of the agent context.

One-off authorization​

Use kleepay_authorize for a specific payment intent. The default pattern is short-lived and narrow: choose the card, amount, currency, merchant scope, and TTL, then verify the result with transaction or activity tools.

Two amount controls fine-tune how strict the match is:

  • Authorization type: exact (default) matches the exact amount; ceiling allows any charge up to the amount.
  • Drift: a percentage tolerance around the amount (default 25%), for merchants whose final charge differs slightly from the quoted price (taxes, fees, currency rounding). A $12.00 authorization with default drift accepts charges between $9.00 and $15.00. Tighten it for merchants that charge exactly what they quote.

Recurring authorization​

A recurring authorization is used when a merchant or workflow needs repeated charges under explicit constraints. Each cycle derives a bounded child charge.

Examples:

  • SaaS subscriptions
  • usage-based tools
  • recurring infrastructure spend
  • agent-operated services with budget ceilings

Verification authorization​

A verification authorization is used for small first-add merchant verification holds. It validates that a card can be linked before larger spend is authorized.

Verification authorizations should be documented separately from recurring authorizations because the user expectation is different: the goal is validation, not ongoing spend.