---
title: "Create a card"
method: POST
path: "/cards"
tags: ["Cards"]
---

# Create a card

`POST /cards`

Issue a new virtual card.

## Request body

- CreateCardRequest
  - `accountId` string, 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.
  - `nickname` string, nullable — Optional user-assigned label for the card.
  - `spendLimit` object, nullable — Spending controls to apply at issuance.
    - `amountCents` integer, required — Maximum total spend allowed per interval, in cents.
    - `interval` 'daily' | 'weekly' | 'monthly', required — Rolling window the limit applies to.
  - `type` 'virtual', required — The type of card to issue.
  - `userId` string, uuid, required — The user to assign as the cardholder.

## Response `200`

- Card
  - `accountId` string, required — The Mercury account this card is associated with.
  - `createdAt` string, yyyy-mm-ddThh:MM:ssZ, required — Timestamp when the card was issued.
  - `expiration` object, required — Month and year the card expires.
    - `month` integer, required — Calendar month.
    - `year` integer, required — Four-digit calendar year.
  - `id` string, uuid, required — Unique identifier for the card.
  - `kind` 'debit' | 'credit', required — Whether the card is a debit or credit card.
  - `lastFour` string, required — Last four digits of the card's primary account number (PAN).
  - `nameOnCard` string, required — Cardholder name printed on the card.
  - `nickname` string, nullable — Optional user-assigned label for the card.
  - `physicalCardStatus` 'inactive' | 'active' | 'locked', nullable — Activation state of a physical card. Null for virtual cards.
  - `spendLimit` object, nullable — Spending controls applied to this card.
    - `amountCents` integer, required — Maximum total spend allowed per interval, in cents.
    - `atmAmountCents` integer, nullable — Maximum ATM withdrawal allowed per interval, in cents. Null for virtual cards.
    - `interval` 'daily' | 'weekly' | 'monthly', required — Rolling window the limit applies to.
  - `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).
  - `updatedAt` string, yyyy-mm-ddThh:MM:ssZ, required — Timestamp of the last modification to the card or its settings.
  - `userId` string, required — Mercury User who owns the card.

## Other responses

- `400` — Invalid `body`

## Changes

- **2026-06-05** `b94507e2a9ea` — 2 info
  - the request property `accountId` became nullable
  - the request property `accountId` became optional
- **2026-05-27** `49d8bf266e65` — 5 breaking, 1 warning
  - added `#/components/schemas/CreateSpendLimit` to the `spendLimit` request property `allOf` list
  - added `#/components/schemas/TransactionPartyId, subschema #2` to the `accountId` request property `allOf` list
  - added `#/components/schemas/UserId, subschema #2` to the `userId` request property `allOf` list
  - the `accountId` request property type changed from `string` to no type
  - …2 more
- **2026-04-28** `314f542b4d39` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/cards/post.md)

---

[API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) · [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mercurytechnologies/mercury-api/revisions/621b18bfbb91/schema)