Stop card testing before it reaches your gateway.

<!-- 1. Your server signed this JWT and put it on the URL -->
<script src="https://cardvera.dev/v1/cv.js?t=eyJhbGciOiJIUzI1NiJ9…"></script>

<script>
  // 2. At submit, ask Cardvera for a verdict.
  form.addEventListener('submit', async (e) => {
    e.preventDefault();
    const v = await Cardvera.assess();
    // v = { action: 'allow' | 'block', token: '<verdict JWT>' }

    // 3. Hand the verdict JWT to YOUR server with the rest of
    //    checkout. Your server verifies it before charging.
    hidden('cvToken', v.token);
    form.submit();
  });
</script>

# A JWT is base64url(header).base64url(payload).base64url(HMAC).
# Any JWT tool works (jwt.io, jwt-cli); with openssl by hand:
b64() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
KEY="cv_sk_p_test_0000111122223333"
H=$(printf '{"alg":"HS256","typ":"JWT"}' | b64)
P=$(printf '{"iss":"acct_7f2a","sid":"9c1d…","txn":"ORD-1","flow":"full_checkout","ident":"guest","iat":%s,"exp":%s}' \
      "$(date +%s)" "$(( $(date +%s) + 1800 ))" | b64)
S=$(printf '%s.%s' "$H" "$P" | openssl dgst -sha256 -hmac "$KEY" -binary | b64)
echo "$H.$P.$S"

import jwt from "jsonwebtoken";        // npm i jsonwebtoken

const KEY = process.env.CARDVERA_KEY;  // cv_sk_p_… (whole string)

const token = jwt.sign(
  { iss: "acct_7f2a", sid, txn, flow: "full_checkout", ident: "guest" },
  KEY,
  { algorithm: "HS256", expiresIn: "30m" }
);

import jwt, time   # pip install pyjwt

KEY = os.environ["CARDVERA_KEY"]       # cv_sk_p_… (whole string)

token = jwt.encode(
    {"iss": "acct_7f2a", "sid": sid, "txn": txn,
     "flow": "full_checkout", "ident": "guest",
     "iat": int(time.time()), "exp": int(time.time()) + 1800},
    KEY, algorithm="HS256")

<?php
use Firebase\JWT\JWT;                    // composer require firebase/php-jwt

$key = getenv('CARDVERA_KEY');          // cv_sk_p_… (whole string)
$now = time();
$token = JWT::encode([
  'iss' => 'acct_7f2a', 'sid' => $sid, 'txn' => $txn,
  'flow' => 'full_checkout', 'ident' => 'guest',
  'iat' => $now, 'exp' => $now + 1800,
], $key, 'HS256');

import "github.com/golang-jwt/jwt/v5"   // go get github.com/golang-jwt/jwt/v5

key := []byte(os.Getenv("CARDVERA_KEY")) // cv_sk_p_… (whole string)
tok := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
    "iss": "acct_7f2a", "sid": sid, "txn": txn,
    "flow": "full_checkout", "ident": "guest",
    "iat": time.Now().Unix(), "exp": time.Now().Add(30 * time.Minute).Unix(),
})
token, _ := tok.SignedString(key)

using JWT.Builder;   // dotnet add package JWT
using JWT.Algorithms;

var key = Environment.GetEnvironmentVariable("CARDVERA_KEY"); // whole string
var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
var token = JwtBuilder.Create()
    .WithAlgorithm(new HMACSHA256Algorithm())
    .WithSecret(key)
    .AddClaim("iss", "acct_7f2a").AddClaim("sid", sid).AddClaim("txn", txn)
    .AddClaim("flow", "full_checkout").AddClaim("ident", "guest")
    .AddClaim("iat", now).AddClaim("exp", now + 1800)
    .Encode();

{
  "iss":   "acct_7f2a",
  "sid":   "9c1d4e77b0a3f5628d10c4ba9e73f001",
  "txn":   "ORD-20260921-abc123",
  "flow":  "full_checkout",
  "ident": "authenticated_new",
  "sub":   "3f1c9a0b7d2e4f6a…",
  "amt":   31104,
  "cur":   "USD",
  "iat":   1787000000,
  "exp":   1787001800
}
// HS256, signed with your key -> the "t" URL parameter

