Card Schema

{
  "created": String,
  "cvv": String,
  "funding": Object,
  "exp_month": String,
  "exp_year": String,
  "hostname": String,
  "last_four": String,
  "memo": String,
  "pan": String,
  "spend_limit": Integer,
  "spend_limit_duration": String,
  "state": String,
  "token": String,
  "type": String
}


created	An ISO 8601 timestamp (yyyy-MM-ddThh:mm:ssZ) for when the card was created.
cvv	Three digit CVV printed on the back of the card.
funding	See Funding Source Schema.
exp_month	Two digit (MM) expiry month.
exp_year	Four digit (yyyy) expiry year.
hostname	Hostname of card’s locked merchant (will be empty if not applicable).
last_four	Last four digits of the card number.
memo	Customizable name to identify the card.
pan	Sixteen digit card number.
spend_limit	Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined. The Spend-Limit value has to be a whole dollars (in cents).
spend_limit_duration	`ANNUALLY`, `FOREVER`, `MONTHLY`, `TRANSACTION`.
state	`CLOSED`, `OPEN`, `PAUSED`, `PENDING_ACTIVATION`, `PENDING_FULFILLMENT`.
token	Globally unique identifier for the card.
type	`MERCHANT_LOCKED`, `SINGLE_USE`, `DIGITAL_WALLET`.

Create Card (Issuing)

API Reference: Create card

Create either a virtual or digital wallet card.

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

Sample Request

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": "New Card",
     "spend_limit": 1000,
     "spend_limit_duration": "TRANSACTION",
     "state": "OPEN"
}
'

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 1000,
  "spend_limit_duration": "TRANSACTION",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}


memo (optional)	Customizable name to identify the card. String. Permitted values: Any.
type (required)	Type of card to be created. String. Permitted values: `SINGLE_USE`, `MERCHANT_LOCKED`, `DIGITAL_WALLET`.
funding_token _(optional)_	Globally unique identifier for the funding source to be used when transactions are made with this card. String. Permitted values: 36-digit version 4 UUID (including hyphens).
spend_limit _(optional)_	Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined. Integer. Permitted values: 0 or greater.
spend_limit_duration _(optional)_	Duration for which spend limit applies. String. Permitted values: `TRANSACTION`, `MONTHLY`, `ANNUALLY`, `FOREVER`.
state (optional)	Indicates whether or not the card is in an active state (i.e., transactions can be accepted). String. Permitted values: `OPEN`, `PAUSED`.
exp_month _(optional)_	Two-digit (MM) expiry month. If neither `exp_month` nor `exp_year` is provided, an expiration date will be generated. String. Permitted values: `01,` 02`,` 03`,`04`,` 05`,` 06`,` 07`,` 08`,`09`,` 10`,` 11`,` 12.
exp_year _(optional)_	Four-digit (yyyy) expiry year. If neither `exp_month` nor `exp_year` is provided, an expiration date will be generated. String. Permitted values: Valid four-digit year.

Update Card (Issuing)

API Reference: Update card

Update the specified properties of the card. Unsupplied properties will remain unchanged.

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

Sample Request

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 '
{
     "memo": "New Card",
     "spend_limit": 2000,
     "spend_limit_duration": "FOREVER"
}
'

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 2000,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}


card_token (required, path parameter)	Globally unique identifier for the card to be updated. String. Permitted values: 36-digit version 4 UUID (including hyphens).
state (optional)	Indicates whether or not the card is in an active state (i.e., transactions can be accepted). Note that setting a card to a `CLOSED` state is a final action that cannot be undone. String. Permitted values: `OPEN`, `PAUSED`, `CLOSED`.
funding_token (optional)	Globally unique identifier for the funding source to be used when transactions are made with this card. String. Permitted values: 36-digit version 4 UUID (including hyphens).
memo (optional)	Customizable name to identify the card. String. Permitted values: Any.
spend_limit (optional)	Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined. Integer. Permitted values: 0 or greater.
spend_limit_duration (optional)	Duration for which spend limit applies. String. Permitted values: `TRANSACTION`, `MONTHLY`, `ANNUALLY`, `FOREVER`.

List Cards

API Reference: List cards

Get details for all cards or a specified card. This endpoint can only be used for cards that are managed by the program associated with the calling API key. If card_token is passed in as a path parameter, the endpoint returns a single object representing the card specified. Otherwise, a list of objects is returned.

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

Sample Request

curl https://api.privacy.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -H "Authorization: api-key YOUR_API_KEY"

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 2000,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}


card_token (optional, path parameter)	Globally unique identifier for the card. If using this parameter, do not include other parameters in the request. String. Permitted values: 36-digit version 4 UUID (including hyphens).
account_token (optional, query parameter)	Globally unique identifier for an account. This endpoint will return cards associated with this account if included in the request. String. Permitted values: 36-digit version 4 UUID (including hyphens).
begin (optional, query parameter)	Cards created on or after the specified date will be included. String. Permitted values: Date string in the form YYYY-MM-DD.
end (optional)	Cards created before the specified date will be included (i.e., cards created on the specified date will not be included). String. Permitted values: Date string in the form YYYY-MM-DD.
page_size (optional, query parameter)	For pagination - specifies the number of entries to be included on each page in the response. Default value is 50. Integer. Permitted values: 1-1000.
page (optional, query parameter)	For pagination - specifies the desired page to be included in the response. For example, if there are 3 total entries, and `page_size` is 2 (i.e., 2 entries per page), then entering the value `2` for `page` would return the second page and only the third entry. The default is one. Integer. Permitted values: 1 or greater.

Enumerations

Card.type


DIGITAL_WALLET	Cards that can be provisioned to a digital wallet like Google Pay or Apple Wallet
MERCHANT_LOCKED	Card is locked to first merchant that successfully authorizes the card
SINGLE_USE	Card will close shortly after the first transaction

Card.state


CLOSED	Card will no longer approve authorizations. Closing a card cannot be undone
OPEN	Card will approve authorizations (if they match card and account parameters)
PAUSED	Card will decline authorizations but can be resumed at a later time

Card.spend_limit_duration


ANNUALLY	Card will authorize transactions up to spend limit in a calendar year
FOREVER	Card will authorize only up to spend limit for the entire lifetime of the card
MONTHLY	Card will authorize transactions up to spend limit for the trailing month. (Note month is calculated as this calendar date one month prior)
TRANSACTION	Card will authorize multiple transactions if each individual transaction is under the spend limit