Privacy.com Getting Started: API Credentials & First Request (2026)

Getting started overview

Getting started with the Privacy.com API involves several key steps: account creation, API key generation, and executing an initial API call. The Privacy.com API enables programmatic control over virtual card creation, management, and transaction monitoring, useful for integrating into financial applications or automating payment workflows. It supports RESTful principles and uses JSON for request and response bodies. Developers can manage card limits, close cards, and integrate webhooks for real-time event notifications, as detailed in the Privacy.com API documentation.

The primary use case for the API is the creation and management of virtual cards, which abstract actual bank account details behind unique, single-use or merchant-locked card numbers. This helps prevent direct exposure of primary financial information during online transactions, a practice that aligns with principles of data minimization and transaction security. The API facilitates automating these privacy-enhancing features.

The following table provides a quick reference for the essential steps to get started:

Create an account and get keys

To access the Privacy.com API, you must first have an active Privacy.com account. Different account tiers offer varying API access levels and card creation limits. The Privacy.com pricing page details the features and limits associated with Personal, Pro, and Teams plans. The Personal Plan includes up to 12 virtual cards per month, while paid plans like Pro and Teams offer higher limits and additional features such as cashback rewards and dedicated account management.

Once your account is set up and verified, navigate to the developer section of your Privacy.com dashboard. Here, you can generate your API keys. Privacy.com typically issues a pair of keys: a public key (for specific client-side operations, if applicable) and a secret key (for server-side authentication). It is important to treat your secret API key as sensitive credentials, similar to a password, as it grants full access to your virtual card management capabilities via the API. For security best practices, store this key securely and avoid hardcoding it directly into client-side applications. The Privacy.com API documentation guide recommends using environment variables or a secure secret management service.

The API key is typically a long, alphanumeric string. This key will be included in the Authorization header of your API requests, usually prefixed with Bearer. For example, Authorization: Bearer YOUR_SECRET_API_KEY. This is a common pattern for Bearer token authentication in RESTful APIs.

Your first request

Your first API request typically involves creating a virtual card. This demonstrates successful authentication and interaction with the core functionality of the Privacy.com API. The endpoint for creating a card is generally a POST request to a /cards endpoint. The Privacy.com Cards API reference provides the specific endpoint URL and required parameters.

A typical request to create a virtual card might look like this:

curl -X POST \  'https://api.privacy.com/v1/cards' \  -H 'Content-Type: application/json' \  -H 'Authorization: Bearer YOUR_SECRET_API_KEY' \  -d '{ \    "type": "SINGLE_USE", \    "spend_limit": 5000, \    "spend_limit_duration": "TRANSACTION", \    "memo": "First API Card", \    "funding_account_token": "FUNDING_ACCOUNT_TOKEN_HERE" \  }'

In this example:

• YOUR_SECRET_API_KEY should be replaced with the API key you obtained from your dashboard.
• type specifies the card type (e.g., SINGLE_USE, MERCHANT_LOCKED).
• spend_limit is the maximum amount (in cents) the card can be used for.
• spend_limit_duration defines how the spend limit is applied (e.g., TRANSACTION, MONTHLY).
• memo is an optional descriptive note for the card.
• funding_account_token links the virtual card to a specific funding source (e.g., your bank account). You can retrieve available funding accounts via another API endpoint, usually GET /funding-accounts.

Upon a successful request, the API will return a JSON object containing the details of the newly created virtual card, including its token, last four digits, expiration, and CVV. A successful HTTP status code (e.g., 200 OK or 201 Created) indicates the card was generated.

Common next steps

After successfully creating your first virtual card, several common next steps can enhance your integration with Privacy.com:

1. Retrieve Card Details: Use the card token received in the creation response to retrieve full card details, including the full card number, expiration date, and CVV, if necessary for specific integrations. Note that for security, the full card number is typically only exposed once upon creation or with specific secure retrieval methods. The Privacy.com API documentation for retrieving card details provides endpoint specifics.
2. Manage Card Limits: Implement functionality to dynamically adjust spend limits on existing virtual cards. This is particularly useful for managing subscriptions or controlling spending on a per-merchant basis. The API typically provides an endpoint to update card attributes, including spend_limit.
3. Close Cards: Automate the closing of virtual cards when they are no longer needed (e.g., after a single transaction, or when a subscription is canceled). This helps maintain security and manage your available card count. Refer to the Privacy.com API endpoint for closing cards.
4. Webhooks Integration: Configure webhooks to receive real-time notifications about key events, such as card transactions, card status changes, or funding account updates. Webhooks are a crucial component for building reactive applications that respond to payment events. The Privacy.com webhooks guide explains how to set up and secure your webhook endpoints.
5. Error Handling: Implement robust error handling to gracefully manage API responses that indicate issues, such as invalid parameters, authentication failures, or rate limits. The Privacy.com API typically returns standardized error codes and messages, which are detailed in the API reference.
6. Explore Other Endpoints: Investigate other available endpoints, such as those for managing funding accounts, retrieving transaction history, or listing existing virtual cards, to build more comprehensive financial management tools.

Troubleshooting the first call

When making your first API call, you might encounter common issues. Here are some troubleshooting tips:

• Authorization Errors (401 Unauthorized):
  • Incorrect API Key: Double-check that you have copied the entire secret API key correctly from your Privacy.com dashboard.
  • Missing Bearer Prefix: Ensure your Authorization header uses the Bearer prefix, e.g., Authorization: Bearer YOUR_SECRET_API_KEY.
  • Expired Key: While uncommon for secret keys, verify that your key is still active. If in doubt, generate a new one from your developer dashboard.
• Bad Request (400 Bad Request):
  • Malformed JSON: Review the JSON payload in your request body for syntax errors (e.g., missing commas, unclosed quotes, incorrect brackets). Tools like online JSON validators can help.
  • Missing Required Parameters: Ensure all mandatory fields (e.g., type, spend_limit, funding_account_token) are present in your request payload, as specified in the Privacy.com create card API documentation.
  • Invalid Parameter Values: Check that the values you're sending for parameters like type or spend_limit_duration match the allowed enumerations or formats. For example, spend limits are typically in cents (e.g., 5000 for $50.00).
• Forbidden (403 Forbidden):
  • Account Limits: You might have hit your monthly virtual card creation limit, especially on a free tier. Check your account dashboard or Privacy.com pricing page for current limits.
  • Permissions: Ensure your API key has the necessary permissions for the operation you are attempting. Some keys might be scoped to specific actions.
• Network Issues:
  • Firewall/Proxy: If you're behind a corporate firewall or proxy, ensure it's not blocking outgoing requests to the Privacy.com API endpoints.
  • Incorrect Endpoint URL: Verify that the base URL for the API endpoint (e.g., https://api.privacy.com/v1/) is correct.
• Server Errors (5xx):
  • These indicate an issue on Privacy.com's side. While less common, if you receive a 5xx error, it's best to wait a short period and retry the request. If the issue persists, consult the Privacy.com developer support resources.