Privacy Cards

Sandbox: Use https://sandbox.privacy.com/v1 for testing. Production: https://api.privacy.com/v1.

API Reference

Base URL: https://api.privacy.com/v1 Auth Header: Authorization: api-key YOUR_API_KEY Content-Type: application/json

All monetary amounts are in cents (e.g., $25.00 = 2500).

Create a Card

POST https://api.privacy.com/v1/cards

{
  "type": "SINGLE_USE",
  "memo": "Domain purchase - example.com",
  "spend_limit": 2500,
  "spend_limit_duration": "TRANSACTION",
  "state": "OPEN"
}

Parameters:

Response includes: pan (16-digit card number), cvv, exp_month, exp_year, token (card ID), last_four.

Update a Card

PATCH https://api.privacy.com/v1/cards/{card_token}

{
  "state": "PAUSED",
  "spend_limit": 5000,
  "memo": "Updated memo"
}

Can update: state, memo, spend_limit, spend_limit_duration, funding_token.

Setting state to CLOSED is permanent and cannot be undone.

Get Card(s)

GET https://api.privacy.com/v1/cards/{card_token}
GET https://api.privacy.com/v1/cards
GET https://api.privacy.com/v1/cards?begin=2024-01-01&end=2024-12-31&page=1&page_size=50

Query parameters: begin, end (date filters), page, page_size (pagination).

List Transactions

GET https://api.privacy.com/v1/transactions?card_token={token}&result=APPROVED&page=1&page_size=50

Query parameters:

Transaction statuses: PENDING, SETTLING, SETTLED, VOIDED, BOUNCED, DECLINED

Step-by-Step Instructions

Creating a Card for an Agent Purchase

1. Determine the amount needed (round up to whole dollars)
2. Choose card type:
   • One-time purchase? Use SINGLE_USE
   • Recurring at one merchant (e.g., subscription)? Use MERCHANT_LOCKED
3. Create the card and extract only the fields you need. Never log or print the full API response — it contains the full card number (PAN) and CVV which must not appear in chat logs or transcripts.

# Create card and extract only safe fields for logging
RESPONSE=$(curl -s https://api.privacy.com/v1/cards \
  -X POST \
  -H "Authorization: api-key $PRIVACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SINGLE_USE",
    "memo": "Purpose of purchase",
    "spend_limit": AMOUNT_IN_CENTS,
    "spend_limit_duration": "TRANSACTION",
    "state": "OPEN"
  }')

# Log only safe fields (no PAN/CVV)
echo "$RESPONSE" | python3 -c "
import sys, json
card = json.load(sys.stdin)
print(json.dumps({
  'token': card.get('token'),
  'last_four': card.get('last_four'),
  'exp_month': card.get('exp_month'),
  'exp_year': card.get('exp_year'),
  'spend_limit': card.get('spend_limit'),
  'state': card.get('state'),
  'memo': card.get('memo')
}, indent=2))
"

4. When you need the full card details for checkout, extract them in a separate step that is not logged to chat. Use the card details directly in the browser tool or API call without printing them.

# Extract card details for checkout (DO NOT print to chat)
PAN=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['pan'])")
CVV=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['cvv'])")
EXP_MONTH=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['exp_month'])")
EXP_YEAR=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['exp_year'])")

5. Use these card details to complete the purchase (via browser tool or API)
6. After purchase, verify with the transactions endpoint

Checking a Card's Status

curl -s https://api.privacy.com/v1/cards/CARD_TOKEN \
  -H "Authorization: api-key $PRIVACY_API_KEY"

Pausing a Card (Temporarily Disable)

curl -s https://api.privacy.com/v1/cards/CARD_TOKEN \
  -X PATCH \
  -H "Authorization: api-key $PRIVACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "PAUSED"}'

Closing a Card (Permanent)

curl -s https://api.privacy.com/v1/cards/CARD_TOKEN \
  -X PATCH \
  -H "Authorization: api-key $PRIVACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "CLOSED"}'

Viewing Recent Transactions

curl -s "https://api.privacy.com/v1/transactions?page=1&page_size=10" \
  -H "Authorization: api-key $PRIVACY_API_KEY"

Safety Rules

1. Always confirm the purchase amount and purpose with the user before creating a card, unless the user has pre-approved the spend (e.g., "buy this domain" with a known price).
2. Use SINGLE_USE by default. Only use MERCHANT_LOCKED if explicitly needed for recurring charges.
3. Set the spend limit as close to the expected amount as possible. Round up to the next whole dollar, but don't over-allocate (e.g., $12.99 item = $13.00 = 1300 cents).
4. Close or pause cards after use. SINGLE_USE cards auto-close, but MERCHANT_LOCKED cards stay open. Close them when no longer needed.
5. Never log, print, or display the full PAN or CVV in chat, logs, or tool output. The raw API response contains sensitive card data (PAN, CVV) that must not appear in transcripts. Always parse the response and extract only safe fields (token, last_four, memo, spend_limit, state) for logging. Use full card details only in the checkout step, never echoed to chat.
6. Include a descriptive memo on every card so the user can identify what it was for in their Privacy.com dashboard.

Output Format

When creating a card, report to the user:

Created Privacy.com card (****1234)
Type: Single-use
Limit: $25.00
Memo: Domain purchase - example.com
Status: Ready to use

When listing transactions:

Recent transactions:

1. $12.99 at NAMECHEAP.COM - SETTLED (Jan 15, 2024)
   Card: ****1234 (Domain purchase)

2. $49.00 at GITHUB.COM - PENDING (Jan 14, 2024)
   Card: ****5678 (GitHub Pro subscription)

Error Handling

• 401 Unauthorized: API key is invalid or missing. Check PRIVACY_API_KEY env var.
• 403 Forbidden: Account may need verification or doesn't have API access.
• 429 Rate Limited: Back off and retry after a short delay.
• Card creation fails: May have hit the monthly card limit for the plan tier. Inform the user.
• Amount not in whole dollars: The API requires spend_limit in whole-dollar increments (in cents). Round up.

Sandbox Testing

For testing without real money, use the sandbox environment:

• Base URL: https://sandbox.privacy.com/v1
• Simulate transactions: POST https://sandbox.privacy.com/v1/simulate/authorize and POST https://sandbox.privacy.com/v1/simulate/clearing
• Sandbox cards work identically to production but no real charges occur.

Data Source

Privacy.com Developer API - RESTful API, requires API key from a Privacy.com account.