Create and manage Privacy.com virtual cards for agent spending. Use when an agent needs to make a purchase, buy a domain, pay for a service, or needs a disposable card with a spending limit. Requires a Privacy.com account and API key.
Create, manage, and monitor virtual cards via the Privacy.com API. Designed for AI agents that need to make purchases with controlled spending limits.
Requires the PRIVACY_API_KEY environment variable. Get an API key from your Privacy.com account settings.
Plans and card limits:
Sandbox: Use https://sandbox.privacy.com/v1 for testing. Production: https://api.privacy.com/v1.
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).
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:
| Field | Required | Description |
|---|---|---|
type | Yes | SINGLE_USE (auto-closes after one charge), MERCHANT_LOCKED (locks to first merchant), DIGITAL_WALLET (Apple/Google Pay) |
memo | No | Label for the card (what it's for) |
spend_limit | No | Max spend in cents. Must be whole dollars (e.g., 2500 not 2550) |
spend_limit_duration | No | TRANSACTION (per charge), MONTHLY, ANNUALLY, FOREVER |
state | No | OPEN (ready to use) or PAUSED |
exp_month | No | Two-digit expiry month (auto-generated if omitted) |
exp_year | No | Four-digit expiry year (auto-generated if omitted) |
Response includes: pan (16-digit card number), cvv, exp_month, exp_year, token (card ID), last_four.
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 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).
GET https://api.privacy.com/v1/transactions?card_token={token}&result=APPROVED&page=1&page_size=50
Query parameters:
| Field | Description |
|---|---|
card_token | Filter by card |
result | APPROVED or decline reason |
page | Page number (1-indexed) |
page_size | Results per page |
begin | Start date (YYYY-MM-DD) |
end | End date (YYYY-MM-DD) |
Transaction statuses: PENDING, SETTLING, SETTLED, VOIDED, BOUNCED, DECLINED
SINGLE_USEMERCHANT_LOCKED# 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))
"
# 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'])")
curl -s https://api.privacy.com/v1/cards/CARD_TOKEN \
-H "Authorization: api-key $PRIVACY_API_KEY"
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"}'
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"}'
curl -s "https://api.privacy.com/v1/transactions?page=1&page_size=10" \
-H "Authorization: api-key $PRIVACY_API_KEY"
SINGLE_USE by default. Only use MERCHANT_LOCKED if explicitly needed for recurring charges.SINGLE_USE cards auto-close, but MERCHANT_LOCKED cards stay open. Close them when no longer needed.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)
PRIVACY_API_KEY env var.For testing without real money, use the sandbox environment:
https://sandbox.privacy.com/v1POST https://sandbox.privacy.com/v1/simulate/authorize and POST https://sandbox.privacy.com/v1/simulate/clearingPrivacy.com Developer API - RESTful API, requires API key from a Privacy.com account.