# A JWT is just base64url(header).base64url(payload).HMAC — buildable
# with openssl, but any JWT tool (jwt-cli, jwt.io) is easier. Helpers:
KEY="cv_sk_p_test_0000111122223333"; AID="acct_7f2a"; HOST="https://cardvera.dev"
b64() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
jwt() { # $1 = payload JSON
  local h p s; h=$(printf '{"alg":"HS256","typ":"JWT"}' | b64); p=$(printf '%s' "$1" | b64)
  s=$(printf '%s.%s' "$h" "$p" | openssl dgst -sha256 -hmac "$KEY" -binary | b64)
  printf '%s.%s.%s' "$h" "$p" "$s"; }

# 1 · MINT — session token -> SDK URL. Persist SID -> TXN yourself.
SID=$(openssl rand -hex 16); TXN="ORD-20260921-abc123"; NOW=$(date +%s)
T=$(jwt "{\"iss\":\"$AID\",\"sid\":\"$SID\",\"txn\":\"$TXN\",\"flow\":\"full_checkout\",\"ident\":\"guest\",\"amt\":31104,\"cur\":\"USD\",\"iat\":$NOW,\"exp\":$((NOW+1800))}")
echo "$HOST/v1/cv.js?t=$T"

# 2 · VERIFY the verdict JWT — pin HS256, then check claims yourself.
#     Easiest with a real JWT lib; conceptually:
#       verify signature with KEY (alg HS256 only)
#       exp not passed; claims.txn == your stored order id; claims.action == "allow"

