This guide covers how to use the Privacy API to create virtual cards, set spending limits, monitor transactions, and manage card state programmatically within an agentic workflow.

What You Need Before You Start

A Privacy account. API access is available to anyone on Privacy Plus ($5/month), Privacy Pro ($10/month), or Privacy Premium ($20/month). Sign up or upgrade at privacy.com/pricing.

Your API key. Once you're on a paid plan, generate your API key from your account page. This key authenticates all API requests.

The sandbox (recommended). Privacy provides a sandbox environment at sandbox.privacy.com with test card numbers. The sandbox requires a separate API key, also available on your account page.

A note on this guide: The Privacy API docs mark some features as "Issuing" or "Enterprise." Some of these labels may be outdated. If you encounter a permissions error on any endpoint described below, contact support@privacy.com to confirm access for your plan tier. 

API Basics

All requests go to https://api.privacy.com/v1/ (or https://sandbox.privacy.com/v1/ for testing).

Authentication: Include your API key in the request header:

Authorization: api-key YOUR_API_KEY

Amounts are integers in the smallest currency unit (e.g., 1000 = $10.00 USD).

Dates are ISO 8601 format.

Responses are paginated:

{
  "data": [...],
  "page": 1,
  "total_entries": 25,
  "total_pages": 2
}

Step 1: Create a Virtual Card for Your Agent

Send a POST request to /v1/cards with the card type, spending limit, and limit duration.

Example: Create a Single-Use Card with a $5 limit

curl https://api.privacy.com/v1/cards \
  -X POST \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SINGLE_USE",
    "memo": "Agent - Perplexity subscription",
    "spend_limit": 500,
    "spend_limit_duration": "TRANSACTION",
    "state": "OPEN"
  }'

The response includes the card details needed to make a purchase:

{
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
  "last_four": "4142",
  "type": "SINGLE_USE",
  "spend_limit": 500,
  "spend_limit_duration": "TRANSACTION",
  "state": "OPEN",
  "memo": "Agent - Perplexity subscription"
}

The agent reads pan, cvv, exp_month, and exp_year from the response to use at checkout.

Choosing a Card Type

Setting Spend Limits

The spend_limit (in cents) and spend_limit_duration fields determine how much the card can authorize.

Example: a Merchant-Locked Card for LLM API billing, capped at $100/month:

curl https://api.privacy.com/v1/cards \
  -X POST \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MERCHANT_LOCKED",
    "memo": "Agent - Anthropic API billing",
    "spend_limit": 10000,
    "spend_limit_duration": "MONTHLY",
    "state": "OPEN"
  }'

Step 2: Monitor Agent Spending

The Transactions endpoint returns transaction history, filterable by card, date range, and result.

List transactions for a specific card

curl "https://api.privacy.com/v1/transactions?card_token=7ef7d65c-9023-4da3-b113-3b8583fd7951&page=1&page_size=50" \
  -H "Authorization: api-key YOUR_API_KEY"

Each transaction includes:

• amount: The transaction amount in cents
• merchant.descriptor: The merchant name (e.g., "OPENAI" or "PERPLEXITY AI")
• merchant.mcc: Merchant category code
• result: APPROVED or a decline reason (e.g., USER_TRANSACTION_LIMIT if the spend limit was hit)
• status: PENDING, SETTLED, DECLINED, VOIDED, etc.
• created: Timestamp of the transaction

Example response

{
  "data": [
    {
      "amount": -500,
      "authorization_amount": -500,
      "created": "2026-02-15T14:22:33Z",
      "merchant": {
        "descriptor": "PERPLEXITY AI",
        "mcc": "5734",
        "city": "SAN FRANCISCO",
        "state": "CA",
        "country": "USA"
      },
      "result": "APPROVED",
      "status": "SETTLED",
      "token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955",
      "card": {
        "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
        "last_four": "4142",
        "memo": "Agent - Perplexity subscription"
      }
    }
  ],
  "page": 1,
  "total_entries": 1,
  "total_pages": 1
}

Useful query parameters

Step 3: Control Cards Programmatically

Cards can be paused, resumed, updated, or permanently closed via PATCH requests.

Pause a card

Pausing a card declines all future transactions until the card is set back to OPEN.

curl https://api.privacy.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -X PATCH \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "PAUSED"}'

Resume a card

curl https://api.privacy.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -X PATCH \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "OPEN"}'

Close a card permanently

Closing a card is irreversible. The card will not accept further transactions.

curl https://api.privacy.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -X PATCH \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "CLOSED"}'

Update a spend limit

Spend limits and durations can be updated on active cards.

curl https://api.privacy.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -X PATCH \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spend_limit": 5000,
    "spend_limit_duration": "MONTHLY"
  }'

