Mercury: Create a card
Mercury cards.createCard: arguments, response, policy and SDK examples.
← Cards operations · Get started
Operation mercury.createcard
Provider route: POST /cards. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/mercury with npm, or alter-sdk-mercury with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { MercuryIntegration } from "@alter-ai/mercury";
async function execute(input: Parameters<MercuryIntegration["cards"]["createCard"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new MercuryIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.cards.createCard(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_mercury import MercuryIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = MercuryIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.cards.create_card(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | Model | Optional | Expand Create a card — request body — body |
Referenced models: Create a card — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Get a card — response body |
Referenced models: Get a card — response body
Schemas
Section titled “Schemas”6 more schemas are linked from the tables above, on the schema pages.
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
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
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]+)?$ |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: mercury.createcard. Catalog operation: mercury:createCard. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.