Cards List

Cards List
Certified
List Mercury cards

Retrieve credit and debit cards across an organization from Mercury with automatic cursor-based pagination and filtering.

yaml
type: io.kestra.plugin.mercury.cards.List

Examples

List all Mercury cards into memory

yaml
id: list_mercury_cards
namespace: company.team

tasks:
  - id: list_cards
    type: io.kestra.plugin.mercury.cards.List
    apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
    fetchType: FETCH

List active virtual debit cards for a specific account

yaml
id: list_active_virtual_cards
namespace: company.team

tasks:
  - id: list_cards
    type: io.kestra.plugin.mercury.cards.List
    apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
    accountId: "4b54e3d6-72aa-4c07-b3c6-9f4a56a64010"
    status: ACTIVE
    cardType: VIRTUAL
    kind: DEBIT
    fetchType: FETCH

Stream all Mercury cards to internal storage

yaml
id: store_mercury_cards
namespace: company.team

tasks:
  - id: store_cards
    type: io.kestra.plugin.mercury.cards.List
    apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
    fetchType: STORE

Installation

Our standard Docker images already include this plugin. If you use a -slim image or another setup, install it with the following command:

kestractl plugins get io.kestra.plugin:plugin-mercury --compatible-for $KESTRA_VERSION

For kestractl, use your Kestra version with --compatible-for, or specify an exact plugin version.

For Kestra CLI, replace LATEST with a specific version or version range to pin the plugin version.

Properties

apiToken *string

Mercury API token

API token for authentication with the Mercury API.

accountId string

Account ID filter

Optional filter to retrieve cards associated with a specific Mercury bank account ID (UUID).

assets

Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.

Definitions

io.kestra.core.models.assets.AssetsDeclaration

assetFailureBehaviorstring

Possible Values

IGNOREFAILWARN

Asset failure behavior

Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.

enableAutobooleanstring

Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.

inputsarray

The assets consumed as inputs.

io.kestra.core.models.assets.AssetIdentifier

id*string

Min length1

typestring

outputs

The assets produced as outputs.

io.kestra.plugin.ee.assets.Dataset

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.File

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.Table

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.VM

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.External

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.Custom

id*string

Min length1

Max length150

type*string

Min length1

Custom asset type

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

baseUrl string

Defaulthttps://api.mercury.com/api/v1

Mercury API base URL

