# Cardvera API

> Cardvera is pre-gateway card-testing prevention. Your server signs a short-lived HS256 JWT describing the checkout, the browser loads the Cardvera SDK with it and calls `Cardvera.assess()`, your server verifies the returned verdict JWT before charging the card, and then reports the PSP outcome to `POST https://cardvera.dev/api/outcome`.

Everything is a JWT signed HS256 with the merchant's key. There is no API call to get a token, so most of the integration runs locally on the merchant's server. The only HTTP endpoints are `GET /v1/cv.js?t=<session JWT>`, which the browser loads, and `POST /api/outcome`, which the merchant's server calls. Base URL: `https://cardvera.dev`.

Rules an integration must follow:

- Use the whole issued key string (`cv_sk_p_…`, prefix included) as the HS256 secret. Keep it server-side.
- Pin the algorithm to HS256 on every verify (`algorithms: ["HS256"]`). Never accept `alg: none`.
- Generate a fresh `sid` per checkout render and store `sid → txn` (the order id) on your server.
- Authorize the card only when the verdict JWT verifies, is unexpired, has `action == "allow"`, and has a `txn` equal to the order id you stored for that `sid`. Fail closed on anything else, including an empty token.
- Every token you sign needs `exp`, no more than 30 minutes ahead (60 s clock skew is allowed).
- `amt` is an integer in minor units (cents), never a decimal, and needs `cur` (ISO-4217, upper-case).
- Report every PSP result to `/api/outcome` with a fresh bearer JWT (`iss`, new random `jti`, `iat`, `exp`). Map gateway timeouts to `declined_technical`.

## Docs

- [Full reference (Markdown)](llms-full.txt): the complete docs in one file, including code samples in cURL, Node.js, Python, PHP, Go and C#, and all JSON Schemas. Start here.
- [HTML reference](index.html): the same content as the human-facing page.

## Schemas

- [Session token claims](schemas/session-token.schema.json): the JWT you sign and put on the SDK URL as `?t=`
- [Verdict token claims](schemas/verdict-token.schema.json): the JWT `Cardvera.assess()` returns, which your server verifies
- [Outcome bearer claims](schemas/outcome-bearer.schema.json): the JWT in `Authorization: Bearer` on `POST /api/outcome`
- [Outcome request body](schemas/outcome-request.schema.json): the JSON body of `POST /api/outcome`, including the closed outcome vocabulary
- [Error response](schemas/error.schema.json): the `{ "error": "…" }` body and its codes

## Optional

- [Verified AI agents](index.html#agents): how Cardvera treats shopping agents that sign requests with Web Bot Auth, and the `agt` verdict claim
- [Production checklist](index.html#checklist)