# 3 · REPORT — bearer JWT + data-only body.
OT=$(jwt "{\"iss\":\"$AID\",\"jti\":\"$(openssl rand -hex 16)\",\"iat\":$(date +%s),\"exp\":$(( $(date +%s)+300 ))}")
curl -sS -X POST "$HOST/api/outcome" -H "Authorization: Bearer $OT" \
  -H 'Content-Type: application/json' -d @- <<JSON
{ "sessionId":"$SID","outcomeType":"auth","outcome":"declined_fraud",
  "occurredAt":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","outcomeId":"psp_abc" }
JSON

import jwt from "jsonwebtoken";          // npm i jsonwebtoken
import crypto from "node:crypto";

const AID = "acct_7f2a";
const KEY = process.env.CARDVERA_KEY;    // cv_sk_p_… (whole string)
const HOST = "https://cardvera.dev";

// 1 · MINT — returns { url, sid }. Persist sid -> txn yourself.
export function mintSdkUrl({ txn, flow = "full_checkout", ident = "guest", sub, amt, cur }) {
  const sid = crypto.randomBytes(16).toString("hex");
  const claims = { iss: AID, sid, txn, flow, ident };
  if (sub) claims.sub = sub;
  if (amt != null) { claims.amt = amt; claims.cur = cur || "USD"; }
  const t = jwt.sign(claims, KEY, { algorithm: "HS256", expiresIn: "30m" });
  return { url: `${HOST}/v1/cv.js?t=${t}`, sid };
}

// 2 · VERIFY — expectedTxn is the order id YOU stored for this sid.
export function verifyVerdict(token, expectedTxn) {
  try {
    const c = jwt.verify(token, KEY, { algorithms: ["HS256"] }); // pin HS256
    return c.action === "allow" && c.txn === expectedTxn ? c : null;
  } catch { return null; }                 // bad sig, expired, wrong alg
}

// 3 · REPORT — bearer JWT + data-only body.
export async function reportOutcome(sid, outcomeType, outcome, outcomeId) {
  const bearer = jwt.sign({ iss: AID, jti: crypto.randomBytes(16).toString("hex") },
    KEY, { algorithm: "HS256", expiresIn: "5m" });
  await fetch(`${HOST}/api/outcome`, {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${bearer}` },
    body: JSON.stringify({ sessionId: sid, outcomeType, outcome,
      occurredAt: new Date().toISOString(), outcomeId }),
  });
}

import jwt, os, secrets, time, urllib.request, json   # pip install pyjwt

AID  = "acct_7f2a"
KEY  = os.environ["CARDVERA_KEY"]        # cv_sk_p_… (whole string)
HOST = "https://cardvera.dev"

# 1 · MINT — returns (url, sid). Persist sid -> txn yourself.
def mint_sdk_url(txn, flow="full_checkout", ident="guest", sub=None, amt=None, cur="USD"):
    sid = secrets.token_hex(16); now = int(time.time())
    claims = {"iss": AID, "sid": sid, "txn": txn, "flow": flow, "ident": ident,
              "iat": now, "exp": now + 1800}
    if sub: claims["sub"] = sub
    if amt is not None: claims["amt"] = amt; claims["cur"] = cur
    t = jwt.encode(claims, KEY, algorithm="HS256")
    return f"{HOST}/v1/cv.js?t={t}", sid

# 2 · VERIFY — expected_txn is the order id YOU stored for this sid.
def verify_verdict(token, expected_txn):
    try:
        c = jwt.decode(token, KEY, algorithms=["HS256"])   # pin HS256
    except jwt.InvalidTokenError:
        return None                                        # bad sig / expired / wrong alg
    return c if c.get("action") == "allow" and c.get("txn") == expected_txn else None

# 3 · REPORT — bearer JWT + data-only body.
def report_outcome(sid, outcome_type, outcome, outcome_id=None):
    now = int(time.time())
    bearer = jwt.encode({"iss": AID, "jti": secrets.token_hex(16),
                         "iat": now, "exp": now + 300}, KEY, algorithm="HS256")
    body = {"sessionId": sid, "outcomeType": outcome_type, "outcome": outcome,
            "occurredAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "outcomeId": outcome_id}
    req = urllib.request.Request(f"{HOST}/api/outcome", method="POST",
        data=json.dumps(body).encode(),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {bearer}"})
    urllib.request.urlopen(req, timeout=3)

<?php
use Firebase\JWT\JWT;                     // composer require firebase/php-jwt
use Firebase\JWT\Key;

const CV_AID = 'acct_7f2a';
const CV_HOST = 'https://cardvera.dev';
function cv_key(): string { return getenv('CARDVERA_KEY'); }   // whole string

// 1 · MINT — returns ['url' => ..., 'sid' => ...]. Persist sid -> txn.
function cv_mint(string $txn, string $flow = 'full_checkout', string $ident = 'guest',
                 ?string $sub = null, ?int $amt = null, string $cur = 'USD'): array {
  $sid = bin2hex(random_bytes(16)); $now = time();
  $claims = ['iss' => CV_AID, 'sid' => $sid, 'txn' => $txn, 'flow' => $flow,
             'ident' => $ident, 'iat' => $now, 'exp' => $now + 1800];
  if ($sub !== null) $claims['sub'] = $sub;
  if ($amt !== null) { $claims['amt'] = $amt; $claims['cur'] = $cur; }
  $t = JWT::encode($claims, cv_key(), 'HS256');
  return ['url' => CV_HOST . "/v1/cv.js?t=$t", 'sid' => $sid];
}

// 2 · VERIFY — $expectedTxn is the order id YOU stored for this sid.
function cv_verify(string $token, string $expectedTxn): ?object {
  try { $c = JWT::decode($token, new Key(cv_key(), 'HS256')); }  // pin HS256
  catch (\Throwable $e) { return null; }                        // bad sig / expired
  return ($c->action === 'allow' && $c->txn === $expectedTxn) ? $c : null;
}

// 3 · REPORT — bearer JWT + data-only body.
function cv_report(string $sid, string $type, string $outcome, ?string $outcomeId = null): void {
  $now = time();
  $bearer = JWT::encode(['iss' => CV_AID, 'jti' => bin2hex(random_bytes(16)),
                         'iat' => $now, 'exp' => $now + 300], cv_key(), 'HS256');
  $body = ['sessionId' => $sid, 'outcomeType' => $type, 'outcome' => $outcome,
           'occurredAt' => gmdate('Y-m-d\TH:i:s\Z'), 'outcomeId' => $outcomeId];
  $c = curl_init(CV_HOST . '/api/outcome');
  curl_setopt_array($c, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', "Authorization: Bearer $bearer"],
    CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 3]);
  curl_exec($c); curl_close($c);
}

package cardvera
// go get github.com/golang-jwt/jwt/v5
import ( "bytes"; "crypto/rand"; "encoding/hex"; "encoding/json"; "fmt"
         "net/http"; "os"; "time"; "github.com/golang-jwt/jwt/v5" )

const aid, host = "acct_7f2a", "https://cardvera.dev"
func key() []byte { return []byte(os.Getenv("CARDVERA_KEY")) }   // whole string
func randHex() string { b := make([]byte, 16); rand.Read(b); return hex.EncodeToString(b) }

// 1 · MINT — returns url, sid. Persist sid -> txn yourself.
func MintSdkURL(txn, flow, ident string, amt int64, cur string) (string, string) {
    sid := randHex()
    claims := jwt.MapClaims{ "iss": aid, "sid": sid, "txn": txn, "flow": flow,
        "ident": ident, "iat": time.Now().Unix(), "exp": time.Now().Add(30 * time.Minute).Unix() }
    if amt > 0 { claims["amt"] = amt; claims["cur"] = cur }
    t, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(key())
    return fmt.Sprintf("%s/v1/cv.js?t=%s", host, t), sid
}

// 2 · VERIFY — expectedTxn is the order id YOU stored for this sid.
func VerifyVerdict(token, expectedTxn string) (jwt.MapClaims, bool) {
    t, err := jwt.Parse(token, func(*jwt.Token) (any, error) { return key(), nil },
        jwt.WithValidMethods([]string{"HS256"}))          // pin HS256
    if err != nil || !t.Valid { return nil, false }
    c := t.Claims.(jwt.MapClaims)
    return c, c["action"] == "allow" && c["txn"] == expectedTxn
}

// 3 · REPORT — bearer JWT + data-only body.
func ReportOutcome(sid, outcomeType, outcome, outcomeID string) error {
    bearer, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
        "iss": aid, "jti": randHex(), "iat": time.Now().Unix(),
        "exp": time.Now().Add(5 * time.Minute).Unix() }).SignedString(key())
    body, _ := json.Marshal(map[string]any{ "sessionId": sid, "outcomeType": outcomeType,
        "outcome": outcome, "occurredAt": time.Now().UTC().Format(time.RFC3339), "outcomeId": outcomeID })
    req, _ := http.NewRequest("POST", host+"/api/outcome", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+bearer)
    _, err := http.DefaultClient.Do(req)
    return err
}

// dotnet add package JWT
using JWT.Builder; using JWT.Algorithms; using System.Security.Cryptography;

public static class Cardvera {
    const string Aid = "acct_7f2a";
    const string Host = "https://cardvera.dev";
    static string Key => Environment.GetEnvironmentVariable("CARDVERA_KEY")!;  // whole string
    static readonly HttpClient Http = new();
    static long Now() => DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    static string RandHex() => Convert.ToHexStringLower(RandomNumberGenerator.GetBytes(16));

    // 1 · MINT — returns (url, sid). Persist sid -> txn yourself.
    public static (string Url, string Sid) MintSdkUrl(string txn, string flow = "full_checkout",
            string ident = "guest", string? sub = null, long? amt = null, string cur = "USD") {
        var sid = RandHex();
        var b = JwtBuilder.Create().WithAlgorithm(new HMACSHA256Algorithm()).WithSecret(Key)
            .AddClaim("iss", Aid).AddClaim("sid", sid).AddClaim("txn", txn)
            .AddClaim("flow", flow).AddClaim("ident", ident)
            .AddClaim("iat", Now()).AddClaim("exp", Now() + 1800);
        if (sub is not null) b.AddClaim("sub", sub);
        if (amt is not null) { b.AddClaim("amt", amt); b.AddClaim("cur", cur); }
        return ($"{Host}/v1/cv.js?t={b.Encode()}", sid);
    }

    // 2 · VERIFY — expectedTxn is the order id YOU stored for this sid.
    public static IDictionary<string, object>? VerifyVerdict(string token, string expectedTxn) {
        try {
            var c = JwtBuilder.Create().WithAlgorithm(new HMACSHA256Algorithm())  // pin HS256
                .WithSecret(Key).MustVerifySignature()
                .Decode<IDictionary<string, object>>(token);
            return (string)c["action"] == "allow" && (string)c["txn"] == expectedTxn ? c : null;
        } catch { return null; }
    }

    // 3 · REPORT — bearer JWT + data-only body.
    public static async Task ReportOutcome(string sid, string type, string outcome, string? outcomeId = null) {
        var bearer = JwtBuilder.Create().WithAlgorithm(new HMACSHA256Algorithm()).WithSecret(Key)
            .AddClaim("iss", Aid).AddClaim("jti", RandHex())
            .AddClaim("iat", Now()).AddClaim("exp", Now() + 300).Encode();
        var body = System.Text.Json.JsonSerializer.Serialize(new { sessionId = sid,
            outcomeType = type, outcome, occurredAt = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"), outcomeId });
        var req = new HttpRequestMessage(HttpMethod.Post, $"{Host}/api/outcome") {
            Content = new StringContent(body, System.Text.Encoding.UTF8, "application/json") };
        req.Headers.Add("Authorization", $"Bearer {bearer}");
        await Http.SendAsync(req);
    }
}

// 1 · Session (you sign; on the SDK URL as ?t=)
{ "iss":"acct_7f2a", "sid":"9c1d…", "txn":"ORD-1",
  "flow":"full_checkout", "ident":"guest",
  "sub":"…", "amt":31104, "cur":"USD", "iat":…, "exp":… }

// 2 · Verdict (Cardvera signs with YOUR key; you verify)
{ "iss":"cardvera", "action":"allow", "sid":"9c1d…",
  "txn":"ORD-1", "iat":…, "exp":… }

// 3 · Outcome bearer (you sign; Authorization: Bearer)
{ "iss":"acct_7f2a", "jti":"<fresh nonce>", "iat":…, "exp":… }

GET https://cardvera.dev/v1/cv.js?t=eyJhbGciOiJIUzI1NiJ9.eyJpc3Mi…

200  application/javascript      -> serves the SDK
400  { "error": "missing_token" }   -> no t param
400  { "error": "invalid_claims" }  -> unknown flow/ident, missing txn
403  { "error": "invalid_token" }   -> bad signature, wrong alg, or expired

<!-- URL minted by your server (see Quickstart) -->
<script src="https://cardvera.dev/v1/cv.js?t=eyJhbGciOiJIUzI1NiJ9…"></script>

<script>
  const form = document.getElementById('checkout');
  form.addEventListener('submit', async (e) => {
    e.preventDefault();
    let token = '';
    try {
      const v = await Cardvera.assess();  // { action, token }
      token = v.token;
    } catch (err) {
      // network/SDK failure -> empty token -> server fails closed
    }
    setHidden('cvToken', token);
    form.submit();   // POST to your server; verify there
  });
</script>

{
  "iss":    "cardvera",
  "action": "allow",     // or "block"
  "sid":    "9c1d4e77b0a3f5628d10c4ba9e73f001",
  "txn":    "ORD-20260921-abc123",
  "iat":    1787000019,
  "exp":    1787000319,
  "agt":    {            // only when a verified AI agent drove the session
    "op":   "openai", "tier": "MajorOperator",
    "tag":  "web-bot-auth", "mode": "enforce"
  }
}
// verify(token, key, { algorithms: ["HS256"] })
// then: claims.action == "allow" AND claims.txn == your stored order id

curl -X POST https://cardvera.dev/api/outcome \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpc3Mi…" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":  "9c1d4e77b0a3f5628d10c4ba9e73f001",
    "outcomeType":"auth",
    "outcome":    "declined_fraud",
    "occurredAt": "2026-09-21T14:32:00Z",
    "outcomeId":  "stripe_pi_3OABCxyz",
    "pspName":    "stripe"
  }'

202  Accepted            -> recorded, move on
400  { "error": "invalid_outcome" }      -> or missing_session_id, invalid_outcome_type, invalid_occurred_at
401  { "error": "invalid_token" }        -> bad/expired bearer, wrong alg
503  { "error": "storage_unavailable" }  -> safe to retry

GET /v1/cv.js?t=eyJ... HTTP/2
Host: edge.cardvera.dev
Signature-Agent: "https://chatgpt.com"
Signature-Input: sig1=("@authority" "@method" "@path");
  created=1787000000;expires=1787000060;
  keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";
  tag="web-bot-auth"
Signature: sig1=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQ=:

// Cardvera: fetch the operator's key directory (cached),
// rebuild the signature base, verify, reject replays.

{ "error": "invalid_outcome" }

// Token failures carry no detail by design:
//   401 { "error": "invalid_token" }   (POST /api/outcome)
//   403 { "error": "invalid_token" }   (GET /v1/cv.js)