Base URL for the Mercury API. Override for the Mercury sandbox (https://api-sandbox.mercury.com/api/v1). Must use HTTPS, except for loopback hosts (localhost, 127.0.0.1, ::1) during local testing.

cardType string

Possible Values

VIRTUALPHYSICAL

Card type filter

Filter cards by type: VIRTUAL or PHYSICAL.

fetchType string

DefaultFETCH

Possible Values

STOREFETCHFETCH_ONENONE

Fetch mode

Controls how results are returned: FETCH to return all rows in memory, FETCH_ONE for the first row, STORE to stream records as ION into internal storage, or NONE to skip collecting outputs.

isAgentCard booleanstring

Is agent card filter

Filter cards by whether they are managed by the spend-management agent.

kind string

Possible Values

DEBITCREDIT

Card kind filter

Filter cards by kind: DEBIT or CREDIT.

limit integerstring

Default500

Results per page

Maximum number of cards to return per page. Minimum 1, maximum 1000. Default is 500.

order string

Possible Values

ASCDESC

Sort order

Sort order of the returned records. Allowed values: ASC or DESC. Defaults to ASC for accounts, cards, and recipients; defaults to DESC for statements.

pageCap integerstring

Default100

Maximum pages to retrieve

Safety cap on the number of pages fetched during pagination. Minimum 1. Default is 100.

status string

Possible Values

ACTIVEFROZENCANCELLEDINACTIVEEXPIREDSUSPENDED

Card status filter

Filter cards by lifecycle status: ACTIVE, FROZEN, CANCELLED, INACTIVE, EXPIRED, or SUSPENDED.

userId string

Cardholder user ID filter

Filter cards by the cardholder's Mercury user ID.

Outputs

row

The first card fetched

The first card retrieved. Only populated when fetchType is FETCH_ONE.

Definitions

io.kestra.plugin.mercury.model.Card

accountIdstring

Account ID

The unique identifier (UUID) of the Mercury bank account associated with this card.

budgetsarray

Budgets

Active budget limits linked to this card and cardholder, in cents. Empty under cardLimit or when no budget is linked.

io.kestra.plugin.mercury.model.Card-Budget

amountCentsinteger

Budget amount in cents

The cardholder's spend limit for the current budget cycle, in cents.

idstring

Budget ID

Unique identifier (UUID) for this budget.

namestring

Budget name

Display name of the budget.

remainingAmountCentsinteger

Remaining budget amount in cents

Current-cycle limit minus recorded spend, clamped at zero, in cents.

categoryLocksarray

SubTypestring

Category locks

List of Mercury spend category names locked on this card. Empty when no category restrictions apply.

createdAtstring

Formatdate-time

Created at timestamp

Timestamp when the card was issued.

expiration

Card expiration

Month and year the card expires.

io.kestra.plugin.mercury.model.Card-Expiration

monthinteger

Expiration month

Two-digit calendar month when the card expires (1-12).

yearinteger

Expiration year

Four-digit calendar year when the card expires (2000-2999).

idstring

Card ID

The unique identifier (UUID) for this card.

isAgentCardboolean

Is agent card

Whether the card is managed by the agentic spend-management agent.

kindstring

Card kind

Funding kind of the card. Possible values: debit, credit.

lastFourstring

Last four digits

Last four digits of the primary account number (PAN). Note that full PAN and CVC are never returned by the list cards endpoint.

merchantLock

Merchant lock

Merchant lock applied to this card, restricting purchases to a single vendor. Null when not locked to a merchant.

io.kestra.plugin.mercury.model.Card-MerchantLock

idstring

Merchant ID

Unique identifier (UUID) of the locked merchant.

namestring

Merchant name

Display name of the locked merchant.

nameOnCardstring

Name on card

Cardholder name embossed or printed on the card.

nicknamestring

Card nickname

Optional user-assigned label or nickname for the card.

physicalCardStatusstring

Physical card status

Activation state of a physical card. Null for virtual cards. Possible values: inactive, active, locked.

spendLimit

Spend limit

Card-level spending controls in cents. Null when limits are unavailable or governed by budgets.

io.kestra.plugin.mercury.model.Card-SpendLimit

amountCentsinteger

Spend limit in cents

Maximum total spend allowed per rolling interval, in cents.

atmAmountCentsinteger

ATM limit in cents

Maximum ATM cash withdrawal allowed per rolling interval, in cents. Null for virtual cards and credit cards.

intervalstring

Spend limit interval

Rolling time window the spend limit applies to. Possible values: daily, weekly, monthly, yearly.

spendLimitTypestring

Spend limit type

Whether card-level limits or budgets govern purchase spending. Possible values: cardLimit, budgets.

statusstring

Card status

Current lifecycle state of the card. Possible values: active, frozen, cancelled, inactive, expired, suspended.

typestring

Card type

Physical form factor of the card. Possible values: virtual, physical.

updatedAtstring

Formatdate-time

Updated at timestamp

Timestamp of the most recent modification to the card or its settings.

userIdstring

User ID

Identifier of the Mercury user who owns and is assigned to the card.

rows array

The cards fetched

List of retrieved cards. Only populated when fetchType is FETCH.

Definitions

io.kestra.plugin.mercury.model.Card

accountIdstring

Account ID

The unique identifier (UUID) of the Mercury bank account associated with this card.

budgetsarray

Budgets

Active budget limits linked to this card and cardholder, in cents. Empty under cardLimit or when no budget is linked.

io.kestra.plugin.mercury.model.Card-Budget

amountCentsinteger

Budget amount in cents

The cardholder's spend limit for the current budget cycle, in cents.

idstring

Budget ID

Unique identifier (UUID) for this budget.

namestring

Budget name

Display name of the budget.

remainingAmountCentsinteger

Remaining budget amount in cents

Current-cycle limit minus recorded spend, clamped at zero, in cents.

categoryLocksarray

SubTypestring

Category locks

List of Mercury spend category names locked on this card. Empty when no category restrictions apply.

createdAtstring

Formatdate-time

Created at timestamp

Timestamp when the card was issued.

expiration

Card expiration

Month and year the card expires.

io.kestra.plugin.mercury.model.Card-Expiration

monthinteger

Expiration month

Two-digit calendar month when the card expires (1-12).

yearinteger

Expiration year

Four-digit calendar year when the card expires (2000-2999).

idstring

Card ID

The unique identifier (UUID) for this card.

isAgentCardboolean

Is agent card

Whether the card is managed by the agentic spend-management agent.

kindstring

Card kind

Funding kind of the card. Possible values: debit, credit.

lastFourstring

Last four digits

Last four digits of the primary account number (PAN). Note that full PAN and CVC are never returned by the list cards endpoint.

merchantLock

Merchant lock

Merchant lock applied to this card, restricting purchases to a single vendor. Null when not locked to a merchant.

io.kestra.plugin.mercury.model.Card-MerchantLock

idstring

Merchant ID

Unique identifier (UUID) of the locked merchant.

namestring

Merchant name

Display name of the locked merchant.

nameOnCardstring

Name on card

Cardholder name embossed or printed on the card.

nicknamestring

Card nickname

Optional user-assigned label or nickname for the card.

physicalCardStatusstring

Physical card status

Activation state of a physical card. Null for virtual cards. Possible values: inactive, active, locked.

spendLimit

Spend limit

Card-level spending controls in cents. Null when limits are unavailable or governed by budgets.

io.kestra.plugin.mercury.model.Card-SpendLimit

amountCentsinteger

Spend limit in cents

Maximum total spend allowed per rolling interval, in cents.

atmAmountCentsinteger

ATM limit in cents

Maximum ATM cash withdrawal allowed per rolling interval, in cents. Null for virtual cards and credit cards.

intervalstring

Spend limit interval

Rolling time window the spend limit applies to. Possible values: daily, weekly, monthly, yearly.

spendLimitTypestring

Spend limit type

Whether card-level limits or budgets govern purchase spending. Possible values: cardLimit, budgets.

statusstring

Card status

Current lifecycle state of the card. Possible values: active, frozen, cancelled, inactive, expired, suspended.

typestring

Card type

Physical form factor of the card. Possible values: virtual, physical.

updatedAtstring

Formatdate-time

Updated at timestamp

Timestamp of the most recent modification to the card or its settings.

userIdstring

User ID

Identifier of the Mercury user who owns and is assigned to the card.

size integer

The total number of cards returned

For FETCH this matches the size of rows, for FETCH_ONE 0 or 1, for STORE the count of stored records, and 0 for NONE.

uri string

Formaturi

URI of stored results

The URI of the file containing ION-formatted records in internal storage. Only populated when fetchType is STORE.

Dataform

Tasks that run Dataform data transformations through the Dataform CLI.

Data

Huawei

Huawei plugin for Kestra

CloudDataInfrastructure

Cards ListCertifiedList Mercury cards

More Plugins in this Category

Dataform

Huawei

Cards List
Certified
List Mercury cards