Create and manage physical and virtual payment cards.
Cards are always associated with a user and derived from a card product.
Card states
UNACTIVATED— newly issued, requires explicit activationACTIVE— active and usable for transactionsSUSPENDED— temporarily frozen; no transactionsTERMINATED— permanently closed; cannot be reactivatedLIMITED— restricted to certain transaction typesUNSUPPORTED— card type not supported in current context
Attribute precedence
card → bulkissuance → cardproduct (higher overrides lower,
does not overwrite lower-precedence values).
Examples
# Virtual card
{:ok, card} = Marqeta.Cards.create(%{
user_token: "user_01",
card_product_token: "cp_01"
})
# Physical card with shipping
{:ok, card} = Marqeta.Cards.create(%{
user_token: "user_01",
card_product_token: "physical_cp_01",
fulfillment: %{
card_personalization: %{text: %{name_line_1: %{value: "Jane Doe"}}},
shipping: %{
method: "TWO_DAY",
recipient_address: %{
first_name: "Jane",
last_name: "Doe",
address1: "123 Main St",
city: "San Francisco",
state: "CA",
zip: "94105",
country: "USA"
}
}
}
})
# Reissue with same PAN (lost / damaged replacement)
{:ok, card} = Marqeta.Cards.create(%{
user_token: "user_01",
card_product_token: "cp_01",
reissue_pan_from_card_token: "old_card_token"
})Summary
Functions
Creates a new card.
Retrieves a card by token.
Lists card resources.
Lists card resources. Raises Marqeta.Error on failure.
Lists all cards for a business.
Lists cards matching the last 4 digits of their PAN. Returns up to 10 per page.
Lists all cards for a user.
Returns merchant-specific data about where a card has been used.
Retrieves a card with the full PAN and CVV2 included.
Returns a lazy Stream that auto-paginates card resources.
Returns a lazy stream of all cards for a business.
Returns a lazy stream of all cards for a user.
Returns a lazy stream of transactions for a card.
Lists transactions for a card.
Updates an existing card.
Updates an existing card. Raises Marqeta.Error on failure.
Functions
@spec create( map(), keyword() ) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Creates a new card.
Options
:show_pan— include full PAN in response (PCI DSS required):show_cvv_number— include CVV2 in response (PCI DSS required)
@spec get( String.t(), keyword() ) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Retrieves a card by token.
Options
:show_pan— include full PAN in response (PCI DSS required):show_cvv_number— include CVV2 in response (PCI DSS required)
@spec list( map(), keyword() ) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Lists card resources.
Accepts standard Marqeta pagination params:
count, start_index, sort_by, sort_order, fields.
Use stream/2 to lazily iterate all pages automatically.
Lists card resources. Raises Marqeta.Error on failure.
@spec list_by_business(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Lists all cards for a business.
@spec list_by_last_four(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Lists cards matching the last 4 digits of their PAN. Returns up to 10 per page.
@spec list_by_user(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Lists all cards for a user.
@spec merchant_scope(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Returns merchant-specific data about where a card has been used.
@spec show_pan( String.t(), keyword() ) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Retrieves a card with the full PAN and CVV2 included.
Requires PCI DSS compliance. Sets fulfillment_status to DIGITALLY_PRESENTED.
@spec stream( map(), keyword() ) :: Enumerable.t()
Returns a lazy Stream that auto-paginates card resources.
@spec stream_by_business(String.t(), map()) :: Enumerable.t()
Returns a lazy stream of all cards for a business.
@spec stream_by_user(String.t(), map()) :: Enumerable.t()
Returns a lazy stream of all cards for a user.
@spec stream_transactions(String.t(), map()) :: Enumerable.t()
Returns a lazy stream of transactions for a card.
@spec transactions(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Lists transactions for a card.
@spec update(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Marqeta.Error.t()}
Updates an existing card.
Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.
Updates an existing card. Raises Marqeta.Error on failure.