Cards that pay you back.

const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY!);

// A virtual card, ready to spend.
const card = await tuppence.cards.create({
  limits: { per_authorization: 5000, monthly: 50000 },
});

// Optional: the rules it spends under.
const policy = await tuppence.spendPolicies.create({
  name: "Software only",
  allowed_merchant_kinds: ["software"],
  approval_threshold: 10000, // a person says yes from $100
});
await tuppence.cards.update(card.id, { spend_policy: policy.id });

// Optional: a card of its own for an AI agent.
const agent = await tuppence.agents.create({ name: "Research agent" });
await tuppence.cards.create({ agent: agent.id });

import { Tuppence } from "@tuppence/node";

const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY);

// What the cards can spend now.
const balance = await tuppence.request("GET", "/v1/issuing/balance");
// { spendable: 25000, currency: "usd",
//   spends_from: "payments_balance", limited_by: "cleared", … }

// No bank details: the cards spend your cleared earnings.
const bank = await tuppence.request(
  "GET",
  "/v1/issuing/funding_instructions",
);
// { available: false, reason: "spends_earnings", … }

// Test mode: pay with pm_card_bypassPending, then move the
// test clock 7 days on. Once cleared, the cards can spend it.

import os
from tuppence import Tuppence

tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])

# What the cards can spend now.
balance = tuppence.request("GET", "/v1/issuing/balance")
print(balance["spendable"], balance["spends_from"])

# No bank details: the cards spend your cleared earnings.
bank = tuppence.request("GET", "/v1/issuing/funding_instructions")
print(bank["available"], bank["reason"])  # False spends_earnings

# What the cards can spend now.
curl https://api.tuppence.ai/v1/issuing/balance \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

# No bank details: available is false, reason spends_earnings.
curl https://api.tuppence.ai/v1/issuing/funding_instructions \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

// Pence, per purchase, day, week, month or all time.
// null removes a limit; a card always keeps one.
await tuppence.cards.setLimits(card.id, {
  monthly: 100000,          // $1,000 a month
  per_authorization: null,
});

// One purchase, at one merchant, up to $24.
const once = await tuppence.cards.create({
  usage: "single_use",
  amount: 2400,
  merchant: { name: "Lumen Labs" },
});

// Stop it at once, and start it again.
await tuppence.cards.freeze(card.id);
await tuppence.cards.unfreeze(card.id);

// The card pays wherever its policy allows,
// and the policy decides the moment the merchant charges it.
const { data } = await tuppence.cardAuthorizations.list({
  card: card.id,
});
// [{ amount: 1800, merchant: { name: "Lumen Labs", … },
//    approved: true, decided_by: "policy", … }]

// Over the threshold? Ask first, so the merchant never sees a decline.
const approval = await tuppence.approvals.create({
  card: card.id,
  amount: 24000, // $240.00
  merchant: { name: "Halcyon & Co" },
  description: "Annual data license",
});
// A person says yes in the dashboard or the app. Then buy.

# Test mode: a purchase, decided as a real one would be.
curl https://api.tuppence.ai/v1/test_helpers/issuing/authorizations \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"card": "card_01K…", "amount": 1800,
       "merchant": {"name": "Lumen Labs", "mcc": 5734}}'

{
  "object": "card_authorization",
  "amount": 1800,
  "approved": true,
  "decided_by": "policy",
  "spend_policy": "pol_01K…",
  …
}

# 1% on settled purchases, worked out on the month's total.
curl https://api.tuppence.ai/v1/cashback/statements \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

{
  "object": "cashback_statement",
  "period": "2026-09",
  "currency": "gbp",
  "eligible_spend": 50000,
  "rate_bps": 89,
  "gross": 445,
  "status": "paid",
  …
}