Sign in

v45

latestOpenAPI 3.0.0raw.githubusercontent.com2026-07-2684278289.5 KB
Cards

Create a card

Issue a new virtual card.

post/cards

Request body

accountIdstring uuid nullable

The account the new card will draw funds from. Required when @kind@ is @debit@; list available account IDs via @GET https://api.mercury.com/api/v1/accounts@ (for debit card creation, the accountId must be associated with a checking account). Optional when @kind@ is @credit@; omit to use your organization's Mercury credit account, or pass the credit accountId from @GET https://api.mercury.com/api/v1/credit@.

kind'debit' | 'credit' required

Whether to issue a debit or credit card.

nicknamestring nullable

Optional user-assigned label for the card.

type'virtual' required

The type of card to issue.

userIdstring uuid required

The user to assign as the cardholder.

Response

accountIdstring required

The Mercury account this card is associated with.

categoryLocksMercuryCategory[] required

Mercury spend-category locks applied to this card, in no particular order. Empty when the card has no category restrictions.

createdAtstring yyyy-mm-ddThh:MM:ssZ required

Timestamp when the card was issued.

idstring uuid required

Unique identifier for the card.

kind'debit' | 'credit' required

Whether the card is a debit or credit card.

lastFourstring required

Last four digits of the card's primary account number (PAN).

nameOnCardstring required

Cardholder name printed on the card.

nicknamestring nullable

Optional user-assigned label for the card.

physicalCardStatus'inactive' | 'active' | 'locked' nullable

Activation state of a physical card. Null for virtual cards.

status'active' | 'frozen' | 'cancelled' | 'inactive' | 'expired' | 'suspended' required

Current lifecycle state of the card.

type'virtual' | 'physical' required

Whether the card is virtual (digital-only) or physical (printed, supports ATM).

updatedAtstring yyyy-mm-ddThh:MM:ssZ required

Timestamp of the last modification to the card or its settings.

userIdstring required

Mercury User who owns the card.

Example response

{
  "createdAt": "2016-07-22T00:00:00Z",
  "expiration": {
    "month": 8,
    "year": 2026
  },
  "updatedAt": "2016-07-22T00:00:00Z"
}