MEmercurytechnologies
Cards

Create a card

Changed on

Issue a new virtual card.

post/cards

Request

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.

isAgentCardboolean required

Whether the card is managed by the agentic spend-management agent. Only agent cards can have their full details revealed.

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.

spendLimitType'cardLimit' | 'budgets' required

Whether card-level limits or budgets govern purchase spending.

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"
}

Changes