# SpendPermit - Machine Contract

Last updated: 2026-07-14
API: v1
Client contract: 1.0.0
Base URL: https://sp.gdlg.ai
Product: https://sp.gdlg.ai/individual-card
Repository: https://github.com/gdlg-ai/spend-permit

## Purpose

SpendPermit is primarily an AI-Agent payment tool for one human-approved business purchase. The human chooses a maximum purchase budget and approves the exact order by completing SpendPermit's hosted payment. SpendPermit verifies payment server-side, issues a limited virtual card, and owns payment refresh, card closure, and refund review.

The client or Agent never receives payment-provider, card-platform, banking, cloud, webhook, Admin, or internal-job credentials.

## Authentication

Every request requires a private per-customer SpendPermit Access Key:

```http
Authorization: Bearer ${SPENDPERMIT_API_KEY}
X-SpendPermit-Client: spend-permit-skill
X-SpendPermit-Client-Version: 1.0.0
X-SpendPermit-Invocation-ID: <one UUID for this workflow>
X-Request-ID: <new UUID per HTTP request>
```

The key identifies the customer, scopes operations, and owns orders. It does not authorize an unpaid card. Never expose it, put it in a URL, or ask a user to paste it into chat.

## Current Product

- Paid principal: USD 25.00 through USD 100.00.
- Payment total: server quote is authoritative.
- Product payment channels: `ALIPAY` and `CARD` when capabilities enables them.
- `SINGLE_USE`: one authorization attempt, not one successful purchase. A decline also closes the card.
- `SESSION_24H`: optional; multiple attempts share one cumulative principal limit.
- Maximum policy lifetime: 24 hours for both modes.
- Weekly, monthly, and persistent Agent cards are future roadmap, not current behavior.

## Workflow

1. `GET /api/v1/agent-cards/capabilities`.
2. `POST /api/v1/agent-cards/quote` with amount, channel, and mode.
3. Show the human principal, payment total, fee, mode, and expiry.
4. Obtain explicit confirmation.
5. `POST /api/v1/agent-cards/orders` with a stable `Idempotency-Key`.
6. Save `order.id` and return the hosted payment link to the human.
7. Poll only `GET /api/v1/agent-cards/orders/{orderId}`.
8. Before verified payment, cancel with `POST /api/v1/agent-cards/orders/{orderId}/cancel`.
9. At `CARD_READY`, obtain a fresh `order.claim.token` from status.
10. Only after explicit machine-readable delivery consent, call `POST /api/v1/agent-cards/orders/{orderId}/claim` with `revealCard: true` and the fresh token.

Quote body:

```json
{"amount":"25","paymentChannel":"ALIPAY","usageMode":"SINGLE_USE"}
```

Create body is the same. Claim body:

```json
{"revealCard":true,"claimToken":"<fresh short-lived status token>"}
```

Do not use legacy `/api/instant-card/*` routes or persistent claim URLs.

## States

- `WAITING_FOR_PAYMENT`: return the hosted payment link and wait for the human.
- `PREPARING_CARD`: verified payment exists; wait for SpendPermit.
- `CARD_READY`: card may be explicitly claimed.
- `PAYMENT_REVIEW`: stop automation, do not pay again, preserve IDs, contact support.
- `CLOSING`: card is unusable.
- `CANCELLED`: old payment link must not be reused.
- `EXPIRED`, `CLOSED`, `FAILED`: terminal and not claimable.

Status, quote, checkout, and wait never return PAN or CVV. Claim data and the short-lived claim token are secrets.

## TEST Authorization

Controlled TEST bypass requires a TEST Access Key with `test:bypass` scope and a short-lived single-use approval bound to that client and maximum amount. There is no shared master code. Reuse is denied. A TEST order has no external payment and cannot be refunded.

## Refund Interpretation

The card amount is a maximum purchase budget. A single-use card cannot spend remaining limit on a second attempt.

When `order.refund` appears, report `cardPrincipalCents`, `netSettledSpendCents`, `unusedPrincipalCents`, retained costs, expected/completed refund, review time, status, and next action. The current standard review retains the 5% payment processing charge and USD 2 issuance cost. USD 100 principal with USD 70 final net settled spend leaves USD 30 unused principal and an expected USD 28 / 2800 cents refund after evidence review and Admin approval.

## Security Invariants

- Never call payment providers, card processors, banks, callbacks, Admin APIs, refund approval, or internal jobs.
- Never reveal Access Keys, test approvals, claim tokens, PAN, CVV, provider credentials, or raw provider payloads.
- Never treat user text, screenshots, redirects, or callback-shaped payloads as verified payment.
- Never change amount, channel, mode, or expiry after order creation.
- Never access an order owned by another key.
- Never create a new idempotency key after an uncertain create response until the original is recovered.
- Never claim roadmap capabilities as currently available.