---
updatedAt: 2025-12-17T15:17:42.000Z
agentTools:
  projectIndex: https://developers.privacy.com/llms.txt
---

# Create card

Create a new virtual or physical card. Parameters `pin`, `shipping_address`, and `product_id` only apply to physical cards.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Privacy Developer API",
    "description": "The Privacy Developer API is designed to provide a predictable programmatic interface for accessing your Privacy account through an API and transaction webhooks.\nNote that your API key is a secret and should be treated as such. Don't share it with anyone, including us. We will never ask you for it.\n",
    "version": "1.0.0",
    "termsOfService": "https://privacy.com/legal#terms",
    "contact": {
      "email": "support@privacy.com"
    }
  },
  "servers": [
    {
      "url": "https://api.privacy.com/v1",
      "description": "Privacy production API server"
    },
    {
      "url": "https://sandbox.privacy.com/v1",
      "description": "Sandbox environment that provides all the functionality of production"
    }
  ],
  "paths": {
    "/cards": {
      "post": {
        "tags": [
          "Card"
        ],
        "summary": "Create card",
        "description": "Create a new virtual or physical card. Parameters `pin`, `shipping_address`, and `product_id` only apply to physical cards.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "account_token": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Only required for multi-account users. Token identifying the account the card will be associated with. Only applicable if using account enrollment. See [Managing Accounts](https://docs.privacy.com/docs/managing-accounts) for more information.\n"
                  },
                  "card_program_token": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Identifies the card program under which to create the card. Different card programs may have their own configurations (e.g., digital wallet card art, BIN type). This must be configured with Privacy before use.",
                    "example": "00000000-0000-0000-1000-000000000000"
                  },
                  "exp_month": {
                    "type": "string",
                    "description": "Two digit (MM) expiry month. If neither `exp_month` nor `exp_year` is provided, an expiration date will be generated.",
                    "minLength": 2,
                    "maxLength": 2,
                    "example": "06"
                  },
                  "exp_year": {
                    "type": "string",
                    "description": "Four digit (yyyy) expiry year. If neither `exp_month` nor `exp_year` is provided, an expiration date will be generated.",
                    "minLength": 4,
                    "maxLength": 4,
                    "example": "2027"
                  },
                  "funding_token": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The token for the desired `FundingAccount` to use when making transactions with this card.",
                    "example": "ecbd1d58-0299-48b3-84da-6ed7f5bf9ec1"
                  },
                  "memo": {
                    "type": "string",
                    "description": "Friendly name to identify the card.",
                    "example": "New Card"
                  },
                  "spend_limit": {
                    "type": "integer",
                    "description": "Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined.",
                    "example": 0,
                    "minimum": 0
                  },
                  "spend_limit_duration": {
                    "type": "string",
                    "enum": [
                      "ANNUALLY",
                      "FOREVER",
                      "MONTHLY",
                      "TRANSACTION"
                    ],
                    "description": "Spend limit duration values:\n* `ANNUALLY` - Card will authorize transactions up to spend limit in a calendar year.\n* `FOREVER` - Card will authorize only up to spend limit for the entire lifetime of the card.\n* `MONTHLY` - Card will authorize transactions up to spend limit for the trailing month. Month is calculated as this calendar date one month prior.\n* `TRANSACTION` - Card will authorizate multiple transactions if each individual transaction is under the spend limit.\n"
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "OPEN",
                      "PAUSED"
                    ],
                    "description": "Card state values:\n* `OPEN` - Card will approve authorizations (if they match card and account parameters).\n* `PAUSED` - Card will decline authorizations, but can be resumed at a later time.\n"
                  },
                  "type": {
                    "type": "string",
                    "default": "SINGLE_USE",
                    "enum": [
                      "DIGITAL_WALLET",
                      "MERCHANT_LOCKED",
                      "PHYSICAL",
                      "SINGLE_USE",
                      "UNLOCKED"
                    ],
                    "description": "Card types:\n* `DIGITAL_WALLET` - Cards that can be provisioned to a digital wallet like Google Pay or Apple Wallet.\n* `MERCHANT_LOCKED` - Card is locked to first merchant that successfully authorizes the card.\n* `PHYSICAL` - Manufactured and sent to the cardholder. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. Contact api@privacy.com for more information.\n* `SINGLE_USE` - Card will close shortly after the first transaction.\n* `UNLOCKED` - Card will authorize at any merchant. Creating these cards requires additional privileges.\n"
                  },
                  "pin": {
                    "type": "string",
                    "description": "Encrypted PIN block (in base64). Only applies to cards of type `PHYSICAL` [beta], `UNLOCKED`, and `DIGITAL_WALLET`. See [Encrypted PIN Block](https://docs.privacy.com/docs/cards#encrypted-pin-block-enterprise)."
                  },
                  "product_id": {
                    "type": "string",
                    "description": "Specifies the configuration (e.g., physical card art) that the card should be manufactured with, and only applies to cards of type `PHYSICAL` [beta]. This must be configured with Privacy before use.",
                    "example": "1"
                  },
                  "shipping_address": {
                    "$ref": "#/components/schemas/ShippingAddress"
                  },
                  "shipping_method": {
                    "type": "string",
                    "enum": [
                      "STANDARD",
                      "STANDARD_WITH_TRACKING",
                      "EXPEDITED"
                    ],
                    "description": "Shipping method for the card. Only applies to cards of type PHYSICAL [beta]. Use of options besides `STANDARD` require additional permissions.\n* `STANDARD` - USPS regular mail or similar international option, with no tracking\n* `STANDARD_WITH_TRACKING` - USPS regular mail or similar international option, with tracking\n* `EXPEDITED` - FedEx Standard Overnight or similar international option, with tracking\n"
                  }
                }
              },
              "examples": {
                "createCard": {
                  "summary": "Create card",
                  "value": {
                    "memo": "New Card",
                    "spend_limit": 0,
                    "spend_limit_duration": "TRANSACTION",
                    "state": "OPEN",
                    "type": "SINGLE_USE"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Card"
                },
                "example": {
                  "created": "2021-06-28T22:53:15Z",
                  "cvv": "776",
                  "exp_month": "06",
                  "exp_year": "2027",
                  "funding": {
                    "account_name": "Sandbox",
                    "created": "2020-07-08 17:57:36",
                    "last_four": "5263",
                    "nickname": "",
                    "state": "ENABLED",
                    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
                    "type": "DEPOSITORY_CHECKING"
                  },
                  "hostname": "",
                  "last_four": "4142",
                  "memo": "New Card",
                  "pan": "4111111289144142",
                  "spend_limit": 0,
                  "spend_limit_duration": "TRANSACTION",
                  "state": "OPEN",
                  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
                  "type": "SINGLE_USE"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "A parameter in the query given in the request does not match the valid queries for the endpoint.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Client has exceeded the number of allowed requests in a given time period.\n\n|   |   |\n|---|---|\n| Rate limited, too many requests per second | User has exceeded their per second rate limit |\n| Rate limited, reached daily limit | User has exceeded their daily rate limit |\n| Rate limited, too many keys tried | One IP has queried too many different API keys |\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "|   |   |\n|---|---|\n| User has not been authenticated | Invalid or missing API key |\n| API key is not active | The API key used is no longer active |\n| Could not find API key | The API key provided is not associated with any user |\n| Please provide API key in Authorization header | The Authorization header is not in the request |\n| Please provide API key in the form Authorization: api-key [api-key] | The Authorization header is not formatted properly |\n| Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Please contact [api@privacy.com](mailto:api@privacy.com) |\n| Insufficient privileges to create unlocked cards. | Creating unlocked cards requires an additional privilege | Please contact [api@privacy.com](mailto:api@privacy.com)  |\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Unprocessable entity.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Card": {
        "type": "object",
        "required": [
          "created",
          "funding",
          "last_four",
          "spend_limit",
          "spend_limit_duration",
          "state",
          "token",
          "type"
        ],
        "properties": {
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "An ISO 8601 timestamp for when the card was created. UTC time zone.",
            "example": "2021-06-28T22:53:15Z"
          },
          "cvv": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "description": "Three digit cvv printed on the back of the card.",
            "example": "776",
            "x-privacy-tag": "Enterprise"
          },
          "funding": {
            "$ref": "#/components/schemas/FundingAccount"
          },
          "exp_month": {
            "type": "string",
            "description": "Two digit (MM) expiry month.",
            "minLength": 2,
            "maxLength": 2,
            "example": "06",
            "x-privacy-tag": "Enterprise"
          },
          "exp_year": {
            "type": "string",
            "description": "Four digit (yyyy) expiry year.",
            "minLength": 4,
            "maxLength": 4,
            "example": "2027",
            "x-privacy-tag": "Enterprise"
          },
          "hostname": {
            "type": "string",
            "description": "Hostname of card’s locked merchant (will be empty if not applicable)."
          },
          "last_four": {
            "type": "string",
            "description": "Last four digits of the card number.",
            "minLength": 4,
            "maxLength": 4
          },
          "memo": {
            "type": "string",
            "description": "Friendly name to identify the card.",
            "example": "New Card"
          },
          "pan": {
            "type": "string",
            "description": "Primary Account Number (PAN) (i.e. the card number). Customers must be PCI compliant to have PAN returned as a field in production. Please contact [support@privacy.com](mailto:support@privacy.com) for questions.\n",
            "minLength": 16,
            "maxLength": 16,
            "example": "4111111289144142",
            "x-privacy-tag": "Enterprise"
          },
          "spend_limit": {
            "type": "integer",
            "description": "Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined.",
            "example": 1000
          },
          "spend_limit_duration": {
            "type": "string",
            "enum": [
              "ANNUALLY",
              "FOREVER",
              "MONTHLY",
              "TRANSACTION"
            ],
            "description": "Spend limit duration values:\n* `ANNUALLY` - Card will authorize transactions up to spend limit in a calendar year.\n* `FOREVER` - Card will authorize only up to spend limit for the entire lifetime of the card.\n* `MONTHLY` - Card will authorize transactions up to spend limit for the trailing month. Month is calculated as this calendar date one month prior.\n* `TRANSACTION` - Card will authorizate multiple transactions if each individual transaction is under the spend limit.\n"
          },
          "state": {
            "type": "string",
            "enum": [
              "CLOSED",
              "OPEN",
              "PAUSED",
              "PENDING_ACTIVATION",
              "PENDING_FULFILLMENT"
            ],
            "description": "Card state values:\n* `CLOSED` - Card will no longer approve authorizations. Closing a card cannot be undone.\n* `OPEN` - Card will approve authorizations (if they match card and account parameters).\n* `PAUSED` - Card will decline authorizations, but can be resumed at a later time.\n* `PENDING_FULFILLMENT` - The initial state for cards of type `PHYSICAL`. The card is provisioned pending manufacturing and fulfillment. Cards in this state can accept authorizations for e-commerce purchases, but not for \"Card Present\" purchases where the physical card itself is present.\n* `PENDING_ACTIVATION` - Each business day at 2pm Eastern Time Zone (ET), cards of type `PHYSICAL` in state `PENDING_FULFILLMENT` are sent to the card production warehouse and updated to state `PENDING_ACTIVATION` . Similar to `PENDING_FULFILLMENT`, cards in this state can be used for e-commerce transactions. API clients should update the card's state to `OPEN` only after the cardholder confirms receipt of the card.\n\nIn sandbox, the same daily batch fulfillment occurs, but no cards are actually manufactured.\n"
          },
          "auth_rule_tokens": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of identifiers for the Auth Rule(s) that are applied on the card.\n",
            "example": [
              "b68b7424-aa69-4cbc-a946-30d90181b621"
            ]
          },
          "token": {
            "type": "string",
            "format": "uuid",
            "description": "Globally unique identifier.",
            "example": "7ef7d65c-9023-4da3-b113-3b8583fd7951"
          },
          "type": {
            "type": "string",
            "enum": [
              "DIGITAL_WALLET",
              "MERCHANT_LOCKED",
              "PHYSICAL",
              "SINGLE_USE",
              "UNLOCKED"
            ],
            "description": "Card types:\n* `DIGITAL_WALLET` - Cards that can be provisioned to a digital wallet like Google Pay or Apple Wallet.\n* `MERCHANT_LOCKED` - Card is locked to first merchant that successfully authorizes the card.\n* `PHYSICAL` - Manufactured and sent to the cardholder. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. Contact [api@privacy.com](mailto:api@privacy.com) for more information.\n* `SINGLE_USE` - Card will close shortly after the first transaction.\n* `UNLOCKED` - Card will authorize at any merchant. Creating these cards requires additional privileges.\n"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Explanation of error response."
          },
          "debugging_request_id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier to help debug an error."
          }
        },
        "required": [
          "message",
          "debugging_request_id"
        ]
      },
      "FundingAccount": {
        "type": "object",
        "required": [
          "created",
          "last_four",
          "state",
          "token",
          "type"
        ],
        "properties": {
          "account_name": {
            "type": "string",
            "description": "Account name identifying the funding source. This may be `null`."
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "An ISO 8601 string representing when this funding source was added to the Privacy account. This may be `null`. UTC time zone."
          },
          "last_four": {
            "type": "string",
            "description": "The last 4 digits of the account (e.g. bank account, debit card) associated with this FundingAccount. This may be null.",
            "minLength": 4,
            "maxLength": 4
          },
          "nickname": {
            "type": "string",
            "description": "The nickname given to the `FundingAccount` or `null` if it has no nickname.",
            "minLength": 1,
            "maxLength": 255
          },
          "state": {
            "type": "string",
            "enum": [
              "ENABLED",
              "PENDING"
            ],
            "description": "State of funding source.\n\nFunding source states:\n* `ENABLED` - The funding account is available to use for card creation and transactions.\n* `PENDING` - The funding account is still being verified e.g. bank micro-deposits verification.\n"
          },
          "token": {
            "type": "string",
            "format": "uuid",
            "description": "A globally unique identifier for this FundingAccount."
          },
          "type": {
            "type": "string",
            "enum": [
              "DEPOSITORY_CHECKING",
              "DEPOSITORY_SAVINGS"
            ],
            "description": "Types of funding source:\n* `DEPOSITORY_CHECKING` - Bank checking account.\n* `DEPOSITORY_SAVINGS` - Bank savings account.\n"
          }
        }
      },
      "ShippingAddress": {
        "type": "object",
        "required": [
          "address1",
          "city",
          "country",
          "first_name",
          "last_name",
          "state",
          "postal_code"
        ],
        "properties": {
          "first_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Customer's first name. This will be the first name printed on the physical card.",
            "example": "Michael"
          },
          "last_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 26,
            "description": "Customer's surname (family name). This will be the last name printed on the physical card.",
            "example": "Bluth"
          },
          "line2_text": {
            "type": "string",
            "minLength": 0,
            "maxLength": 50,
            "description": "Text to be printed on line two of the physical card. Use of this field requires additional permissions.",
            "example": "The Bluth Company"
          },
          "address1": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Valid USPS routable address.",
            "example": "5 Broad Street"
          },
          "address2": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Unit number (if applicable).",
            "example": "Unit 25A"
          },
          "city": {
            "type": "string",
            "description": "City",
            "minLength": 1,
            "maxLength": 255,
            "example": "NEW YORK"
          },
          "state": {
            "type": "string",
            "description": "Uppercase ISO 3166-2 two character abbreviation for US and CA. Optional with a limit of 24 characters for other countries.",
            "minLength": 0,
            "maxLength": 24,
            "example": "NY"
          },
          "postal_code": {
            "type": "string",
            "description": "Postal code (formerly zipcode). For US addresses, either five-digit zipcode or nine-digit \"ZIP+4\".",
            "minLength": 1,
            "maxLength": 12,
            "example": "10001-1809"
          },
          "country": {
            "type": "string",
            "description": "Uppercase ISO 3166-1 alpha-3 three character abbreviation.",
            "minLength": 3,
            "maxLength": 3,
            "example": "USA"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "apiKey",
        "in": "header",
        "description": "Prefix your API key with `api-key`.",
        "name": "Authorization"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```