‍

Step 4: Set Up Webhooks for Real-Time Monitoring

Instead of polling the Transactions endpoint, you can configure webhooks to receive real-time transaction data.

Set your webhook URL in your Privacy account settings. Once configured, Privacy will send an HTTP POST request to your endpoint with a Transaction object every time a transaction event occurs on any of your cards.

Webhooks are HMAC-verified, so you can confirm each notification actually came from Privacy. If your server is unavailable, Privacy retries with exponential backoff (doubling the wait time between attempts) for up to 24 hours.

Use cases for webhooks

• Spend alerts: Trigger notifications when charges occur
• Automated card controls: Pause a card programmatically if a transaction exceeds an expected threshold
• Audit logging: Record every agent transaction with merchant details and timestamps
• Agent feedback loops: Confirm a purchase succeeded before the agent proceeds to its next task

Putting It All Together: A Sample Agentic Workflow

Here's a typical integration flow. In this example, an agent needs to purchase a Perplexity AI subscription to gain search capabilities.

1. Create card. Orchestration layer calls POST /v1/cards to create a single-use card with a $20 limit.
2. Read card details. The API response includes pan, cvv, exp_month, and exp_year. The agent stores these temporarily.
3. Complete purchase. The agent navigates to Perplexity AI's checkout and enters the card details.
4. Webhook fires. Your server receives a webhook: $5.00 charged by PERPLEXITY AI, result APPROVED.
5. Card auto-closes. Single-Use Card closes after the first transaction. No further charges are possible.
6. Agent continues. With the subscription active, the agent proceeds to its next task.

If the charge at step 3 exceeds the $20 limit, the transaction is declined. If the agent attempts to reuse the card, it's already closed.

Python Quick Reference

Most agent frameworks are Python-based. Here's a minimal wrapper around the Privacy API:

import requests

PRIVACY_API_KEY = "your_api_key_here"
BASE_URL = "https://api.privacy.com/v1"  # Use https://sandbox.privacy.com/v1 for testing
HEADERS = {
    "Authorization": f"api-key {PRIVACY_API_KEY}",
    "Content-Type": "application/json",
}


def create_card(card_type, memo, spend_limit_cents, duration="TRANSACTION"):
    """Create a virtual card and return the full card details."""
    resp = requests.post(f"{BASE_URL}/cards", headers=HEADERS, json={
        "type": card_type,
        "memo": memo,
        "spend_limit": spend_limit_cents,
        "spend_limit_duration": duration,
        "state": "OPEN",
    })
    resp.raise_for_status()
    return resp.json()


def pause_card(card_token):
    """Pause a card. All future transactions will be declined."""
    resp = requests.patch(f"{BASE_URL}/cards/{card_token}", headers=HEADERS, json={
        "state": "PAUSED",
    })
    resp.raise_for_status()
    return resp.json()


def close_card(card_token):
    """Permanently close a card. This cannot be undone."""
    resp = requests.patch(f"{BASE_URL}/cards/{card_token}", headers=HEADERS, json={
        "state": "CLOSED",
    })
    resp.raise_for_status()
    return resp.json()


def get_transactions(card_token=None, result=None):
    """List transactions, optionally filtered by card or result."""
    params = {}
    if card_token:
        params["card_token"] = card_token
    if result:
        params["result"] = result
    resp = requests.get(f"{BASE_URL}/transactions", headers=HEADERS, params=params)
    resp.raise_for_status()
    return resp.json()


# Example usage:
# card = create_card("SINGLE_USE", "Agent - Perplexity", 2000)
# print(f"Card number: {card['pan']}, CVV: {card['cvv']}, Exp: {card['exp_month']}/{card['exp_year']}")
# ... agent uses card ...
# transactions = get_transactions(card_token=card["token"])

Best Practices

• Single-Use Cards for one-off purchases. They close automatically after the first transaction, preventing repeat or unauthorized charges.
• Merchant-Locked Cards for recurring billing. Only the original merchant can charge the card.
• Tight spend limits. If you expect a $5 charge, set a limit close to that. Smaller limits reduce exposure.
• Label cards with memo. Clear labels like "Agent - Anthropic API" or "Agent - domain purchase" make auditing straightforward.
• Develop against the sandbox. sandbox.privacy.com provides the same functionality with test card numbers.
• Use webhooks over polling. Webhooks provide real-time transaction data without additional API calls.

API Reference Summary

Full API documentation: privacy-com.readme.io/docs

Get Started

1. Sign up or upgrade to a Privacy plan (Plus or higher) at privacy.com/pricing
2. Generate your API key from your account page
3. Build against the sandbox at sandbox.privacy.com
4. Go live when ready

Questions? Reach out to support@privacy.com.

‍