# SpendPermit: Complete English Guide [Project home](../README.md) · [中文指南](USAGE.zh-CN.md) · [Product](https://sp.gdlg.ai/individual-card) · [Machine contract](../llms.txt) ## 1. Product Model SpendPermit creates a short-lived, precisely limited virtual card for a human-approved business purchase. The customer does not need a full Card Portal account. The AI Agent may prepare the purchase, but the human remains the spender of record: 1. The Agent obtains a SpendPermit quote and explains the amount and policy. 2. The human confirms and completes SpendPermit's hosted payment. 3. SpendPermit verifies payment server-side and records an immutable purchase authorization. 4. SpendPermit issues a card and enforces the exact cumulative limit and expiry. 5. The Agent polls SpendPermit, then claims card JSON only with explicit consent. An Access Key identifies the customer and owns the order. It does not approve an unpaid card. ## 2. Good And Poor Fits Good fits: - One authorized online business purchase prepared by an Agent. - A known safe maximum but uncertain tax, shipping, conversion, or final capture. - A business that does not want to expose a reusable company card. - A purchase that fits USD 25 through USD 100 and can complete within 24 hours. Poor fits: - Personal or household spending. - Subscriptions, free trials, recurring billing, or multiple purchases. - Hotels, rentals, deposits, fuel pumps, split shipments, and incremental authorization. - Merchants likely to retry a failed authorization when `SINGLE_USE` is selected. - Any attempt to avoid identity, merchant, compliance, or banking controls. Review [real scenarios and anti-scenarios](SCENARIOS.md) before the first order. ## 3. Access And Security Obtain a private, per-customer `SPENDPERMIT_API_KEY` from the SpendPermit operator. It is scoped, rate-limited, independently revocable, and can access only its owner's orders. macOS/Linux: ```bash export SPENDPERMIT_API_KEY="" ``` PowerShell: ```powershell $env:SPENDPERMIT_API_KEY = "" ``` Do not store the key in source, prompts, screenshots, shell history, logs, or public repositories. The repository and CLI contain no payment, card-platform, bank, webhook, cloud, Admin, or internal-job credentials. ## 4. Channels And Usage Modes Use product-level channels only: - `ALIPAY`: hosted Alipay checkout. - `CARD`: hosted international card checkout. - `MOCK`: controlled TEST-only approval flow. Always call `capabilities`; a documented channel may be temporarily unavailable. Usage modes: - `SINGLE_USE`: default. The first authorization attempt closes the card, including a decline or dropped attempt. - `SESSION_24H`: only when capabilities lists it. Multiple attempts share one cumulative principal limit. Both modes close no later than the absolute 24-hour policy expiry. Weekly, monthly, and persistent Agent cards remain roadmap items. ## 5. Browser Flow 1. Open . 2. Enter the private SpendPermit Access Key. The server exchanges it for a secure browser session; the plaintext key is not placed in the URL or cookie. 3. Choose amount, enabled channel, and enabled mode. 4. Review principal, payment total, fee, usage behavior, and expiry. 5. Create checkout and save the order ID. 6. Complete payment on the hosted page. 7. Return to status. Do not pay again because a callback is delayed. 8. When ready, use the protected browser claim or explicit CLI claim. 9. End browser access when finished. Cancel before verified payment if the purchase will not proceed. Never reuse an old payment link after cancellation. ## 6. CLI Flow Requirements: Node.js 18 or newer on Windows, macOS, or Linux. ```bash node cli/spend-permit.mjs capabilities node cli/spend-permit.mjs quote 25 --channel card --mode single-use node cli/spend-permit.mjs checkout 25 --channel card --mode single-use ``` Record `order.id`. The human completes `order.payment.checkoutUrl`. The Agent and CLI poll only SpendPermit: ```bash node cli/spend-permit.mjs status ORDER_ID node cli/spend-permit.mjs wait ORDER_ID ``` Cancel an unpaid order: ```bash node cli/spend-permit.mjs cancel ORDER_ID ``` Explicit machine-readable claim after `CARD_READY`: ```bash node cli/spend-permit.mjs claim ORDER_ID --reveal-card ``` The claim command fetches a fresh short-lived capability and performs an authenticated POST. It does not use a persistent claim URL. Never send its output to logs, issues, source repositories, or shared chat. ## 7. Public API All requests use: ```http Authorization: Bearer ``` Endpoints: ```text GET /api/v1/agent-cards/capabilities POST /api/v1/agent-cards/quote POST /api/v1/agent-cards/orders GET /api/v1/agent-cards/orders/{orderId} POST /api/v1/agent-cards/orders/{orderId}/cancel POST /api/v1/agent-cards/orders/{orderId}/claim ``` Create requires a stable `Idempotency-Key`. Reuse it after an uncertain response; do not create another key until the original order is recovered or conclusively absent. Never call legacy, callback, internal, Admin, refund, or maintenance endpoints. ## 8. States | State | Meaning | Action | | --- | --- | --- | | `WAITING_FOR_PAYMENT` | Human payment required | Return hosted link and wait | | `PREPARING_CARD` | Verified payment; card preparation | Poll SpendPermit only | | `CARD_READY` | Fresh claim capability available | Claim only with explicit consent | | `PAYMENT_REVIEW` | Payment evidence conflict | Stop; do not pay again; contact support | | `CLOSING` | Card unusable; cleanup pending | Wait | | `CANCELLED` | Unpaid order cancelled | Do not reuse old link | | `CLOSED` / `EXPIRED` / `FAILED` | Terminal | Do not claim or use | `quote`, `checkout`, `status`, and `wait` never return PAN or CVV. ## 9. Refund Boundary The card principal is a maximum purchase budget, not a promise that the merchant settles the full amount. A single-use card cannot use remaining limit for a second purchase. At the original 24-hour review point, SpendPermit evaluates final settled spend, pending authorization, card closure, and payment evidence. The current standard retains the 5% payment processing charge and USD 2 issuance cost. Example: USD 100 principal, USD 70 net settled spend, USD 30 `unusedPrincipalCents`, and USD 28 expected refund after evidence review and Admin approval. Refund returns only to the original payment method and is not immediate or guaranteed before review. TEST orders have no external payment and are never refundable. ## 10. Error Handling - `401`: credential missing or invalid; never ask the user to paste it into chat. - `403`: client inactive, wrong scope, wrong environment, or disallowed action; stop. - `404 ORDER_NOT_FOUND`: absent or not owned by this client. - `409`: replay, order-state conflict, or payment review; preserve IDs and stop unsafe retries. - `429`: obey `Retry-After`. - `503`: product, channel, security configuration, or session controls unavailable. ## 11. TEST Flow TEST bypass requires a TEST Access Key with `test:bypass` scope and a short-lived single-use approval privately issued for that client and maximum amount. ```bash export SPENDPERMIT_TEST_APPROVAL_CODE="" node cli/spend-permit.mjs checkout 10 --channel bypass ``` There is no shared master code. The approval is consumed atomically by the first accepted order, replay is denied, and no external payment means no refund.