Mercury: Cards schemas
12 Mercury schemas with complete fields and constraints.
← Cards operations · All schemas
Create a card — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
accountId | JSON | Optional | |
accountId (anyOf 1) | JSON | Alternative | |
accountId (anyOf 1) (allOf 1) | string | All variants apply | ID for a Mercury account. Format: uuid |
accountId (anyOf 1) (allOf 2) | JSON | All variants apply | 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@. |
accountId (anyOf 2) | null | Alternative | |
cardConfiguration | JSON | Optional | |
cardConfiguration (anyOf 1) | JSON | Alternative | |
cardConfiguration (anyOf 1) (allOf 1) | Model | All variants apply | Expand Create a card — request body — body card Configuration single Use single Use |
cardConfiguration (anyOf 1) (allOf 2) | JSON | All variants apply | Optional card configuration (single-use, agent, etc.) |
cardConfiguration (anyOf 2) | null | Alternative | |
kind | JSON | Required within parent | |
kind (allOf 1) | string | All variants apply | One of: debit, credit |
kind (allOf 2) | JSON | All variants apply | Whether to issue a debit or credit card. |
nickname | JSON | Optional | |
nickname (anyOf 1) | string | Alternative | Optional user-assigned label for the card. |
nickname (anyOf 2) | null | Alternative | |
spendLimit | JSON | Optional | |
spendLimit (anyOf 1) | JSON | Alternative | |
spendLimit (anyOf 1) (allOf 1) | Model | All variants apply | Expand Create a card — request body — body spend Limit Spending controls to apply at issuance amount Cents, interval |
spendLimit (anyOf 1) (allOf 2) | JSON | All variants apply | Spending controls to apply at issuance. |
spendLimit (anyOf 2) | null | Alternative | |
type | JSON | Required within parent | |
type (allOf 1) | string | All variants apply | One of: virtual |
type (allOf 2) | JSON | All variants apply | The type of card to issue. |
userId | JSON | Required within parent | |
userId (allOf 1) | string | All variants apply | ID for the user Format: uuid |
userId (allOf 2) | JSON | All variants apply | The user to assign as the cardholder. |
Referenced models: Create a card — request body — body card Configuration single Use single Use, Create a card — request body — body spend Limit Spending controls to apply at issuance amount Cents, interval
Create a card — request body — body card Configuration single Use single Use
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The configuration of a card. Used both as the read-side response alongside @cardConfiguration@ and as an alternative input at issuance time. Additional keys: not allowed |
singleUse | boolean | Required within parent | Whether this card auto-cancels itself on the first approved non-zero authorization. Must be 'False' for physical cards. |
Create a card — request body — body spend Limit Spending controls to apply at issuance amount Cents, interval
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
amountCents | integer | Required within parent | Maximum total spend allowed per interval, in cents. Minimum: 0 |
interval | JSON | Required within parent | |
interval (allOf 1) | string | All variants apply | One of: daily, weekly, monthly, yearly |
interval (allOf 2) | JSON | All variants apply | Rolling window the limit applies to. |
Get a card — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accountId | string | Required within parent | The Mercury account this card is associated with. |
budgets | array | Required within parent | One entry per active budget linked to this card and cardholder. Empty under cardLimit, or when this response has no active budget for the cardholder. |
budgets[] | Model | Each item | Expand Get a card — response body — budgets item |
categoryLocks | array | Required within parent | Mercury spend-category locks applied to this card, in no particular order. Empty when the card has no category restrictions. |
categoryLocks[] | Model | Each item | Expand Get a card — response body — category Locks item |
createdAt | JSON | Required within parent | |
createdAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
createdAt (allOf 2) | JSON | All variants apply | Timestamp when the card was issued. |
expiration | JSON | Required within parent | |
expiration (allOf 1) | Model | All variants apply | Expand Get a card — response body — expiration Month and year the card expires |
expiration (allOf 2) | JSON | All variants apply | Month and year the card expires. |
id | string | Required within parent | Unique identifier for the card. Format: uuid |
isAgentCard | boolean | Required within parent | Whether the card is managed by the agentic spend-management agent. Only agent cards can have their full details revealed. |
isSingleUse | boolean | Required within parent | Whether the card closes automatically after its first approved purchase. A used single-use card reports a @singleUseConsumed@ status. |
kind | JSON | Required within parent | |
kind (allOf 1) | string | All variants apply | Known values: debit, credit |
kind (allOf 2) | JSON | All variants apply | Whether the card is a debit or credit card. |
lastFour | string | Required within parent | Last four digits of the card's primary account number (PAN). |
merchantLock | JSON | Optional | |
merchantLock (anyOf 1) | JSON | Alternative | |
merchantLock (anyOf 1) (allOf 1) | Model | All variants apply | Expand List merchants — response body — data item |
merchantLock (anyOf 1) (allOf 2) | JSON | All variants apply | Merchant lock applied to this card. Present only when the card is locked to a single merchant; otherwise omitted. |
merchantLock (anyOf 2) | null | Alternative | |
nameOnCard | string | Required within parent | Cardholder name printed on the card. |
nickname | JSON | Optional | |
nickname (anyOf 1) | string | Alternative | Optional user-assigned label for the card. |
nickname (anyOf 2) | null | Alternative | |
physicalCardStatus | JSON | Optional | |
physicalCardStatus (anyOf 1) | JSON | Alternative | |
physicalCardStatus (anyOf 1) (allOf 1) | string | All variants apply | Known values: inactive, active, locked |
physicalCardStatus (anyOf 1) (allOf 2) | JSON | All variants apply | Activation state of a physical card. Null for virtual cards. |
physicalCardStatus (anyOf 2) | null | Alternative | |
spendLimit | JSON | Optional | |
spendLimit (anyOf 1) | JSON | Alternative | |
spendLimit (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get a card — response body — spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card |
spendLimit (anyOf 1) (allOf 2) | JSON | All variants apply | Card-level spending controls. This is null when card-level limits are unavailable, including for credit cards governed by budgets. For debit cards, this includes the underlying card limits even when budgets govern purchase spending. In budget mode, the transaction limit does not gate purchases, but the ATM or cash limit can still apply to cash withdrawals. |
spendLimit (anyOf 2) | null | Alternative | |
spendLimitType | JSON | Required within parent | |
spendLimitType (allOf 1) | string | All variants apply | Known values: cardLimit, budgets |
spendLimitType (allOf 2) | JSON | All variants apply | Whether card-level limits or budgets govern purchase spending. |
status | JSON | Required within parent | |
status (allOf 1) | string | All variants apply | Known values: active, frozen, cancelled, inactive, expired, suspended, singleUseConsumed |
status (allOf 2) | JSON | All variants apply | Current lifecycle state of the card. |
type | JSON | Required within parent | |
type (allOf 1) | string | All variants apply | Known values: virtual, physical |
type (allOf 2) | JSON | All variants apply | Whether the card is virtual (digital-only) or physical (printed, supports ATM). |
updatedAt | JSON | Required within parent | |
updatedAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
updatedAt (allOf 2) | JSON | All variants apply | Timestamp of the last modification to the card or its settings. |
userId | string | Required within parent | Mercury User who owns the card. |
Referenced models: Get a card — response body — budgets item, Get a card — response body — expiration Month and year the card expires, List merchants — response body — data item, Get a card — response body — category Locks item, Get a card — response body — spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card
Get a card — response body — budgets item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Current-cycle limits for one budget linked to this card and cardholder. |
amountCents | JSON | Required within parent | |
amountCents (anyOf 1) | integer | Alternative | The cardholder's spend limit for the current budget cycle, in cents. Minimum: 0 |
amountCents (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
id | string | Required within parent | Unique identifier for a budget Format: uuid |
name | string | Required within parent | Display name of the budget. |
remainingAmountCents | JSON | Required within parent | |
remainingAmountCents (anyOf 1) | integer | Alternative | Current-cycle limit minus recorded spend, clamped at zero, in cents. Authorization also uses cached allocations and in-flight holds, so its available amount may differ. Minimum: 0 |
remainingAmountCents (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Get a card — response body — category Locks item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | Known values: Other, Advertising, Airlines, AlcoholAndBars, BooksAndNewspaper, CarRental, Charity, Clothing, Conferences, Education, Electronics, Entertainment, FacilitiesExpenses, Fees, FoodDelivery, FuelAndGas, Gambling, GovernmentServices, Grocery, GroundTransportation, Insurance, InternetAndTelephone, Legal, Lodging, Medical, Memberships, OfficeSupplies, OtherTravel, Parking, Political, ProfessionalServices, Restaurants, Retail, RideshareAndTaxis, Shipping, Software, Taxes, Utilities, VehicleExpenses |
Get a card — response body — expiration Month and year the card expires
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Month and year the card expires. |
month | JSON | Required within parent | |
month (anyOf 1) | integer | Alternative | Calendar month. Maximum: 12 Minimum: 1 |
month (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
year | JSON | Required within parent | |
year (anyOf 1) | integer | Alternative | Four-digit calendar year. Maximum: 2999 Minimum: 2000 |
year (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Get a card — response body — spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Spending controls applied to a card |
amountCents | JSON | Required within parent | |
amountCents (anyOf 1) | integer | Alternative | Maximum total spend allowed per interval, in cents. Minimum: 0 |
amountCents (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
atmAmountCents | JSON | Optional | |
atmAmountCents (anyOf 1) | JSON | Alternative | |
atmAmountCents (anyOf 1) (anyOf 1) | integer | Alternative | Maximum ATM withdrawal allowed per interval, in cents. Null for virtual cards and credit cards. Minimum: 0 |
atmAmountCents (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
atmAmountCents (anyOf 2) | null | Alternative | |
interval | JSON | Required within parent | |
interval (allOf 1) | string | All variants apply | Known values: daily, weekly, monthly, yearly |
interval (allOf 2) | JSON | All variants apply | Rolling window the limit applies to. |
List cards — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
cards | array | Required within parent | List of cards in the current page. |
cards[] | Model | Each item | Expand Get a card — response body |
page | object | Required within parent | Pagination cursors for navigating to next/previous pages. |
page.nextPage | string | Optional | Unique identifier for a card Format: uuid |
page.previousPage | string | Optional | Unique identifier for a card Format: uuid |
Referenced models: Get a card — response body
Update a card — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | At least one updateable field must be provided; requests where every field is the same are rejected. Additional keys: not allowed |
nickname | JSON | Optional | |
nickname (allOf 1) | Model | All variants apply | Expand Update a card — request body — body nickname value |
nickname (allOf 2) | JSON | All variants apply | Updated card nickname. Omit to keep current, send null/empty to clear, send a string to set. |
spendLimit | JSON | Optional | |
spendLimit (anyOf 1) | JSON | Alternative | |
spendLimit (anyOf 1) (allOf 1) | Model | All variants apply | Expand Update a card — request body — body spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card |
spendLimit (anyOf 1) (allOf 2) | JSON | All variants apply | Updated spending controls for the card. Omit to leave unchanged. |
spendLimit (anyOf 2) | null | Alternative |
Referenced models: Update a card — request body — body nickname value, Update a card — request body — body spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card
Update a card — request body — body nickname value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | string | Alternative | Nickname update action. Omit the field to keep the current nickname, send null or an empty/whitespace-only string to clear it, or send a string to set it. |
$ (anyOf 2) | null | Alternative |
Update a card — request body — body spend Limit amount Cents, atm Amount Cents, interval Spending controls applied to a card
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Spending controls applied to a card Additional keys: not allowed |
amountCents | integer | Required within parent | Maximum total spend allowed per interval, in cents. Minimum: 0 |
atmAmountCents | JSON | Optional | |
atmAmountCents (anyOf 1) | integer | Alternative | Maximum ATM withdrawal allowed per interval, in cents. Null for virtual cards and credit cards. Minimum: 0 |
atmAmountCents (anyOf 2) | null | Alternative | |
interval | JSON | Required within parent | |
interval (allOf 1) | string | All variants apply | One of: daily, weekly, monthly, yearly |
interval (allOf 2) | JSON | All variants apply | Rolling window the limit applies to. |