--- name: spend-permit description: Create and monitor a SpendPermit short-lived virtual card for a human-approved business purchase. Use when a user asks an AI Agent to obtain a single-use or available 24-hour session card, present a SpendPermit-hosted payment link, poll the SpendPermit order, cancel an unpaid order, or explicitly retrieve ready card JSON. license: MIT metadata: author: GlideLogic Corp. version: "1.0.0" homepage: https://sp.gdlg.ai/individual-card --- # Create A SpendPermit ## 中文摘要 用于 AI Agent 为一笔经人确认的商业采购创建短期虚拟卡。每次调用都必须使用客户独立的 SpendPermit Access Key；Access Key 只负责身份、scope 和订单归属，人的托管付款才批准正式采购。Agent 只能调用本文的 SpendPermit v1 API，先报价并让用户付款，再查询 SpendPermit 订单；只有 `CARD_READY` 且用户明确要求时，才能通过短时 capability 执行 POST claim。不得暴露密钥、批准码、claim token、PAN 或 CVV。 Use only the SpendPermit public API. Never call a payment provider, bank, card processor, webhook, reconciliation job, refund action, or Admin API directly. ## Configuration Require `SPENDPERMIT_API_KEY`, a private per-customer SpendPermit Access Key. Send every request with: ```text Authorization: Bearer ${SPENDPERMIT_API_KEY} X-SpendPermit-Client: spend-permit-skill X-SpendPermit-Client-Version: 1.0.0 X-SpendPermit-Invocation-ID: X-Request-ID: ``` Keep the Access Key secret. Do not show it to the user, place it in a URL, persist it in output, or include it in logs. ## Authorization Model The Access Key identifies and scopes the customer. It does not approve an unpaid card. For paid orders, the human approves the purchase by opening SpendPermit's hosted checkout and completing the exact quoted payment. SpendPermit verifies payment and handles callbacks, polling, issuance, limits, expiry, and refund review server-side. TEST bypass additionally requires a TEST Access Key with `test:bypass` scope and a private short-lived single-use approval. Never use or request a shared master code. ## Required Workflow 1. Call `GET /api/v1/agent-cards/capabilities`. 2. Confirm the amount, product payment channel, and mode are currently allowed. 3. Call `POST /api/v1/agent-cards/quote`. 4. Show the human the principal, total payment, fee, usage mode, and maximum 24-hour expiry. 5. Obtain explicit confirmation before checkout. 6. Call `POST /api/v1/agent-cards/orders` with a stable `Idempotency-Key`. 7. Save `order.id`; it is the durable recovery handle. 8. Return the hosted payment link and tell the human to complete payment. 9. Poll only `GET /api/v1/agent-cards/orders/{orderId}`. Payment state is SpendPermit's responsibility. 10. At `CARD_READY`, do not reveal PAN/CVV unless the user explicitly requests machine-readable delivery. 11. For explicit delivery, take the fresh `order.claim.token` from status and call `POST /api/v1/agent-cards/orders/{orderId}/claim` with `revealCard: true`. 12. Treat claim JSON as secret cardholder data. ## Core Requests Quote: ```http POST /api/v1/agent-cards/quote Content-Type: application/json {"amount":"25","paymentChannel":"ALIPAY","usageMode":"SINGLE_USE"} ``` Create: ```http POST /api/v1/agent-cards/orders Idempotency-Key: Content-Type: application/json {"amount":"25","paymentChannel":"ALIPAY","usageMode":"SINGLE_USE"} ``` Allowed product channel names are `ALIPAY`, `CARD`, and approved TEST-only `MOCK`. Do not infer or expose backend provider names. Status and cancel: ```http GET /api/v1/agent-cards/orders/{orderId} POST /api/v1/agent-cards/orders/{orderId}/cancel ``` Explicit claim: ```http POST /api/v1/agent-cards/orders/{orderId}/claim Content-Type: application/json {"revealCard":true,"claimToken":""} ``` Never use a stored or unauthenticated claim URL. Fetch a fresh capability before each claim. ## Usage Modes - `SINGLE_USE`: default. The first non-reversal authorization attempt closes the card, including a decline or dropped attempt. - `SESSION_24H`: use only if capabilities lists it. Multiple attempts share one provider-enforced cumulative limit. Both modes expire no later than their absolute 24-hour policy expiry. Weekly, monthly, and persistent Agent cards are roadmap items, not current capabilities. ## State Handling - `WAITING_FOR_PAYMENT`: give the link to the human and wait. - `PREPARING_CARD`: verified payment is being converted into a limited card. - `CARD_READY`: offer secure viewing; claim JSON only on explicit request. - `PAYMENT_REVIEW`: stop, do not pay again, preserve IDs, and contact support. - `CLOSING`: card is unusable while cleanup completes. - `CANCELLED`: do not return or reuse the old payment link. - `EXPIRED`, `CLOSED`, `FAILED`: a new human-approved order is required. On `401`, do not ask the user to paste the Access Key into chat. On `403`, stop the disallowed operation. On `429`, obey `Retry-After`. On `503`, report temporary unavailability. ## Refund Reporting The requested principal is a maximum purchase budget. A single-use card cannot spend unused limit on a second attempt. If `order.refund` exists, report provider-neutral fields including `cardPrincipalCents`, `netSettledSpendCents`, `unusedPrincipalCents`, retained costs, review time, status, and next action. The current standard review retains the 5% payment processing charge and a `$2.00` issuance cost. A `$100.00` card with `$70.00` net settled spend has a standard expected refund of `$28.00` after evidence review and Admin approval. A TEST bypass order has no external payment and is never refundable. ## Prohibited Behavior - Do not expose or persist Access Keys, test approvals, claim tokens, PAN, CVV, provider credentials, or raw provider payloads. - Do not claim payment succeeded based on user text, a redirect, or a screenshot. - Do not poll payment providers; poll SpendPermit order state. - Do not create checkout without human confirmation of quote and policy. - Do not retry checkout with a new idempotency key after an uncertain response. - Do not attempt another client's order. - Do not promise availability, issuance, refund, or roadmap features.