/
225 minute read
March 24, 2022

Card Products

The card products resource represents the behavior and functionality of one or more cards (either physical or virtual). For example, attributes of the card product determine whether the associated cards can be used at an ATM and/or online and whether they are currently enabled. For physical cards, the card product determines color and other printing specifications for when the cards are manufactured and personalized. You can optionally associate authorization controls and/or velocity controls with card products to restrict where and how associated cards are used.

If your program is Managed by Marqeta, then Marqeta will create the card products for your production environment.

Some attributes of the cardproduct object can also be defined in an associated bulkissuance or card object. If you define one of these attributes in more than one object, the Marqeta platform applies an order of precedence to determine which attribute to use at fulfillment time. The order of precedence is as follows:

  • card

  • bulkissuance

  • cardproduct

Defining an attribute in an object with higher precedence does not overwrite the same attribute in a lower-precedence object; the Marqeta platform ignores these lower-precedence attributes.

For more information on cards, see About Cards.

Create card product

Action: POST
Endpoint: /cardproducts

Use this endpoint to create a card product.

The card product request contains a set of fields that provide basic information about the card product, such as name, active status, and start and end dates. Configuration information is contained in the config object, which contains sub-elements whose fields control the features and behavior of the card product. The elements are referred to collectively as the card product "configuration," and as such are contained in a config object.

Request body
Fields Description

active

boolean
Optional

Indicates whether the card product is active.

NOTE: This field has no effect on the ability to create cards from this card product. Use the config.fulfillment.allow_card_creation field to allow/disallow card creation.

Allowable Values:

true, false

Default value:
true

config

object
Optional

Defines the characteristics of the card product. Configurations are conditionally required based on program setup.

Allowable Values:

A valid config object

config.card_life_cycle

object
Optional

Defines characteristics of the lifecycle of cards of this card product type.

Allowable Values:

A valid card_life_cycle object

config.card_life_cycle.activate_upon_issue

boolean
Optional

A value of true indicates that cards of this card product type are active once they are issued.

Allowable Values:

true, false

Default value:
false

config.card_life_cycle.card_service_code

integer
Optional

A sequence of three digits that defines various services, differentiates card usage in international or domestic interchange, designates PIN and authorization requirements, and identifies card restrictions. The following values are commonly used:

First digit

  • 1 — International interchange OK

  • 2 — International interchange, use IC (chip) where feasible

  • 5 — National interchange only except under bilateral agreement

  • 6 — National interchange only except under bilateral agreement, use IC (chip) where feasible

  • 7 — No interchange except under bilateral agreement (closed loop)

  • 9 — Test

Second digit

  • 0 — Normal

  • 2 — Contact issuer via online means

  • 4 — Contact issuer via online means except under bilateral agreement

Third digit

  • 0 — No restrictions, PIN required

  • 1 — No restrictions

  • 2 — Goods and services only (no cash)

  • 3 — ATM only, PIN required

  • 4 — Cash only

  • 5 — Goods and services only (no cash), PIN required

  • 6 — No restrictions, use PIN where feasible

  • 7 — Goods and services only (no cash), use PIN where feasible

Allowable Values:

100 - 999

Default value:
101

config.card_life_cycle.expiration_offset

object
Optional

Specifies the length of time after the date of issue for which cards of this card product type are valid.

Allowable Values:

A valid expiration_offset object

config.card_life_cycle.expiration_offset.min_offset

object
Optional

Specifies the minimum length of time after the date of issue for which the cards are valid.

Allowable Values:

Valid min_offset object

config.card_life_cycle.expiration_offset.min_offset.unit

string
Optional

Specifies the minimum offset unit.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default Value
expiration_offset.unit

config.card_life_cycle.expiration_offset.min_offset.value

integer
Optional

Specifies the minimum offset value.

Allowable Values:

Default Value
expiration_offset.value

config.card_life_cycle.expiration_offset.unit

string
Optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value:
YEARS

config.card_life_cycle.expiration_offset.value

integer
Optional

Specifies the number of time units (as defined by the unit field in this object) that cards of this card product type are valid. In other words, cards expire value x unit after the date of issue.

This number is rounded as follows:

  • YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and value = 1, the cards expire on the last day of Jan 2022.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and value = 1, the cards expire on the last day of June 2022.

  • DAYS – Rounds up to the last second of the day of expiration.

  • HOURS, MINUTES, SECONDS – No rounding.

Allowable Values:

Any positive integer

Default value:
4

config.card_life_cycle.update_expiration_upon_activation

boolean
Optional

Normally, the expiration_offset is measured from the date of issue. Set this field to true to measure expiration_offset from the date of activation instead.

Allowable Values:

true, false

Default value:
false

config.clearing_and_settlement

object
Optional

Specifies the destination for overdraft funds.

Allowable Values:

A valid clearing_and_settlement object

config.clearing_and_settlement.overdraft_destination

string
Optional

Specifies the destination for overdraft funds.

This field does not apply if JIT Funding is enabled.

Allowable Values:

GPA, MSA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value:
GPA

config.digital_wallet_tokenization

object
Optional

Controls characteristics related to digital wallets.

Allowable Values:

A valid digital_wallet_tokenization object

config.digital_wallet_tokenization.card_art_id

string
Optional

Specifies the digital wallet card art identifier for the card product. Digital wallets display the card art after the initial token has been provisioned and activated. Digital wallet card art is updated for all wallets automatically whenever a tokenized card is reissued or replaced.

  • If your card program is Managed by Marqeta, Marqeta populates this field on your behalf.

  • If your card program is Powered by Marqeta, you can obtain the correct card art identifier directly from Visa or Mastercard.

If this field is left blank, your card product inherits the card art assigned to the account BIN range.

Allowable Values:

Valid identifiers are defined by Visa or Mastercard and vary by program:

  • For Visa card products, this identifier is a GUID called profileID.

  • For Mastercard card products, this identifier is a string called ProductConfigID.

config.digital_wallet_tokenization.provisioning_controls

object
Optional

Controls the provisioning of digital wallets.

Allowable Values:

A valid provisioning_controls object

config.digital_wallet_tokenization.provisioning_controls.in_app_provisioning

object
Optional

Controls the provisioning of digital wallets by a Marqeta customer’s mobile application.

Allowable Values:

A valid in_app_provisioning object

config.digital_wallet_tokenization.provisioning_controls.manual_entry

object
Optional

Controls the provisioning of digital wallets by manual entry, in which the cardholder manually enters the card’s PAN, CVV2, and expiration date.

Allowable Values:

A valid manual_entry object

config.digital_wallet_tokenization.provisioning_controls.wallet_provider_card_on_file

object
Optional

Controls the provisioning of digital wallets where the digital wallet provider already has the card on file.

Allowable Values:

A valid wallet_provider_card_on_file object

config.digital_wallet_tokenization.provisioning_controls.web_push_provisioning

object
Optional

Specifies the digital wallet card art and program configuration identifiers at the card product level for Web Push Provisioning.

Allowable Values:

A valid web_push_provisioning object

config.fulfillment

object
Optional

Determines physical characteristics of a card, along with its bulk shipment information.

Allowable Values:

A valid fulfillment object

config.fulfillment.all_zero_card_security_code

boolean
Optional

If true, an all zero code (000) is allowed as a valid value in an authorization request.

Allowable Values:

true, false

Default value:
false

config.fulfillment.allow_card_creation

boolean
Optional

Controls the ability to create cards from this card product; true allows and false disallows the creation of cards.

NOTE: The card product’s active field has no effect on card creation or the behavior of this field.

Allowable Values:

true, false

Default value:
true

config.fulfillment.bin_prefix

string
Optional

The prefix of the bank identification number.

Allowable Values:

A six-digit number for the sandbox environment; a six- to nine-digit number is expected in production environments (see note below).

Default value:
111111

NOTE: In the sandbox environment or when testing against OpenAPI (Swagger), this field must be set to 111111. It is preferable to use eight- or nine-digit BIN prefixes in production environments. Contact your Marqeta representative for the appropriate value to use.

config.fulfillment.bulk_ship

boolean
Optional

Enables bulk ordering of cards of this card product type using the /bulkissuances endpoint.

Allowable Values:

true, false

Default value:
false

config.fulfillment.card_personalization

object
Required

Allows personalized attributes to be added to the card product.

Allowable Values:

A valid card_personalization object

config.fulfillment.card_personalization.carrier

object
Optional

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

config.fulfillment.card_personalization.carrier.logo_file

string
Optional

Specifies an image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Optional

Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.message_file

string
Optional

Specifies a text file containing a custom message to print on the card carrier.

Allowable Values:

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.message_line

string
Optional

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

config.fulfillment.card_personalization.carrier.template_id

string
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

config.fulfillment.card_personalization.images

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Existing images object

config.fulfillment.card_personalization.images.card

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

config.fulfillment.card_personalization.images.card.name

string
Optional

Specifies a PNG image to display on the card.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.card.thermal_color

string
Optional

Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color and must match one of the provider’s predefined colors.

config.fulfillment.card_personalization.images.carrier

object
Optional

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

config.fulfillment.card_personalization.images.carrier.message_1

string
Optional

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

config.fulfillment.card_personalization.images.carrier.name

string
Optional

Specifies a PNG image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.carrier_return_window

object
Optional

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Valid carrier_return_window object

config.fulfillment.card_personalization.images.carrier_return_window.name

string
Optional

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.signature

object
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

config.fulfillment.card_personalization.images.signature.name

string
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.perso_type

string
Optional

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

config.fulfillment.card_personalization.text

object
Required

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

config.fulfillment.card_personalization.text.name_line_1

object
Required

Specifies the first line of personalized text that appears on the card.

Allowable Values:

name_line_1.value

21 char max; if name_line_1_numeric_postfix is true, 14 char max

Strings longer than the character limit are truncated.

config.fulfillment.card_personalization.text.name_line_1.value

string
Optional

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.card_personalization.text.name_line_2

object
Optional

Specifies the second line of personalized text that appears on the card.

Allowable Values:

name_line_2.value

config.fulfillment.card_personalization.text.name_line_2.value

string
Optional

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.card_personalization.text.name_line_3

object
Optional

Specifies the third line of personalized text that appears on the card.

Allowable Values:

name_line_3.value

config.fulfillment.card_personalization.text.name_line_3.value

string
Optional

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.enable_offline_pin

boolean
Optional

Enables offline PIN verification for EMV ("chip-and-PIN") card payments.

Allowable Values:

true, false

Default value:
false

config.fulfillment.fulfillment_provider

string
Optional

Specifies the fulfillment provider.

NOTE: Expedited processing is available for cards that are fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions. You can expedite an order’s processing by using the expedite field of the card or bulkissuance object. Contact your Marqeta representative for information regarding the cost of expedited service.

Allowable Values:

PERFECTPLASTIC, ARROWEYE, IDEMIA, IDEMIA_UK, IDEMIA_FR, IDEMIA_CZ, IDEMIA_APAC, IDEMIA_PL, IDEMIA_AU, IDEMIA_LA, GEMALTO, NITECREST, OBERTHUR, ALLPAY, IDEMIA_FR_SC, GD, NITECREST_UK_SC, NITECREST_PL, TAG, IDEMIA_DE, FIS, CPI, EXCEET_DE, OBERTHUR_SC, IDEMIA_PE

Default value:
PERFECTPLASTIC

config.fulfillment.package_id

string
Optional

Card fulfillment provider’s package ID.

Allowable Values:

1–50 chars

config.fulfillment.pan_length

string
Optional

Specifies the length of the primary account number (PAN).

Allowable Values:

Default value: 16

config.fulfillment.payment_instrument

string
Optional

Specifies the physical form cards of this card product type will take.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

Default value:
PHYSICAL_MSR

config.fulfillment.shipping

object
Optional

Specifies shipping details for the order.

Allowable Values:

Valid shipping object

config.fulfillment.shipping.care_of_line

string
Optional

Adds the specified value as a care of (C/O) line to the mailing carrier.

Allowable Values:

255 char max

config.fulfillment.shipping.method

string
Optional

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.

config.fulfillment.shipping.recipient_address

object
Optional

Address to which the order will be shipped.

In order to generate cards, a valid shipping address must be provided by one of these:

  • The card or bulk card order’s fulfillment.shipping.recipient_address field

  • The users' address fields

  • The card product’s config.fulfillment.shipping.recipient_address field

The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the address1, city, state, and postal_code or zip fields populated. The country field defaults to USA if unpopulated.

Allowable Values:

Valid recipient_address object

config.fulfillment.shipping.recipient_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.recipient_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.recipient_address.city

string
Optional

City.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.country

string
Optional

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

config.fulfillment.shipping.recipient_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

config.fulfillment.shipping.recipient_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

config.fulfillment.shipping.recipient_address.state

string
Optional

State.

Allowable Values:

32 char max

config.fulfillment.shipping.recipient_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

config.fulfillment.shipping.return_address

object
Optional

Address to which the order will be returned if shipping fails.

Allowable Values:

Valid return_address object

config.fulfillment.shipping.return_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.return_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.return_address.city

string
Optional

City.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.country

string
Optional

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

config.fulfillment.shipping.return_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

config.fulfillment.shipping.return_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

config.fulfillment.shipping.return_address.state

string
Optional

State.

Allowable Values:

32 char max

config.fulfillment.shipping.return_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

config.fulfillment.uppercase_name_lines

boolean
Optional

A value of true sets the text in the fulfillment.card_personalization.text.name_line_1 and name_line_2 fields to all uppercase letters. A value of false leaves the text in its original state.

Allowable Values:

true, false

Default value:
true

config.jit_funding

object
Optional

Governs the behavior of JIT Funding.

Allowable Values:

A valid jit_funding object

config.jit_funding.paymentcard_funding_source

object
Optional

Allows for the enabling and configuration of a payment card funding source.

Allowable Values:

A valid paymentcard_funding_source object

config.jit_funding.paymentcard_funding_source.enabled

boolean
Optional

Specifies whether JIT Funding is enabled or disabled for the payment card funding source. A value of true indicates that the payment card funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.paymentcard_funding_source.refunds_destination

string
Optional

Specifies the return destination for refunds in the case of a transaction reversal.

Allowable Values:

GATEWAY, GPA, WATERFALL

config.jit_funding.program_funding_source

object
Optional

Allows for the enabling and configuration of a program funding source.

Allowable Values:

A valid program_funding_source object

config.jit_funding.program_funding_source.enabled

boolean
Optional

Specifies whether JIT Funding is enabled or disabled for the program funding source. A value of true indicates that the program funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.program_funding_source.funding_source_token

string
Optional

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

config.jit_funding.program_funding_source.refunds_destination

string
Optional

Specifies the return destination for refunds in the case of a transaction reversal. PROGRAM_FUNDING_SOURCE returns funds to the program funding source. GPA returns the funds to the user’s GPA.

Allowable Values:

PROGRAM_FUNDING_SOURCE, GPA, WATERFALL

config.jit_funding.programgateway_funding_source

object
Optional

Allows for the enabling and configuration of a program gateway funding source.

Allowable Values:

A valid programgateway_funding_source object

config.jit_funding.programgateway_funding_source.always_fund

boolean
Optional

If set to true, this card product is always funded from this program gateway funding source.

Allowable Values:

true, false

Default value:
false

config.jit_funding.programgateway_funding_source.enabled

boolean
Optional

Specifies whether JIT Funding is enabled or disabled for the program gateway funding source. A value of true indicates that the program gateway funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.programgateway_funding_source.funding_source_token

string
Optional

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

config.jit_funding.programgateway_funding_source.refunds_destination

string
Optional

Specifies the return destination for refunds in the case of a transaction reversal. In most cases, you should set the value to GATEWAY, which returns funds to the program gateway funding source. Setting to GPA returns the funds to the user’s GPA, which creates a positive account balance and introduces the potential of a transaction being authorized without a JIT Funding request being sent to the gateway.

Allowable Values:

GATEWAY, GPA, WATERFALL

config.poi

object
Optional

Governs the point of interaction.

Allowable Values:

A valid poi object

config.poi.atm

boolean
Optional

A value of true enables cards to be used for withdrawing cash at an ATM and for receiving cash back at a point of sale (POS).

Allowable Values:

true, false

Default value:
false

config.poi.ecommerce

boolean
Optional

A value of true enables cards to be used for online purchases.

Allowable Values:

true, false

Default value:
false

config.poi.other

object
Optional

Allows for configuration of points of interaction other than ecommerce or ATMs, such as points of sale (POS).

Allowable Values:

A valid other object

config.poi.other.allow

boolean
Optional

If set to true, card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes points of sale (POS).

Allowable Values:

true, false

Default value:
true

config.poi.other.card_presence_required

boolean
Optional

If set to true, cards of this card product type are required to be present during the transaction, such as in IVR scenarios.

Allowable Values:

true, false

Default value:
false

config.poi.other.cardholder_presence_required

boolean
Optional

A value of true indicates that the cardholder is required to be present, such as in a restaurant where the card is present but the cardholder is not present when the card is swiped.

Allowable Values:

true, false

Default value:
false

config.selective_auth

object
Optional

Contains information about authorization decisions.

Allowable Values:

A valid selective_auth object

config.selective_auth.dmd_location_sensitivity

integer
Optional

Determines what type of merchant information is required for a match (authorization). Not relevant if enable_regex_search_chain = false.

  • 0 – Requires exact match on card acceptor name and postal code to existing entry in Marqeta Merchant database (most restrictive).

  • 1 – Partial match on card acceptor name (least restrictive).

  • 2 – Partial match on card acceptor name; exact match on card acceptor city.

  • 3 – Partial match on card acceptor name; exact match on card acceptor postal code.

  • 4 – Partial match on card acceptor name; exact match on street address 1 and postal code.

Allowable Values:

0, 1, 2, 3, 4

Default value:
0

config.selective_auth.enable_regex_search_chain

boolean
Optional

Use true to perform regular expression checking on the description received in the authorization.

Allowable Values:

true , false

Default value:
false

config.selective_auth.sa_mode

integer
Optional

  • 0 — Inactive

  • 1 — Active (attempts to authorize a merchant that does not have a recognized MID by matching other pieces of information)

  • 2 — Logging and notification (checks the transaction and logs results, but does not authorize)

Selective authorization applies to transactions that are limited to specific merchants. Matching requirements for authorization are set by the dmd_location_sensitivity field.

Allowable Values:

0, 1, 2

Default value:
0

config.special

object
Optional

Contains information about merchant onboarding.

Allowable Values:

A valid special object

config.special.merchant_on_boarding

boolean
Optional

A value of true indicates cards of this card product type can be used for merchant onboarding.

Allowable Values:

true, false

Default value:
false

config.transaction_controls

object
Optional

Controls transactional characteristics of card usage.

Allowable Values:

A valid transaction_controls object

config.transaction_controls.accepted_countries_token

string
Optional

Set to accept_us_only to allow transactions only within the US.

Set to decline_ofac_countries to allow international transactions except with countries that the Financial Action Task Force (FATF) and Office of Foreign Assets Control (OFAC) have identified as high risk.

Users with the Admin role can create and update additional lists of accepted countries for transactions at the /acceptedcountries endpoint. See Accepted Countries.

Allowable Values:

accept_us_only, decline_ofac_countries, additional Admin-defined tokens

Default value:
accept_us_only

config.transaction_controls.address_verification

object
Optional

Contains configuration options for AVS.

Allowable Values:

A valid address_verification object

config.transaction_controls.address_verification.auth_messages

object
Optional

Contains verification options for authorization messages.

These messages pertain to actual purchases and are for amounts greater than $0.

Allowable Values:

A valid auth_messages object

config.transaction_controls.address_verification.av_messages

object
Optional

Contains verification options for account verification messages.

These are $0 messages typically used to store cards on file at a merchant.

Allowable Values:

A valid av_messages object

config.transaction_controls.allow_chip_fallback

boolean
Optional

Indicates whether to allow transactions where an EMV chip-enabled card was processed using the magstripe as fallback.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.allow_first_pin_set_via_financial_transaction

boolean
Optional

WARNING: This field is deprecated and will be unsupported in a future release.

Allows cardholders to define a PIN as they complete their first PIN-debit transaction.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.allow_gpa_auth

boolean
Optional

A value of true allows transactions to be authorized using GPA funds.

NOTE: For most programs, this field should be set to true.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.allow_mcc_group_authorization_controls

boolean
Optional

The MCC group authorization_controls object allows you to automatically increase authorization holds and to specify authorization expiration times based on merchant type. By default, these settings apply to all cards in your program. You can, however, exempt cards associated with a particular card product by setting this field to false.

NOTE: Partial authorizations are disallowed if this field is set to true.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.allow_network_load

boolean
Optional

Indicates whether card network loads are allowed. The associated card’s state must be ACTIVE or the load will be rejected.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.allow_network_load_card_activation

boolean
Optional

Indicates whether card network loads are allowed. Sets the associated card’s state to ACTIVE if its current state is INACTIVE.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.allow_quasi_cash

boolean
Optional

Indicates whether quasi-cash transactions are allowed. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.always_require_icc

boolean
Optional

A value of true indicates that the cards of this card product type require an Integrated Circuit Card.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.always_require_pin

boolean
Optional

A value of true indicates that the cards of this card product type require a PIN.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.enable_partial_auth_approval

boolean
Optional

Set to true to enable partial authorizations.

When this setting is false and the requested authorization amount exceeds available funds, the transaction is declined. When this setting is true and the requested authorization amount exceeds available funds, the transaction is authorized for the amount of available funds.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.ignore_card_suspended_state

boolean
Optional

Allows transactions to be approved even if the card’s state = SUSPENDED. When this field is set to true, the card behaves as if its state = ACTIVE.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.notification_language

string
Optional

Specifies the language for 3D Secure and digital wallet token notifications sent to cardholders under this card program. By default, notifications are sent in English. You can also send notifications to your cardholders in Czech, French, Italian, German, Polish, Spanish, and Swedish.

To specify the language for OTP notifications at the user level, see Users. Languages set at the user level take precedence over the language set at the card product level.

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

If you leave this field blank, cardholders receive notifications in English.

config.transaction_controls.quasi_cash_exempt_merchant_group_token

string
Optional

The token of the merchant group that you want to exempt from quasi-cash transaction authorization control, allowing your cardholders to conduct quasi-cash transactions. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

You can specify a merchant group token in addition to whatever merchant identifiers you listed in the quasi_cash_exempt_mids field, if any.

Allowable Values:

1–36 chars

A valid merchant group token. For information about merchant groups, see Merchant Groups.

config.transaction_controls.quasi_cash_exempt_mids

string
Optional

A comma-separated list of merchant identifiers that you want to exempt from quasi-cash transaction authorization control, allowing your cardholders to conduct quasi-cash transactions. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

Allowable Values:

255 char max

For example: 12345678901,23456789012,34567890123,45678901234

config.transaction_controls.require_card_not_present_card_security_code

boolean
Optional

A value of true indicates that if card_presence_required is true, the card’s security code is required.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.strong_customer_authentication_limits

object
Optional

Contains information about Strong Customer Authentication (SCA) behavior for contactless point-of-sale (POS) and low-value payment (LVP) e-commerce transactions.

Allowable Values:

A valid strong_customer_authentication_limits object

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_cumulative_amount_limit

decimal
Optional

Specifies the cumulative limit of transactions the cardholder can perform before receiving an SCA challenge.

A value of 0 in this field means that the cumulative amount spent in contactless POS transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transaction_limit

decimal
Optional

Specifies the maximum allowable amount for a single contactless point-of-sale (POS) transaction, above which the cardholder receives a strong customer authentication (SCA) challenge.

A value of 0 in this field means that the amount of any single contactless POS transaction performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transactions_count_limit

integer
Optional

Specifies the number of contactless POS transactions the cardholder can perform before receiving an SCA challenge.

A value of 0 in this field means that the number of contactless POS transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

An integer, such as 5.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transactions_currency

string
Optional

Specifies the currency type for contactless POS transactions.

This field is required if either the sca_contactless_transaction_limit field or the sca_contactless_cumulative_amount_limit field in this object contains a value, even if that value is 0.

Allowable Values:

A valid three-digit ISO 4217 currency type, such as EUR.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_cumulative_amount_limit

decimal
Optional

Specifies the cumulative limit of LVP e-commerce transactions the cardholder can perform before receiving an SCA challenge.

For example, if you set the value of this field to 100.00, your cardholder can perform two transactions for 30.00 and two transactions for 20.00 before receiving an SCA challenge.

If you leave this field blank, the cumulative amount spent in LVP e-commerce transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transaction_limit

decimal
Optional

Specifies the maximum allowable amount for a single low-value payment (LVP) e-commerce transaction, above which the cardholder receives a strong customer authentication (SCA) challenge.

If you leave this field blank, the amount of any single LVP e-commerce transaction performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transactions_count_limit

integer
Optional

Specifies the number of LVP e-commerce transactions the cardholder can perform before receiving an SCA challenge.

If you leave this field blank, the total number of LVP e-commerce transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

An integer, such as 5.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transactions_currency

string
Optional

Specifies the currency type for LVP e-commerce transaction limits.

This field is required if any one of the sca_lvp_transaction_limit, sca_lvp_cumulative_amount_limit, or sca_lvp_transactions_count_limit fields in this object contains a value, even if that value is 0.

Allowable Values:

A valid three-digit ISO 4217 currency type, such as EUR.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_tra_exemption_amount_limit

decimal
Optional

Specifies the maximum allowable amount for a single low-value payment (LVP) e-commerce transaction with transaction risk analysis (TRA) exemption sent by the merchant or acquirer. If the transaction amount exceeds the specified limit, then the transaction is either approved or it receives a strong customer authentication (SCA) challenge based on sca_lvp_transaction_limit and sca_lvp_transactions_currency.

Allowable Values:

Format: 0.00

Default value:
0.00

end_date

date
Optional

The end date of the range over which the card product can be active.

Allowable Values:

Format: yyyy-DD-mm

name

string
Required

The name of the card product. We recommend using a unique string.

Allowable Values:

1–40 chars

start_date

date
Required

The date when the card product becomes active. If the start date has passed and the card is set to active = false, then the card will not be activated.

Allowable Values:

Format: yyyy-DD-mm

token

string
Optional

The unique identifier of the card product.

If you do not include a token, the system will generate one automatically. This token is required in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

active

boolean
Conditionally returned

Indicates whether the card product is active.

Allowable Values:

true, false

Default value:
true

config

object
Conditionally returned

Defines the characteristics of the card product. Configurations are conditionally returned based on program setup.

Allowable Values:

A valid config object

config.card_life_cycle

object
Conditionally returned

Defines characteristics of the lifecycle of cards of this card product type.

Allowable Values:

A valid card_life_cycle object

config.card_life_cycle.activate_upon_issue

boolean
Conditionally returned

A value of true indicates that cards of this card product type are active once they are issued.

Allowable Values:

true, false

Default value:
false

config.card_life_cycle.card_service_code

integer
Conditionally returned

A sequence of three digits that defines various services, differentiates card usage in international or domestic interchange, designates PIN and authorization requirements, and identifies card restrictions. The following values are commonly used:

First digit

  • 1 — International interchange OK

  • 2 — International interchange, use IC (chip) where feasible

  • 5 — National interchange only except under bilateral agreement

  • 6 — National interchange only except under bilateral agreement, use IC (chip) where feasible

  • 7 — No interchange except under bilateral agreement (closed loop)

  • 9 — Test

Second digit

  • 0 — Normal

  • 2 — Contact issuer via online means

  • 4 — Contact issuer via online means except under bilateral agreement

Third digit

  • 0 — No restrictions, PIN required

  • 1 — No restrictions

  • 2 — Goods and services only (no cash)

  • 3 — ATM only, PIN required

  • 4 — Cash only

  • 5 — Goods and services only (no cash), PIN required

  • 6 — No restrictions, use PIN where feasible

  • 7 — Goods and services only (no cash), use PIN where feasible

Allowable Values:

100 - 999

Default value:
101

config.card_life_cycle.expiration_offset

object
Conditionally returned

Specifies the length of time after the date of issue for which cards of this card product type are valid.

Allowable Values:

A valid expiration_offset object

config.card_life_cycle.expiration_offset.min_offset

object
Conditionally returned

Specifies the minimum length of time after the date of issue for which the cards are valid.

Allowable Values:

Valid min_offset object

config.card_life_cycle.expiration_offset.min_offset.unit

string
Conditionally returned

Specifies the minimum offset unit.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default Value
expiration_offset.unit

config.card_life_cycle.expiration_offset.min_offset.value

integer
Conditionally returned

Specifies the minimum offset value.

Allowable Values:

Default Value
expiration_offset.value

config.card_life_cycle.expiration_offset.unit

string
Conditionally returned

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value:
YEARS

config.card_life_cycle.expiration_offset.value

integer
Conditionally returned

Specifies the number of time units (as defined by the unit field in this object) that cards of this card product type are valid. In other words, cards expire value x unit after the date of issue.

This number is rounded as follows:

  • YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and value = 1, the cards expire on the last day of Jan 2022.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and value = 1, the cards expire on the last day of June 2022.

  • DAYS – Rounds up to the last second of the day of expiration.

  • HOURS, MINUTES, SECONDS – No rounding.

Allowable Values:

Any positive integer

Default value:
4

config.card_life_cycle.update_expiration_upon_activation

boolean
Conditionally returned

Normally, the expiration_offset is measured from the date of issue. Set this field to true to measure expiration_offset from the date of activation instead.

Allowable Values:

true, false

Default value:
false

config.clearing_and_settlement

object
Conditionally returned

Specifies the destination for overdraft funds.

Allowable Values:

A valid clearing_and_settlement object

config.clearing_and_settlement.overdraft_destination

string
Conditionally returned

Specifies the destination for overdraft funds.

This field does not apply if JIT Funding is enabled.

Allowable Values:

GPA, MSA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value:
GPA

config.digital_wallet_tokenization

object
Conditionally returned

Controls characteristics related to digital wallets.

Allowable Values:

A valid digital_wallet_tokenization object

config.digital_wallet_tokenization.card_art_id

string
Conditionally returned

Specifies the digital wallet card art identifier for the card product. Digital wallets display the card art after the initial token has been provisioned and activated. Digital wallet card art is updated for all wallets automatically whenever a tokenized card is reissued or replaced.

  • If your card program is Managed by Marqeta, Marqeta populates this field on your behalf.

  • If your card program is Powered by Marqeta, you can obtain the correct card art identifier directly from Visa or Mastercard.

If this field is left blank, your card product inherits the card art assigned to the account BIN range.

Allowable Values:

Valid identifiers are defined by Visa or Mastercard and vary by program:

  • For Visa card products, this identifier is a GUID called profileID.

  • For Mastercard card products, this identifier is a string called ProductConfigID.

config.digital_wallet_tokenization.provisioning_controls

object
Conditionally returned

Controls the provisioning of digital wallets.

Allowable Values:

A valid provisioning_controls object

config.digital_wallet_tokenization.provisioning_controls.in_app_provisioning

object
Conditionally returned

Controls the provisioning of digital wallets by a Marqeta customer’s mobile application.

Allowable Values:

A valid in_app_provisioning object

config.digital_wallet_tokenization.provisioning_controls.manual_entry

object
Conditionally returned

Controls the provisioning of digital wallets by manual entry, in which the cardholder manually enters the card’s PAN, CVV2, and expiration date.

Allowable Values:

A valid manual_entry object

config.digital_wallet_tokenization.provisioning_controls.wallet_provider_card_on_file

object
Conditionally returned

Controls the provisioning of digital wallets where the digital wallet provider already has the card on file.

Allowable Values:

A valid wallet_provider_card_on_file object

config.digital_wallet_tokenization.provisioning_controls.web_push_provisioning

object
Conditionally returned

Specifies the digital wallet card art and program configuration identifiers at the card product level for Web Push Provisioning.

Allowable Values:

A valid web_push_provisioning object

config.fulfillment

object
Conditionally returned

Determines physical characteristics of a card, along with its bulk shipment information.

Allowable Values:

A valid fulfillment object

config.fulfillment.all_zero_card_security_code

boolean
Conditionally returned

If true, an all zero code (000) is allowed as a valid value in an authorization request.

Allowable Values:

true, false

Default value:
false

config.fulfillment.allow_card_creation

boolean
Conditionally returned

Controls the ability to create cards from this card product; true allows and false disallows the creation of cards.

NOTE: The card product’s active field has no effect on card creation or the behavior of this field.

Allowable Values:

true, false

Default value:
true

config.fulfillment.bin_prefix

string
Conditionally returned

The prefix of the bank identification number.

Allowable Values:

A six-digit number for the sandbox environment; a six- to nine-digit number is expected in production environments (see note below).

Default value:
111111

NOTE: In the sandbox environment or when testing against OpenAPI (Swagger), this field must be set to 111111. It is preferable to use eight- or nine-digit BIN prefixes in production environments. Contact your Marqeta representative for the appropriate value to use.

config.fulfillment.bulk_ship

boolean
Conditionally returned

Enables bulk ordering of cards of this card product type using the /bulkissuances endpoint.

Allowable Values:

true, false

Default value:
false

config.fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card product.

Allowable Values:

A valid card_personalization object

config.fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

config.fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

Specifies a text file containing a custom message to print on the card carrier.

Allowable Values:

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

config.fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

config.fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Existing images object

config.fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

config.fulfillment.card_personalization.images.card.name

string
Conditionally returned

Specifies a PNG image to display on the card.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.card.thermal_color

string
Conditionally returned

Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color and must match one of the provider’s predefined colors.

config.fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

config.fulfillment.card_personalization.images.carrier.message_1

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

config.fulfillment.card_personalization.images.carrier.name

string
Conditionally returned

Specifies a PNG image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Valid carrier_return_window object

config.fulfillment.card_personalization.images.carrier_return_window.name

string
Conditionally returned

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

config.fulfillment.card_personalization.images.signature.name

string
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

config.fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

config.fulfillment.card_personalization.text.name_line_1

object
Returned

Specifies the first line of personalized text that appears on the card.

Allowable Values:

name_line_1.value

21 char max; if name_line_1_numeric_postfix is true, 14 char max

Strings longer than the character limit are truncated.

config.fulfillment.card_personalization.text.name_line_1.value

string
Conditionally returned

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Specifies the second line of personalized text that appears on the card.

Allowable Values:

name_line_2.value

config.fulfillment.card_personalization.text.name_line_2.value

string
Conditionally returned

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Specifies the third line of personalized text that appears on the card.

Allowable Values:

name_line_3.value

config.fulfillment.card_personalization.text.name_line_3.value

string
Conditionally returned

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.enable_offline_pin

boolean
Conditionally returned

Enables offline PIN verification for EMV ("chip-and-PIN") card payments.

Allowable Values:

true, false

Default value:
false

config.fulfillment.fulfillment_provider

string
Conditionally returned

Specifies the fulfillment provider.

NOTE: Expedited processing is available for cards that are fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions. You can expedite an order’s processing by using the expedite field of the card or bulkissuance object. Contact your Marqeta representative for information regarding the cost of expedited service.

Allowable Values:

PERFECTPLASTIC, ARROWEYE, IDEMIA, IDEMIA_UK, IDEMIA_FR, IDEMIA_CZ, IDEMIA_APAC, IDEMIA_PL, IDEMIA_AU, IDEMIA_LA, GEMALTO, NITECREST, OBERTHUR, ALLPAY, IDEMIA_FR_SC, GD, NITECREST_UK_SC, NITECREST_PL, TAG, IDEMIA_DE, FIS, CPI, EXCEET_DE, OBERTHUR_SC, IDEMIA_PE

Default value:
PERFECTPLASTIC

config.fulfillment.package_id

string
Conditionally returned

Card fulfillment provider’s package ID.

Allowable Values:

1–50 chars

config.fulfillment.pan_length

string
Conditionally returned

Specifies the length of the primary account number (PAN).

Allowable Values:

Default value: 16

config.fulfillment.payment_instrument

string
Conditionally returned

Specifies the physical form cards of this card product type will take.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

Default value:
PHYSICAL_MSR

config.fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the order.

Allowable Values:

Valid shipping object

config.fulfillment.shipping.care_of_line

string
Conditionally returned

Adds the specified value as a care of (C/O) line to the mailing carrier.

Allowable Values:

255 char max

config.fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.

config.fulfillment.shipping.recipient_address

object
Conditionally returned

Address to which the order will be shipped.

In order to generate cards, a valid shipping address must be provided by one of these:

  • The card or bulk card order’s fulfillment.shipping.recipient_address field

  • The users' address fields

  • The card product’s config.fulfillment.shipping.recipient_address field

The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the address1, city, state, and postal_code or zip fields populated. The country field defaults to USA if unpopulated.

Allowable Values:

Valid recipient_address object

config.fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

config.fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

config.fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

config.fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

config.fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

config.fulfillment.shipping.return_address

object
Conditionally returned

Address to which the order will be returned if shipping fails.

Allowable Values:

Valid return_address object

config.fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

config.fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

config.fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

config.fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

config.fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

config.fulfillment.uppercase_name_lines

boolean
Conditionally returned

A value of true sets the text in the fulfillment.card_personalization.text.name_line_1 and name_line_2 fields to all uppercase letters. A value of false leaves the text in its original state.

Allowable Values:

true, false

Default value:
true

config.jit_funding

object
Conditionally returned

Governs the behavior of JIT Funding.

Allowable Values:

A valid jit_funding object

config.jit_funding.paymentcard_funding_source

object
Conditionally returned

Allows for the enabling and configuration of a payment card funding source.

Allowable Values:

A valid paymentcard_funding_source object

config.jit_funding.paymentcard_funding_source.enabled

boolean
Conditionally returned

Specifies whether JIT Funding is enabled or disabled for the payment card funding source. A value of true indicates that the payment card funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.paymentcard_funding_source.refunds_destination

string
Conditionally returned

Specifies the return destination for refunds in the case of a transaction reversal.

Allowable Values:

GATEWAY, GPA, WATERFALL

config.jit_funding.program_funding_source

object
Conditionally returned

Allows for the enabling and configuration of a program funding source.

Allowable Values:

A valid program_funding_source object

config.jit_funding.program_funding_source.enabled

boolean
Conditionally returned

Specifies whether JIT Funding is enabled or disabled for the program funding source. A value of true indicates that the program funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.program_funding_source.funding_source_token

string
Conditionally returned

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

config.jit_funding.program_funding_source.refunds_destination

string
Conditionally returned

Specifies the return destination for refunds in the case of a transaction reversal. PROGRAM_FUNDING_SOURCE returns funds to the program funding source. GPA returns the funds to the user’s GPA.

Allowable Values:

PROGRAM_FUNDING_SOURCE, GPA, WATERFALL

config.jit_funding.programgateway_funding_source

object
Conditionally returned

Allows for the enabling and configuration of a program gateway funding source.

Allowable Values:

A valid programgateway_funding_source object

config.jit_funding.programgateway_funding_source.always_fund

boolean
Conditionally returned

If set to true, this card product is always funded from this program gateway funding source.

Allowable Values:

true, false

Default value:
false

config.jit_funding.programgateway_funding_source.enabled

boolean
Conditionally returned

Specifies whether JIT Funding is enabled or disabled for the program gateway funding source. A value of true indicates that the program gateway funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.programgateway_funding_source.funding_source_token

string
Conditionally returned

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

config.jit_funding.programgateway_funding_source.refunds_destination

string
Conditionally returned

Specifies the return destination for refunds in the case of a transaction reversal. In most cases, you should set the value to GATEWAY, which returns funds to the program gateway funding source. Setting to GPA returns the funds to the user’s GPA, which creates a positive account balance and introduces the potential of a transaction being authorized without a JIT Funding request being sent to the gateway.

Allowable Values:

GATEWAY, GPA, WATERFALL

config.poi

object
Conditionally returned

Governs the point of interaction.

Allowable Values:

A valid poi object

config.poi.atm

boolean
Conditionally returned

A value of true enables cards to be used for withdrawing cash at an ATM and for receiving cash back at a point of sale (POS).

Allowable Values:

true, false

Default value:
false

config.poi.ecommerce

boolean
Conditionally returned

A value of true enables cards to be used for online purchases.

Allowable Values:

true, false

Default value:
false

config.poi.other

object
Conditionally returned

Allows for configuration of points of interaction other than ecommerce or ATMs, such as points of sale (POS).

Allowable Values:

A valid other object

config.poi.other.allow

boolean
Conditionally returned

If set to true, card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes points of sale (POS).

Allowable Values:

true, false

Default value:
true

config.poi.other.card_presence_required

boolean
Conditionally returned

If set to true, cards of this card product type are required to be present during the transaction, such as in IVR scenarios.

Allowable Values:

true, false

Default value:
false

config.poi.other.cardholder_presence_required

boolean
Conditionally returned

A value of true indicates that the cardholder is required to be present, such as in a restaurant where the card is present but the cardholder is not present when the card is swiped.

Allowable Values:

true, false

Default value:
false

config.selective_auth

object
Conditionally returned

Contains information about authorization decisions.

Allowable Values:

A valid selective_auth object

config.selective_auth.dmd_location_sensitivity

integer
Conditionally returned

Determines what type of merchant information is required for a match (authorization). Not relevant if enable_regex_search_chain = false.

  • 0 – Requires exact match on card acceptor name and postal code to existing entry in Marqeta Merchant database (most restrictive).

  • 1 – Partial match on card acceptor name (least restrictive).

  • 2 – Partial match on card acceptor name; exact match on card acceptor city.

  • 3 – Partial match on card acceptor name; exact match on card acceptor postal code.

  • 4 – Partial match on card acceptor name; exact match on street address 1 and postal code.

Allowable Values:

0, 1, 2, 3, 4

Default value:
0

config.selective_auth.enable_regex_search_chain

boolean
Conditionally returned

Use true to perform regular expression checking on the description received in the authorization.

Allowable Values:

true , false

Default value:
false

config.selective_auth.sa_mode

integer
Conditionally returned

  • 0 — Inactive

  • 1 — Active (attempts to authorize a merchant that does not have a recognized MID by matching other pieces of information)

  • 2 — Logging and notification (checks the transaction and logs results, but does not authorize)

Selective authorization applies to transactions that are limited to specific merchants. Matching requirements for authorization are set by the dmd_location_sensitivity field.

Allowable Values:

0, 1, 2

Default value:
0

config.special

object
Conditionally returned

Contains information about merchant onboarding.

Allowable Values:

A valid special object

config.special.merchant_on_boarding

boolean
Conditionally returned

A value of true indicates cards of this card product type can be used for merchant onboarding.

Allowable Values:

true, false

Default value:
false

config.transaction_controls

object
Conditionally returned

Controls transactional characteristics of card usage.

Allowable Values:

A valid transaction_controls object

config.transaction_controls.accepted_countries_token

string
Conditionally returned

Set to accept_us_only to allow transactions only within the US.

Set to decline_ofac_countries to allow international transactions except with countries that the Financial Action Task Force (FATF) and Office of Foreign Assets Control (OFAC) have identified as high risk.

Users with the Admin role can create and update additional lists of accepted countries for transactions at the /acceptedcountries endpoint. See Accepted Countries.

Allowable Values:

accept_us_only, decline_ofac_countries, additional Admin-defined tokens

Default value:
accept_us_only

config.transaction_controls.address_verification

object
Conditionally returned

Contains configuration options for AVS.

Allowable Values:

A valid address_verification object

config.transaction_controls.address_verification.auth_messages

object
Conditionally returned

Contains verification options for authorization messages.

These messages pertain to actual purchases and are for amounts greater than $0.

Allowable Values:

A valid auth_messages object

config.transaction_controls.address_verification.av_messages

object
Conditionally returned

Contains verification options for account verification messages.

These are $0 messages typically used to store cards on file at a merchant.

Allowable Values:

A valid av_messages object

config.transaction_controls.allow_chip_fallback

boolean
Conditionally returned

Indicates whether to allow transactions where an EMV chip-enabled card was processed using the magstripe as fallback.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.allow_first_pin_set_via_financial_transaction

boolean
Conditionally returned

WARNING: This field is deprecated and will be unsupported in a future release.

Allows cardholders to define a PIN as they complete their first PIN-debit transaction.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.allow_gpa_auth

boolean
Conditionally returned

A value of true allows transactions to be authorized using GPA funds.

NOTE: For most programs, this field should be set to true.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.allow_mcc_group_authorization_controls

boolean
Conditionally returned

The MCC group authorization_controls object allows you to automatically increase authorization holds and to specify authorization expiration times based on merchant type. By default, these settings apply to all cards in your program. You can, however, exempt cards associated with a particular card product by setting this field to false.

NOTE: Partial authorizations are disallowed if this field is set to true.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.allow_network_load

boolean
Conditionally returned

Indicates whether card network loads are allowed. The associated card’s state must be ACTIVE or the load will be rejected.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.allow_network_load_card_activation

boolean
Conditionally returned

Indicates whether card network loads are allowed. Sets the associated card’s state to ACTIVE if its current state is INACTIVE.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.allow_quasi_cash

boolean
Conditionally returned

Indicates whether quasi-cash transactions are allowed. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.always_require_icc

boolean
Conditionally returned

A value of true indicates that the cards of this card product type require an Integrated Circuit Card.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.always_require_pin

boolean
Conditionally returned

A value of true indicates that the cards of this card product type require a PIN.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.enable_partial_auth_approval

boolean
Conditionally returned

Set to true to enable partial authorizations.

When this setting is false and the requested authorization amount exceeds available funds, the transaction is declined. When this setting is true and the requested authorization amount exceeds available funds, the transaction is authorized for the amount of available funds.

Allowable Values:

true, false

Default value:
true

config.transaction_controls.ignore_card_suspended_state

boolean
Conditionally returned

Allows transactions to be approved even if the card’s state = SUSPENDED. When this field is set to true, the card behaves as if its state = ACTIVE.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.notification_language

string
Conditionally returned

Specifies the language for 3D Secure and digital wallet token notifications sent to cardholders under this card program. By default, notifications are sent in English. You can also send notifications to your cardholders in Czech, French, Italian, German, Polish, Spanish, and Swedish.

To specify the language for OTP notifications at the user level, see Users. Languages set at the user level take precedence over the language set at the card product level.

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

If you leave this field blank, cardholders receive notifications in English.

config.transaction_controls.quasi_cash_exempt_merchant_group_token

string
Conditionally returned

The token of the merchant group that you want to exempt from quasi-cash transaction authorization control, allowing your cardholders to conduct quasi-cash transactions. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

You can specify a merchant group token in addition to whatever merchant identifiers you listed in the quasi_cash_exempt_mids field, if any.

Allowable Values:

1–36 chars

A valid merchant group token. For information about merchant groups, see Merchant Groups.

config.transaction_controls.quasi_cash_exempt_mids

string
Conditionally returned

A comma-separated list of merchant identifiers that you want to exempt from quasi-cash transaction authorization control, allowing your cardholders to conduct quasi-cash transactions. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

Allowable Values:

255 char max

For example: 12345678901,23456789012,34567890123,45678901234

config.transaction_controls.require_card_not_present_card_security_code

boolean
Conditionally returned

A value of true indicates that if card_presence_required is true, the card’s security code is required.

Allowable Values:

true, false

Default value:
false

config.transaction_controls.strong_customer_authentication_limits

object
Conditionally returned

Contains information about Strong Customer Authentication (SCA) behavior for contactless point-of-sale (POS) and low-value payment (LVP) e-commerce transactions.

Allowable Values:

A valid strong_customer_authentication_limits object

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_cumulative_amount_limit

decimal
Conditionally returned

Specifies the cumulative limit of transactions the cardholder can perform before receiving an SCA challenge.

A value of 0 in this field means that the cumulative amount spent in contactless POS transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transaction_limit

decimal
Conditionally returned

Specifies the maximum allowable amount for a single contactless point-of-sale (POS) transaction, above which the cardholder receives a strong customer authentication (SCA) challenge.

A value of 0 in this field means that the amount of any single contactless POS transaction performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transactions_count_limit

integer
Conditionally returned

Specifies the number of contactless POS transactions the cardholder can perform before receiving an SCA challenge.

A value of 0 in this field means that the number of contactless POS transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

An integer, such as 5.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transactions_currency

string
Conditionally returned

Specifies the currency type for contactless POS transactions.

This field is required if either the sca_contactless_transaction_limit field or the sca_contactless_cumulative_amount_limit field in this object contains a value, even if that value is 0.

Allowable Values:

A valid three-digit ISO 4217 currency type, such as EUR.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_cumulative_amount_limit

decimal
Conditionally returned

Specifies the cumulative limit of LVP e-commerce transactions the cardholder can perform before receiving an SCA challenge.

For example, if you set the value of this field to 100.00, your cardholder can perform two transactions for 30.00 and two transactions for 20.00 before receiving an SCA challenge.

If you leave this field blank, the cumulative amount spent in LVP e-commerce transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transaction_limit

decimal
Conditionally returned

Specifies the maximum allowable amount for a single low-value payment (LVP) e-commerce transaction, above which the cardholder receives a strong customer authentication (SCA) challenge.

If you leave this field blank, the amount of any single LVP e-commerce transaction performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transactions_count_limit

integer
Conditionally returned

Specifies the number of LVP e-commerce transactions the cardholder can perform before receiving an SCA challenge.

If you leave this field blank, the total number of LVP e-commerce transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

An integer, such as 5.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transactions_currency

string
Conditionally returned

Specifies the currency type for LVP e-commerce transaction limits.

This field is required if any one of the sca_lvp_transaction_limit, sca_lvp_cumulative_amount_limit, or sca_lvp_transactions_count_limit fields in this object contains a value, even if that value is 0.

Allowable Values:

A valid three-digit ISO 4217 currency type, such as EUR.

There is no default value for this field.

config.transaction_controls.strong_customer_authentication_limits.sca_tra_exemption_amount_limit

decimal
Conditionally returned

Specifies the maximum allowable amount for a single low-value payment (LVP) e-commerce transaction with transaction risk analysis (TRA) exemption sent by the merchant or acquirer. If the transaction amount exceeds the specified limit, then the transaction is either approved or it receives a strong customer authentication (SCA) challenge based on sca_lvp_transaction_limit and sca_lvp_transactions_currency.

Allowable Values:

Format: 0.00

Default value:
0.00

created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-DD-mmT00:00:00Z

end_date

date
Conditionally returned

The end date of the range over which the card product can be active.

Allowable Values:

Format: yyyy-DD-mm

last_modified_time

datetime
Returned

The date and time when the resource was last updated, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-DD-mmT00:00:00Z

name

string
Returned

The name of the card product.

Allowable Values:

1–40 chars

start_date

date
Returned

The date when the card product becomes active.

Allowable Values:

Format: yyyy-DD-mm

token

string
Conditionally returned

The unique identifier of the card product.

Allowable Values:

1–36 chars

If you did not include a token in your request, the system returns an automatically generated token in the response.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List card products

Action: GET
Endpoint: /cardproducts

Use this endpoint to list existing card products.

This endpoint supports pagination.

URL query parameters
Fields Description

count

integer
Optional

The number of resources to retrieve. Count can be between 1 - 10 items.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of objects in a returned resource.

Allowable Values:

A valid data array

data[].active

boolean
Conditionally returned

Indicates whether the card product is active.

Allowable Values:

true, false

Default value:
true

data[].config

object
Conditionally returned

Defines the characteristics of the card product. Configurations are conditionally returned based on program setup.

Allowable Values:

A valid config object

data[].config.card_life_cycle

object
Conditionally returned

Defines characteristics of the lifecycle of cards of this card product type.

Allowable Values:

A valid card_life_cycle object

data[].config.card_life_cycle.activate_upon_issue

boolean
Conditionally returned

A value of true indicates that cards of this card product type are active once they are issued.

Allowable Values:

true, false

Default value:
false

data[].config.card_life_cycle.card_service_code

integer
Conditionally returned

A sequence of three digits that defines various services, differentiates card usage in international or domestic interchange, designates PIN and authorization requirements, and identifies card restrictions. The following values are commonly used:

First digit

  • 1 — International interchange OK

  • 2 — International interchange, use IC (chip) where feasible

  • 5 — National interchange only except under bilateral agreement

  • 6 — National interchange only except under bilateral agreement, use IC (chip) where feasible

  • 7 — No interchange except under bilateral agreement (closed loop)

  • 9 — Test

Second digit

  • 0 — Normal

  • 2 — Contact issuer via online means

  • 4 — Contact issuer via online means except under bilateral agreement

Third digit

  • 0 — No restrictions, PIN required

  • 1 — No restrictions

  • 2 — Goods and services only (no cash)

  • 3 — ATM only, PIN required

  • 4 — Cash only

  • 5 — Goods and services only (no cash), PIN required

  • 6 — No restrictions, use PIN where feasible

  • 7 — Goods and services only (no cash), use PIN where feasible

Allowable Values:

100 - 999

Default value:
101

data[].config.card_life_cycle.expiration_offset

object
Conditionally returned

Specifies the length of time after the date of issue for which cards of this card product type are valid.

Allowable Values:

A valid expiration_offset object

data[].config.card_life_cycle.expiration_offset.min_offset

object
Conditionally returned

Specifies the minimum length of time after the date of issue for which the cards are valid.

Allowable Values:

Valid min_offset object

data[].config.card_life_cycle.expiration_offset.min_offset.unit

string
Conditionally returned

Specifies the minimum offset unit.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default Value
expiration_offset.unit

data[].config.card_life_cycle.expiration_offset.min_offset.value

integer
Conditionally returned

Specifies the minimum offset value.

Allowable Values:

Default Value
expiration_offset.value

data[].config.card_life_cycle.expiration_offset.unit

string
Conditionally returned

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value:
YEARS

data[].config.card_life_cycle.expiration_offset.value

integer
Conditionally returned

Specifies the number of time units (as defined by the unit field in this object) that cards of this card product type are valid. In other words, cards expire value x unit after the date of issue.

This number is rounded as follows:

  • YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and value = 1, the cards expire on the last day of Jan 2022.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and value = 1, the cards expire on the last day of June 2022.

  • DAYS – Rounds up to the last second of the day of expiration.

  • HOURS, MINUTES, SECONDS – No rounding.

Allowable Values:

Any positive integer

Default value:
4

data[].config.card_life_cycle.update_expiration_upon_activation

boolean
Conditionally returned

Normally, the expiration_offset is measured from the date of issue. Set this field to true to measure expiration_offset from the date of activation instead.

Allowable Values:

true, false

Default value:
false

data[].config.clearing_and_settlement

object
Conditionally returned

Specifies the destination for overdraft funds.

Allowable Values:

A valid clearing_and_settlement object

data[].config.clearing_and_settlement.overdraft_destination

string
Conditionally returned

Specifies the destination for overdraft funds.

This field does not apply if JIT Funding is enabled.

Allowable Values:

GPA, MSA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value:
GPA

data[].config.digital_wallet_tokenization

object
Conditionally returned

Controls characteristics related to digital wallets.

Allowable Values:

A valid digital_wallet_tokenization object

data[].config.digital_wallet_tokenization.card_art_id

string
Conditionally returned

Specifies the digital wallet card art identifier for the card product. Digital wallets display the card art after the initial token has been provisioned and activated. Digital wallet card art is updated for all wallets automatically whenever a tokenized card is reissued or replaced.

  • If your card program is Managed by Marqeta, Marqeta populates this field on your behalf.

  • If your card program is Powered by Marqeta, you can obtain the correct card art identifier directly from Visa or Mastercard.

If this field is left blank, your card product inherits the card art assigned to the account BIN range.

Allowable Values:

Valid identifiers are defined by Visa or Mastercard and vary by program:

  • For Visa card products, this identifier is a GUID called profileID.

  • For Mastercard card products, this identifier is a string called ProductConfigID.

data[].config.digital_wallet_tokenization.provisioning_controls

object
Conditionally returned

Controls the provisioning of digital wallets.

Allowable Values:

A valid provisioning_controls object

data[].config.digital_wallet_tokenization.provisioning_controls.in_app_provisioning

object
Conditionally returned

Controls the provisioning of digital wallets by a Marqeta customer’s mobile application.

Allowable Values:

A valid in_app_provisioning object

data[].config.digital_wallet_tokenization.provisioning_controls.manual_entry

object
Conditionally returned

Controls the provisioning of digital wallets by manual entry, in which the cardholder manually enters the card’s PAN, CVV2, and expiration date.

Allowable Values:

A valid manual_entry object

data[].config.digital_wallet_tokenization.provisioning_controls.wallet_provider_card_on_file

object
Conditionally returned

Controls the provisioning of digital wallets where the digital wallet provider already has the card on file.

Allowable Values:

A valid wallet_provider_card_on_file object

data[].config.digital_wallet_tokenization.provisioning_controls.web_push_provisioning

object
Conditionally returned

Specifies the digital wallet card art and program configuration identifiers at the card product level for Web Push Provisioning.

Allowable Values:

A valid web_push_provisioning object

data[].config.fulfillment

object
Conditionally returned

Determines physical characteristics of a card, along with its bulk shipment information.

Allowable Values:

A valid fulfillment object

data[].config.fulfillment.all_zero_card_security_code

boolean
Conditionally returned

If true, an all zero code (000) is allowed as a valid value in an authorization request.

Allowable Values:

true, false

Default value:
false

data[].config.fulfillment.allow_card_creation

boolean
Conditionally returned

Controls the ability to create cards from this card product; true allows and false disallows the creation of cards.

NOTE: The card product’s active field has no effect on card creation or the behavior of this field.

Allowable Values:

true, false

Default value:
true

data[].config.fulfillment.bin_prefix

string
Conditionally returned

The prefix of the bank identification number.

Allowable Values:

A six-digit number for the sandbox environment; a six- to nine-digit number is expected in production environments (see note below).

Default value:
111111

NOTE: In the sandbox environment or when testing against OpenAPI (Swagger), this field must be set to 111111. It is preferable to use eight- or nine-digit BIN prefixes in production environments. Contact your Marqeta representative for the appropriate value to use.

data[].config.fulfillment.bulk_ship

boolean
Conditionally returned

Enables bulk ordering of cards of this card product type using the /bulkissuances endpoint.

Allowable Values:

true, false

Default value:
false

data[].config.fulfillment.card_personalization

object
Returned

Allows personalized attributes to be added to the card product.

Allowable Values:

A valid card_personalization object

data[].config.fulfillment.card_personalization.carrier

object
Conditionally returned

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

data[].config.fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Specifies an image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

Specifies a text file containing a custom message to print on the card carrier.

Allowable Values:

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

data[].config.fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

data[].config.fulfillment.card_personalization.images

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Existing images object

data[].config.fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

data[].config.fulfillment.card_personalization.images.card.name

string
Conditionally returned

Specifies a PNG image to display on the card.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.images.card.thermal_color

string
Conditionally returned

Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color and must match one of the provider’s predefined colors.

data[].config.fulfillment.card_personalization.images.carrier

object
Conditionally returned

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

data[].config.fulfillment.card_personalization.images.carrier.message_1

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

data[].config.fulfillment.card_personalization.images.carrier.name

string
Conditionally returned

Specifies a PNG image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.images.carrier_return_window

object
Conditionally returned

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Valid carrier_return_window object

data[].config.fulfillment.card_personalization.images.carrier_return_window.name

string
Conditionally returned

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.images.signature

object
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

data[].config.fulfillment.card_personalization.images.signature.name

string
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].config.fulfillment.card_personalization.perso_type

string
Conditionally returned

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

data[].config.fulfillment.card_personalization.text

object
Returned

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

data[].config.fulfillment.card_personalization.text.name_line_1

object
Returned

Specifies the first line of personalized text that appears on the card.

Allowable Values:

name_line_1.value

21 char max; if name_line_1_numeric_postfix is true, 14 char max

Strings longer than the character limit are truncated.

data[].config.fulfillment.card_personalization.text.name_line_1.value

string
Conditionally returned

A line of personalized text printed on the card.

Allowable Values:

21 char max

data[].config.fulfillment.card_personalization.text.name_line_2

object
Conditionally returned

Specifies the second line of personalized text that appears on the card.

Allowable Values:

name_line_2.value

data[].config.fulfillment.card_personalization.text.name_line_2.value

string
Conditionally returned

A line of personalized text printed on the card.

Allowable Values:

21 char max

data[].config.fulfillment.card_personalization.text.name_line_3

object
Conditionally returned

Specifies the third line of personalized text that appears on the card.

Allowable Values:

name_line_3.value

data[].config.fulfillment.card_personalization.text.name_line_3.value

string
Conditionally returned

A line of personalized text printed on the card.

Allowable Values:

21 char max

data[].config.fulfillment.enable_offline_pin

boolean
Conditionally returned

Enables offline PIN verification for EMV ("chip-and-PIN") card payments.

Allowable Values:

true, false

Default value:
false

data[].config.fulfillment.fulfillment_provider

string
Conditionally returned

Specifies the fulfillment provider.

NOTE: Expedited processing is available for cards that are fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions. You can expedite an order’s processing by using the expedite field of the card or bulkissuance object. Contact your Marqeta representative for information regarding the cost of expedited service.

Allowable Values:

PERFECTPLASTIC, ARROWEYE, IDEMIA, IDEMIA_UK, IDEMIA_FR, IDEMIA_CZ, IDEMIA_APAC, IDEMIA_PL, IDEMIA_AU, IDEMIA_LA, GEMALTO, NITECREST, OBERTHUR, ALLPAY, IDEMIA_FR_SC, GD, NITECREST_UK_SC, NITECREST_PL, TAG, IDEMIA_DE, FIS, CPI, EXCEET_DE, OBERTHUR_SC, IDEMIA_PE

Default value:
PERFECTPLASTIC

data[].config.fulfillment.package_id

string
Conditionally returned

Card fulfillment provider’s package ID.

Allowable Values:

1–50 chars

data[].config.fulfillment.pan_length

string
Conditionally returned

Specifies the length of the primary account number (PAN).

Allowable Values:

Default value: 16

data[].config.fulfillment.payment_instrument

string
Conditionally returned

Specifies the physical form cards of this card product type will take.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

Default value:
PHYSICAL_MSR

data[].config.fulfillment.shipping

object
Conditionally returned

Specifies shipping details for the order.

Allowable Values:

Valid shipping object

data[].config.fulfillment.shipping.care_of_line

string
Conditionally returned

Adds the specified value as a care of (C/O) line to the mailing carrier.

Allowable Values:

255 char max

data[].config.fulfillment.shipping.method

string
Conditionally returned

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.

data[].config.fulfillment.shipping.recipient_address

object
Conditionally returned

Address to which the order will be shipped.

In order to generate cards, a valid shipping address must be provided by one of these:

  • The card or bulk card order’s fulfillment.shipping.recipient_address field

  • The users' address fields

  • The card product’s config.fulfillment.shipping.recipient_address field

The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the address1, city, state, and postal_code or zip fields populated. The country field defaults to USA if unpopulated.

Allowable Values:

Valid recipient_address object

data[].config.fulfillment.shipping.recipient_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].config.fulfillment.shipping.recipient_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].config.fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

data[].config.fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.recipient_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].config.fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].config.fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].config.fulfillment.shipping.recipient_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].config.fulfillment.shipping.return_address

object
Conditionally returned

Address to which the order will be returned if shipping fails.

Allowable Values:

Valid return_address object

data[].config.fulfillment.shipping.return_address.address1

string
Conditionally returned

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].config.fulfillment.shipping.return_address.address2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

data[].config.fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

data[].config.fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.return_address.middle_name

string
Conditionally returned

Middle name.

Allowable Values:

40 char max

data[].config.fulfillment.shipping.return_address.phone

string
Conditionally returned

Telephone number.

Allowable Values:

20 char max

data[].config.fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].config.fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

32 char max

data[].config.fulfillment.shipping.return_address.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].config.fulfillment.uppercase_name_lines

boolean
Conditionally returned

A value of true sets the text in the fulfillment.card_personalization.text.name_line_1 and name_line_2 fields to all uppercase letters. A value of false leaves the text in its original state.

Allowable Values:

true, false

Default value:
true

data[].config.jit_funding

object
Conditionally returned

Governs the behavior of JIT Funding.

Allowable Values:

A valid jit_funding object

data[].config.jit_funding.paymentcard_funding_source

object
Conditionally returned

Allows for the enabling and configuration of a payment card funding source.

Allowable Values:

A valid paymentcard_funding_source object

data[].config.jit_funding.paymentcard_funding_source.enabled

boolean
Conditionally returned

Specifies whether JIT Funding is enabled or disabled for the payment card funding source. A value of true indicates that the payment card funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

data[].config.jit_funding.paymentcard_funding_source.refunds_destination

string
Conditionally returned

Specifies the return destination for refunds in the case of a transaction reversal.

Allowable Values:

GATEWAY, GPA, WATERFALL

data[].config.jit_funding.program_funding_source

object
Conditionally returned

Allows for the enabling and configuration of a program funding source.

Allowable Values:

A valid program_funding_source object

data[].config.jit_funding.program_funding_source.enabled

boolean
Conditionally returned

Specifies whether JIT Funding is enabled or disabled for the program funding source. A value of true indicates that the program funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

data[].config.jit_funding.program_funding_source.funding_source_token

string
Conditionally returned

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

data[].config.jit_funding.program_funding_source.refunds_destination

string
Conditionally returned

Specifies the return destination for refunds in the case of a transaction reversal. PROGRAM_FUNDING_SOURCE returns funds to the program funding source. GPA returns the funds to the user’s GPA.

Allowable Values:

PROGRAM_FUNDING_SOURCE, GPA, WATERFALL

data[].config.jit_funding.programgateway_funding_source

object
Conditionally returned

Allows for the enabling and configuration of a program gateway funding source.

Allowable Values:

A valid programgateway_funding_source object

data[].config.jit_funding.programgateway_funding_source.always_fund

boolean
Conditionally returned

If set to true, this card product is always funded from this program gateway funding source.

Allowable Values:

true, false

Default value:
false

data[].config.jit_funding.programgateway_funding_source.enabled

boolean
Conditionally returned

Specifies whether JIT Funding is enabled or disabled for the program gateway funding source. A value of true indicates that the program gateway funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

data[].config.jit_funding.programgateway_funding_source.funding_source_token

string
Conditionally returned

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

data[].config.jit_funding.programgateway_funding_source.refunds_destination

string
Conditionally returned

Specifies the return destination for refunds in the case of a transaction reversal. In most cases, you should set the value to GATEWAY, which returns funds to the program gateway funding source. Setting to GPA returns the funds to the user’s GPA, which creates a positive account balance and introduces the potential of a transaction being authorized without a JIT Funding request being sent to the gateway.

Allowable Values:

GATEWAY, GPA, WATERFALL

data[].config.poi

object
Conditionally returned

Governs the point of interaction.

Allowable Values:

A valid poi object

data[].config.poi.atm

boolean
Conditionally returned

A value of true enables cards to be used for withdrawing cash at an ATM and for receiving cash back at a point of sale (POS).

Allowable Values:

true, false

Default value:
false

data[].config.poi.ecommerce

boolean
Conditionally returned

A value of true enables cards to be used for online purchases.

Allowable Values:

true, false

Default value:
false

data[].config.poi.other

object
Conditionally returned

Allows for configuration of points of interaction other than ecommerce or ATMs, such as points of sale (POS).

Allowable Values:

A valid other object

data[].config.poi.other.allow

boolean
Conditionally returned

If set to true, card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes points of sale (POS).

Allowable Values:

true, false

Default value:
true

data[].config.poi.other.card_presence_required

boolean
Conditionally returned

If set to true, cards of this card product type are required to be present during the transaction, such as in IVR scenarios.

Allowable Values:

true, false

Default value:
false

data[].config.poi.other.cardholder_presence_required

boolean
Conditionally returned

A value of true indicates that the cardholder is required to be present, such as in a restaurant where the card is present but the cardholder is not present when the card is swiped.

Allowable Values:

true, false

Default value:
false

data[].config.selective_auth

object
Conditionally returned

Contains information about authorization decisions.

Allowable Values:

A valid selective_auth object

data[].config.selective_auth.dmd_location_sensitivity

integer
Conditionally returned

Determines what type of merchant information is required for a match (authorization). Not relevant if enable_regex_search_chain = false.

  • 0 – Requires exact match on card acceptor name and postal code to existing entry in Marqeta Merchant database (most restrictive).

  • 1 – Partial match on card acceptor name (least restrictive).

  • 2 – Partial match on card acceptor name; exact match on card acceptor city.

  • 3 – Partial match on card acceptor name; exact match on card acceptor postal code.

  • 4 – Partial match on card acceptor name; exact match on street address 1 and postal code.

Allowable Values:

0, 1, 2, 3, 4

Default value:
0

data[].config.selective_auth.enable_regex_search_chain

boolean
Conditionally returned

Use true to perform regular expression checking on the description received in the authorization.

Allowable Values:

true , false

Default value:
false

data[].config.selective_auth.sa_mode

integer
Conditionally returned

  • 0 — Inactive

  • 1 — Active (attempts to authorize a merchant that does not have a recognized MID by matching other pieces of information)

  • 2 — Logging and notification (checks the transaction and logs results, but does not authorize)

Selective authorization applies to transactions that are limited to specific merchants. Matching requirements for authorization are set by the dmd_location_sensitivity field.

Allowable Values:

0, 1, 2

Default value:
0

data[].config.special

object
Conditionally returned

Contains information about merchant onboarding.

Allowable Values:

A valid special object

data[].config.special.merchant_on_boarding

boolean
Conditionally returned

A value of true indicates cards of this card product type can be used for merchant onboarding.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls

object
Conditionally returned

Controls transactional characteristics of card usage.

Allowable Values:

A valid transaction_controls object

data[].config.transaction_controls.accepted_countries_token

string
Conditionally returned

Set to accept_us_only to allow transactions only within the US.

Set to decline_ofac_countries to allow international transactions except with countries that the Financial Action Task Force (FATF) and Office of Foreign Assets Control (OFAC) have identified as high risk.

Users with the Admin role can create and update additional lists of accepted countries for transactions at the /acceptedcountries endpoint. See Accepted Countries.

Allowable Values:

accept_us_only, decline_ofac_countries, additional Admin-defined tokens

Default value:
accept_us_only

data[].config.transaction_controls.address_verification

object
Conditionally returned

Contains configuration options for AVS.

Allowable Values:

A valid address_verification object

data[].config.transaction_controls.address_verification.auth_messages

object
Conditionally returned

Contains verification options for authorization messages.

These messages pertain to actual purchases and are for amounts greater than $0.

Allowable Values:

A valid auth_messages object

data[].config.transaction_controls.address_verification.av_messages

object
Conditionally returned

Contains verification options for account verification messages.

These are $0 messages typically used to store cards on file at a merchant.

Allowable Values:

A valid av_messages object

data[].config.transaction_controls.allow_chip_fallback

boolean
Conditionally returned

Indicates whether to allow transactions where an EMV chip-enabled card was processed using the magstripe as fallback.

Allowable Values:

true, false

Default value:
true

data[].config.transaction_controls.allow_first_pin_set_via_financial_transaction

boolean
Conditionally returned

WARNING: This field is deprecated and will be unsupported in a future release.

Allows cardholders to define a PIN as they complete their first PIN-debit transaction.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.allow_gpa_auth

boolean
Conditionally returned

A value of true allows transactions to be authorized using GPA funds.

NOTE: For most programs, this field should be set to true.

Allowable Values:

true, false

Default value:
true

data[].config.transaction_controls.allow_mcc_group_authorization_controls

boolean
Conditionally returned

The MCC group authorization_controls object allows you to automatically increase authorization holds and to specify authorization expiration times based on merchant type. By default, these settings apply to all cards in your program. You can, however, exempt cards associated with a particular card product by setting this field to false.

NOTE: Partial authorizations are disallowed if this field is set to true.

Allowable Values:

true, false

Default value:
true

data[].config.transaction_controls.allow_network_load

boolean
Conditionally returned

Indicates whether card network loads are allowed. The associated card’s state must be ACTIVE or the load will be rejected.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.allow_network_load_card_activation

boolean
Conditionally returned

Indicates whether card network loads are allowed. Sets the associated card’s state to ACTIVE if its current state is INACTIVE.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.allow_quasi_cash

boolean
Conditionally returned

Indicates whether quasi-cash transactions are allowed. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.always_require_icc

boolean
Conditionally returned

A value of true indicates that the cards of this card product type require an Integrated Circuit Card.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.always_require_pin

boolean
Conditionally returned

A value of true indicates that the cards of this card product type require a PIN.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.enable_partial_auth_approval

boolean
Conditionally returned

Set to true to enable partial authorizations.

When this setting is false and the requested authorization amount exceeds available funds, the transaction is declined. When this setting is true and the requested authorization amount exceeds available funds, the transaction is authorized for the amount of available funds.

Allowable Values:

true, false

Default value:
true

data[].config.transaction_controls.ignore_card_suspended_state

boolean
Conditionally returned

Allows transactions to be approved even if the card’s state = SUSPENDED. When this field is set to true, the card behaves as if its state = ACTIVE.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.notification_language

string
Conditionally returned

Specifies the language for 3D Secure and digital wallet token notifications sent to cardholders under this card program. By default, notifications are sent in English. You can also send notifications to your cardholders in Czech, French, Italian, German, Polish, Spanish, and Swedish.

To specify the language for OTP notifications at the user level, see Users. Languages set at the user level take precedence over the language set at the card product level.

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

If you leave this field blank, cardholders receive notifications in English.

data[].config.transaction_controls.quasi_cash_exempt_merchant_group_token

string
Conditionally returned

The token of the merchant group that you want to exempt from quasi-cash transaction authorization control, allowing your cardholders to conduct quasi-cash transactions. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

You can specify a merchant group token in addition to whatever merchant identifiers you listed in the quasi_cash_exempt_mids field, if any.

Allowable Values:

1–36 chars

A valid merchant group token. For information about merchant groups, see Merchant Groups.

data[].config.transaction_controls.quasi_cash_exempt_mids

string
Conditionally returned

A comma-separated list of merchant identifiers that you want to exempt from quasi-cash transaction authorization control, allowing your cardholders to conduct quasi-cash transactions. In a quasi-cash transaction, the cardholder purchases an item that can be directly converted to cash, such as traveler’s checks, money orders, casino chips, or lottery tickets.

Allowable Values:

255 char max

For example: 12345678901,23456789012,34567890123,45678901234

data[].config.transaction_controls.require_card_not_present_card_security_code

boolean
Conditionally returned

A value of true indicates that if card_presence_required is true, the card’s security code is required.

Allowable Values:

true, false

Default value:
false

data[].config.transaction_controls.strong_customer_authentication_limits

object
Conditionally returned

Contains information about Strong Customer Authentication (SCA) behavior for contactless point-of-sale (POS) and low-value payment (LVP) e-commerce transactions.

Allowable Values:

A valid strong_customer_authentication_limits object

data[].config.transaction_controls.strong_customer_authentication_limits.sca_contactless_cumulative_amount_limit

decimal
Conditionally returned

Specifies the cumulative limit of transactions the cardholder can perform before receiving an SCA challenge.

A value of 0 in this field means that the cumulative amount spent in contactless POS transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transaction_limit

decimal
Conditionally returned

Specifies the maximum allowable amount for a single contactless point-of-sale (POS) transaction, above which the cardholder receives a strong customer authentication (SCA) challenge.

A value of 0 in this field means that the amount of any single contactless POS transaction performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transactions_count_limit

integer
Conditionally returned

Specifies the number of contactless POS transactions the cardholder can perform before receiving an SCA challenge.

A value of 0 in this field means that the number of contactless POS transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

An integer, such as 5.

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_contactless_transactions_currency

string
Conditionally returned

Specifies the currency type for contactless POS transactions.

This field is required if either the sca_contactless_transaction_limit field or the sca_contactless_cumulative_amount_limit field in this object contains a value, even if that value is 0.

Allowable Values:

A valid three-digit ISO 4217 currency type, such as EUR.

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_lvp_cumulative_amount_limit

decimal
Conditionally returned

Specifies the cumulative limit of LVP e-commerce transactions the cardholder can perform before receiving an SCA challenge.

For example, if you set the value of this field to 100.00, your cardholder can perform two transactions for 30.00 and two transactions for 20.00 before receiving an SCA challenge.

If you leave this field blank, the cumulative amount spent in LVP e-commerce transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transaction_limit

decimal
Conditionally returned

Specifies the maximum allowable amount for a single low-value payment (LVP) e-commerce transaction, above which the cardholder receives a strong customer authentication (SCA) challenge.

If you leave this field blank, the amount of any single LVP e-commerce transaction performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

Format: 0.00

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transactions_count_limit

integer
Conditionally returned

Specifies the number of LVP e-commerce transactions the cardholder can perform before receiving an SCA challenge.

If you leave this field blank, the total number of LVP e-commerce transactions performed by the cardholder does not impact the decision of whether or not an SCA challenge is served.

Allowable Values:

An integer, such as 5.

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_lvp_transactions_currency

string
Conditionally returned

Specifies the currency type for LVP e-commerce transaction limits.

This field is required if any one of the sca_lvp_transaction_limit, sca_lvp_cumulative_amount_limit, or sca_lvp_transactions_count_limit fields in this object contains a value, even if that value is 0.

Allowable Values:

A valid three-digit ISO 4217 currency type, such as EUR.

There is no default value for this field.

data[].config.transaction_controls.strong_customer_authentication_limits.sca_tra_exemption_amount_limit

decimal
Conditionally returned

Specifies the maximum allowable amount for a single low-value payment (LVP) e-commerce transaction with transaction risk analysis (TRA) exemption sent by the merchant or acquirer. If the transaction amount exceeds the specified limit, then the transaction is either approved or it receives a strong customer authentication (SCA) challenge based on sca_lvp_transaction_limit and sca_lvp_transactions_currency.

Allowable Values:

Format: 0.00

Default value:
0.00

data[].created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2021-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-DD-mmT00:00:00Z

data[].end_date

date
Conditionally returned

The end date of the range over which the card product can be active.

Allowable Values:

Format: yyyy-DD-mm

data[].last_modified_time

datetime
Returned

The date and time when the resource was last updated, in UTC. 2021-10-26T20:03:15Z, for example.

Allowable Values:

Format: yyyy-DD-mmT00:00:00Z

data[].name

string
Returned

The name of the card product.

Allowable Values:

1–40 chars

data[].start_date

date
Returned

The date when the card product becomes active.

Allowable Values:

Format: yyyy-DD-mm

data[].token

string
Conditionally returned

The unique identifier of the card product.

Allowable Values:

1–36 chars

If you did not include a token in your request, the system returns an automatically generated token in the response.

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update card product

Action: PUT
Endpoint: /cardproducts/{token}

Use this endpoint to update a card product. Only values of fields in the request are modified; all others are left unchanged.

URL path parameters
Fields Description

token

string
Required

Identifies the card product to update.

Allowable Values:

Existing card product token

Request body
Fields Description

active

boolean
Optional

Indicates whether the card product is active.

NOTE: This field has no effect on the ability to create cards from this card product. Use the config.fulfillment.allow_card_creation field to allow/disallow card creation.

Allowable Values:

true, false

Default value:
true

config

object
Optional

Defines the characteristics of the card product. Configurations are conditionally required based on program setup.

Allowable Values:

A valid config object

config.card_life_cycle

object
Optional

Defines characteristics of the lifecycle of cards of this card product type.

Allowable Values:

A valid card_life_cycle object

config.card_life_cycle.activate_upon_issue

boolean
Optional

A value of true indicates that cards of this card product type are active once they are issued.

Allowable Values:

true, false

Default value:
false

config.card_life_cycle.card_service_code

integer
Optional

A sequence of three digits that defines various services, differentiates card usage in international or domestic interchange, designates PIN and authorization requirements, and identifies card restrictions. The following values are commonly used:

First digit

  • 1 — International interchange OK

  • 2 — International interchange, use IC (chip) where feasible

  • 5 — National interchange only except under bilateral agreement

  • 6 — National interchange only except under bilateral agreement, use IC (chip) where feasible

  • 7 — No interchange except under bilateral agreement (closed loop)

  • 9 — Test

Second digit

  • 0 — Normal

  • 2 — Contact issuer via online means

  • 4 — Contact issuer via online means except under bilateral agreement

Third digit

  • 0 — No restrictions, PIN required

  • 1 — No restrictions

  • 2 — Goods and services only (no cash)

  • 3 — ATM only, PIN required

  • 4 — Cash only

  • 5 — Goods and services only (no cash), PIN required

  • 6 — No restrictions, use PIN where feasible

  • 7 — Goods and services only (no cash), use PIN where feasible

Allowable Values:

100 - 999

Default value:
101

config.card_life_cycle.expiration_offset

object
Optional

Specifies the length of time after the date of issue for which cards of this card product type are valid.

Allowable Values:

A valid expiration_offset object

config.card_life_cycle.expiration_offset.min_offset

object
Optional

Specifies the minimum length of time after the date of issue for which the cards are valid.

Allowable Values:

Valid min_offset object

config.card_life_cycle.expiration_offset.min_offset.unit

string
Optional

Specifies the minimum offset unit.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default Value
expiration_offset.unit

config.card_life_cycle.expiration_offset.min_offset.value

integer
Optional

Specifies the minimum offset value.

Allowable Values:

Default Value
expiration_offset.value

config.card_life_cycle.expiration_offset.unit

string
Optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value:
YEARS

config.card_life_cycle.expiration_offset.value

integer
Optional

Specifies the number of time units (as defined by the unit field in this object) that cards of this card product type are valid. In other words, cards expire value x unit after the date of issue.

This number is rounded as follows:

  • YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and value = 1, the cards expire on the last day of Jan 2022.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and value = 1, the cards expire on the last day of June 2022.

  • DAYS – Rounds up to the last second of the day of expiration.

  • HOURS, MINUTES, SECONDS – No rounding.

Allowable Values:

Any positive integer

Default value:
4

config.card_life_cycle.update_expiration_upon_activation

boolean
Optional

Normally, the expiration_offset is measured from the date of issue. Set this field to true to measure expiration_offset from the date of activation instead.

Allowable Values:

true, false

Default value:
false

config.clearing_and_settlement

object
Optional

Specifies the destination for overdraft funds.

Allowable Values:

A valid clearing_and_settlement object

config.clearing_and_settlement.overdraft_destination

string
Optional

Specifies the destination for overdraft funds.

This field does not apply if JIT Funding is enabled.

Allowable Values:

GPA, MSA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value:
GPA

config.digital_wallet_tokenization

object
Optional

Controls characteristics related to digital wallets.

Allowable Values:

A valid digital_wallet_tokenization object

config.digital_wallet_tokenization.card_art_id

string
Optional

Specifies the digital wallet card art identifier for the card product. Digital wallets display the card art after the initial token has been provisioned and activated. Digital wallet card art is updated for all wallets automatically whenever a tokenized card is reissued or replaced.

  • If your card program is Managed by Marqeta, Marqeta populates this field on your behalf.

  • If your card program is Powered by Marqeta, you can obtain the correct card art identifier directly from Visa or Mastercard.

If this field is left blank, your card product inherits the card art assigned to the account BIN range.

Allowable Values:

Valid identifiers are defined by Visa or Mastercard and vary by program:

  • For Visa card products, this identifier is a GUID called profileID.

  • For Mastercard card products, this identifier is a string called ProductConfigID.

config.digital_wallet_tokenization.provisioning_controls

object
Optional

Controls the provisioning of digital wallets.

Allowable Values:

A valid provisioning_controls object

config.digital_wallet_tokenization.provisioning_controls.in_app_provisioning

object
Optional

Controls the provisioning of digital wallets by a Marqeta customer’s mobile application.

Allowable Values:

A valid in_app_provisioning object

config.digital_wallet_tokenization.provisioning_controls.manual_entry

object
Optional

Controls the provisioning of digital wallets by manual entry, in which the cardholder manually enters the card’s PAN, CVV2, and expiration date.

Allowable Values:

A valid manual_entry object

config.digital_wallet_tokenization.provisioning_controls.wallet_provider_card_on_file

object
Optional

Controls the provisioning of digital wallets where the digital wallet provider already has the card on file.

Allowable Values:

A valid wallet_provider_card_on_file object

config.digital_wallet_tokenization.provisioning_controls.web_push_provisioning

object
Optional

Specifies the digital wallet card art and program configuration identifiers at the card product level for Web Push Provisioning.

Allowable Values:

A valid web_push_provisioning object

config.fulfillment

object
Optional

Determines physical characteristics of a card, along with its bulk shipment information.

Allowable Values:

A valid fulfillment object

config.fulfillment.all_zero_card_security_code

boolean
Optional

If true, an all zero code (000) is allowed as a valid value in an authorization request.

Allowable Values:

true, false

Default value:
false

config.fulfillment.allow_card_creation

boolean
Optional

Controls the ability to create cards from this card product; true allows and false disallows the creation of cards.

NOTE: The card product’s active field has no effect on card creation or the behavior of this field.

Allowable Values:

true, false

Default value:
true

config.fulfillment.bin_prefix

string
Optional

The prefix of the bank identification number.

Allowable Values:

A six-digit number for the sandbox environment; a six- to nine-digit number is expected in production environments (see note below).

Default value:
111111

NOTE: In the sandbox environment or when testing against OpenAPI (Swagger), this field must be set to 111111. It is preferable to use eight- or nine-digit BIN prefixes in production environments. Contact your Marqeta representative for the appropriate value to use.

config.fulfillment.bulk_ship

boolean
Optional

Enables bulk ordering of cards of this card product type using the /bulkissuances endpoint.

Allowable Values:

true, false

Default value:
false

config.fulfillment.card_personalization

object
Required

Allows personalized attributes to be added to the card product.

Allowable Values:

A valid card_personalization object

config.fulfillment.card_personalization.carrier

object
Optional

Specifies attributes of the card carrier.

Allowable Values:

Valid carrier object

config.fulfillment.card_personalization.carrier.logo_file

string
Optional

Specifies an image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Optional

Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.message_file

string
Optional

Specifies a text file containing a custom message to print on the card carrier.

Allowable Values:

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.carrier.message_line

string
Optional

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

config.fulfillment.card_personalization.carrier.template_id

string
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID

config.fulfillment.card_personalization.images

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Existing images object

config.fulfillment.card_personalization.images.card

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

Valid images.card object

config.fulfillment.card_personalization.images.card.name

string
Optional

Specifies a PNG image to display on the card.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.card.thermal_color

string
Optional

Specifies the color of the image displayed on the card.

Allowable Values:

Contains the name of the color and must match one of the provider’s predefined colors.

config.fulfillment.card_personalization.images.carrier

object
Optional

Specifies personalized images that appear on the card carrier.

Allowable Values:

Valid carrier object

config.fulfillment.card_personalization.images.carrier.message_1

string
Optional

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

config.fulfillment.card_personalization.images.carrier.name

string
Optional

Specifies a PNG image to display on the card carrier.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.carrier_return_window

object
Optional

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Valid carrier_return_window object

config.fulfillment.card_personalization.images.carrier_return_window.name

string
Optional

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.images.signature

object
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Valid signature object

config.fulfillment.card_personalization.images.signature.name

string
Optional

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

config.fulfillment.card_personalization.perso_type

string
Optional

Specifies the type of card personalization.

Allowable Values:

EMBOSS, LASER, FLAT

config.fulfillment.card_personalization.text

object
Required

Specifies personalized text that appears on the card.

Allowable Values:

Valid text object

config.fulfillment.card_personalization.text.name_line_1

object
Required

Specifies the first line of personalized text that appears on the card.

Allowable Values:

name_line_1.value

21 char max; if name_line_1_numeric_postfix is true, 14 char max

Strings longer than the character limit are truncated.

config.fulfillment.card_personalization.text.name_line_1.value

string
Optional

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.card_personalization.text.name_line_2

object
Optional

Specifies the second line of personalized text that appears on the card.

Allowable Values:

name_line_2.value

config.fulfillment.card_personalization.text.name_line_2.value

string
Optional

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.card_personalization.text.name_line_3

object
Optional

Specifies the third line of personalized text that appears on the card.

Allowable Values:

name_line_3.value

config.fulfillment.card_personalization.text.name_line_3.value

string
Optional

A line of personalized text printed on the card.

Allowable Values:

21 char max

config.fulfillment.enable_offline_pin

boolean
Optional

Enables offline PIN verification for EMV ("chip-and-PIN") card payments.

Allowable Values:

true, false

Default value:
false

config.fulfillment.fulfillment_provider

string
Optional

Specifies the fulfillment provider.

NOTE: Expedited processing is available for cards that are fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions. You can expedite an order’s processing by using the expedite field of the card or bulkissuance object. Contact your Marqeta representative for information regarding the cost of expedited service.

Allowable Values:

PERFECTPLASTIC, ARROWEYE, IDEMIA, IDEMIA_UK, IDEMIA_FR, IDEMIA_CZ, IDEMIA_APAC, IDEMIA_PL, IDEMIA_AU, IDEMIA_LA, GEMALTO, NITECREST, OBERTHUR, ALLPAY, IDEMIA_FR_SC, GD, NITECREST_UK_SC, NITECREST_PL, TAG, IDEMIA_DE, FIS, CPI, EXCEET_DE, OBERTHUR_SC, IDEMIA_PE

Default value:
PERFECTPLASTIC

config.fulfillment.package_id

string
Optional

Card fulfillment provider’s package ID.

Allowable Values:

1–50 chars

config.fulfillment.pan_length

string
Optional

Specifies the length of the primary account number (PAN).

Allowable Values:

Default value: 16

config.fulfillment.payment_instrument

string
Optional

Specifies the physical form cards of this card product type will take.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

Default value:
PHYSICAL_MSR

config.fulfillment.shipping

object
Optional

Specifies shipping details for the order.

Allowable Values:

Valid shipping object

config.fulfillment.shipping.care_of_line

string
Optional

Adds the specified value as a care of (C/O) line to the mailing carrier.

Allowable Values:

255 char max

config.fulfillment.shipping.method

string
Optional

Specifies the shipping service.

Allowable Values:

LOCAL_MAIL, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.

config.fulfillment.shipping.recipient_address

object
Optional

Address to which the order will be shipped.

In order to generate cards, a valid shipping address must be provided by one of these:

  • The card or bulk card order’s fulfillment.shipping.recipient_address field

  • The users' address fields

  • The card product’s config.fulfillment.shipping.recipient_address field

The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the address1, city, state, and postal_code or zip fields populated. The country field defaults to USA if unpopulated.

Allowable Values:

Valid recipient_address object

config.fulfillment.shipping.recipient_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.recipient_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.recipient_address.city

string
Optional

City.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.country

string
Optional

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

config.fulfillment.shipping.recipient_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

config.fulfillment.shipping.recipient_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

config.fulfillment.shipping.recipient_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

config.fulfillment.shipping.recipient_address.state

string
Optional

State.

Allowable Values:

32 char max

config.fulfillment.shipping.recipient_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

config.fulfillment.shipping.return_address

object
Optional

Address to which the order will be returned if shipping fails.

Allowable Values:

Valid return_address object

config.fulfillment.shipping.return_address.address1

string
Optional

Number and street.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.return_address.address2

string
Optional

Additional address information.

Allowable Values:

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

config.fulfillment.shipping.return_address.city

string
Optional

City.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.country

string
Optional

Country.

Allowable Values:

40 char max

The English short name. For example, for Spain, use the English short name "Spain".

The ISO maintains the full list of country codes.

config.fulfillment.shipping.return_address.first_name

string
Optional

First name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.last_name

string
Optional

Last name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.middle_name

string
Optional

Middle name.

Allowable Values:

40 char max

config.fulfillment.shipping.return_address.phone

string
Optional

Telephone number.

Allowable Values:

20 char max

config.fulfillment.shipping.return_address.postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

config.fulfillment.shipping.return_address.state

string
Optional

State.

Allowable Values:

32 char max

config.fulfillment.shipping.return_address.zip

string
Optional

United States ZIP code.

Allowable Values:

10 char max

config.fulfillment.uppercase_name_lines

boolean
Optional

A value of true sets the text in the fulfillment.card_personalization.text.name_line_1 and name_line_2 fields to all uppercase letters. A value of false leaves the text in its original state.

Allowable Values:

true, false

Default value:
true

config.jit_funding

object
Optional

Governs the behavior of JIT Funding.

Allowable Values:

A valid jit_funding object

config.jit_funding.paymentcard_funding_source

object
Optional

Allows for the enabling and configuration of a payment card funding source.

Allowable Values:

A valid paymentcard_funding_source object

config.jit_funding.paymentcard_funding_source.enabled

boolean
Optional

Specifies whether JIT Funding is enabled or disabled for the payment card funding source. A value of true indicates that the payment card funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.paymentcard_funding_source.refunds_destination

string
Optional

Specifies the return destination for refunds in the case of a transaction reversal.

Allowable Values:

GATEWAY, GPA, WATERFALL

config.jit_funding.program_funding_source

object
Optional

Allows for the enabling and configuration of a program funding source.

Allowable Values:

A valid program_funding_source object

config.jit_funding.program_funding_source.enabled

boolean
Optional

Specifies whether JIT Funding is enabled or disabled for the program funding source. A value of true indicates that the program funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.program_funding_source.funding_source_token

string
Optional

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

config.jit_funding.program_funding_source.refunds_destination

string
Optional

Specifies the return destination for refunds in the case of a transaction reversal. PROGRAM_FUNDING_SOURCE returns funds to the program funding source. GPA returns the funds to the user’s GPA.

Allowable Values:

PROGRAM_FUNDING_SOURCE, GPA, WATERFALL

config.jit_funding.programgateway_funding_source

object
Optional

Allows for the enabling and configuration of a program gateway funding source.

Allowable Values:

A valid programgateway_funding_source object

config.jit_funding.programgateway_funding_source.always_fund

boolean
Optional

If set to true, this card product is always funded from this program gateway funding source.

Allowable Values:

true, false

Default value:
false

config.jit_funding.programgateway_funding_source.enabled

boolean
Optional

Specifies whether JIT Funding is enabled or disabled for the program gateway funding source. A value of true indicates that the program gateway funding source is enabled and will be debited when swipes occur.

Allowable Values:

true, false

Default value:
false

config.jit_funding.programgateway_funding_source.funding_source_token

string
Optional

The unique identifier of the already existing funding source. Required if JIT Funding is enabled.

Allowable Values:

36 char max

config.jit_funding.programgateway_funding_source.refunds_destination

string
Optional

Specifies the return destination for refunds in the case of a transaction reversal. In most cases, you should set the value to GATEWAY, which returns funds to the program gateway funding source. Setting to GPA returns the funds to the user’s GPA, which creates a positive account balance and introduces the potential of a transaction being authorized without a JIT Funding request being sent to the gateway.

Allowable Values:

GATEWAY, GPA, WATERFALL

config.poi

object
Optional

Governs the point of interaction.

Allowable Values:

A valid poi object

config.poi.atm

boolean
Optional

A value of true enables cards to be used for withdrawing cash at an ATM and for receiving cash back at a point of sale (POS).

Allowable Values:

true, false

Default value:
false

config.poi.ecommerce

boolean
Optional

A value of true enables cards to be used for online purchases.

Allowable Values:

true, false

Default value:
false

config.poi.other

object
Optional

Allows for configuration of points of interaction other than ecommerce or ATMs, such as points of sale (POS).

Allowable Values:

A valid other object

config.poi.other.allow

boolean
Optional

If set to true, card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes points of sale (POS).

Allowable Values:

true, false

Default value:
true

config.poi.other.card_presence_required

boolean
Optional

If set to true, cards of this card product type are required to be present during the transaction, such as in IVR scenarios.

Allowable Values:

true, false

Default value:
false

config.poi.other.cardholder_presence_required

boolean
Optional

A value of true indicates that the cardholder is required to be present, such as in a restaurant where the card is present but the cardholder is not present when the card is swiped.

Allowable Values:

true, false

Default value:
false

config.selective_auth

object
Optional

Contains information about authorization decisions.

Allowable Values:

A valid selective_auth object

config.selective_auth.dmd_location_sensitivity

integer
Optional

Determines what type of merchant information is required for a match (authorization). Not relevant if enable_regex_search_chain = false.

  • 0 – Requires exact match on card acceptor name and postal code to existing entry in Marqeta Merchant database (most restrictive).

  • 1 – Partial match on card acceptor name (least restrictive).

  • 2 – Partial match on card acceptor name; exact match on card acceptor city.

  • 3 – Partial match on card acceptor name; exact match on card acceptor postal code.

  • 4 – Partial match on card acceptor name; exact match on street address 1 and postal code.

Allowable Values:

0, 1, 2, 3, 4

Default value:
0

config.selective_auth.enable_regex_search_chain

boolean
Optional

Use true to perform regular expression checking on the description received in the authorization.

Allowable Values:

true , false

Default value:
false

config.selective_auth.sa_mode

integer
Optional

  • 0 — Inactive

  • 1 — Active (attempts to authorize a merchant that does not have a recognized MID by matching other pieces of information)

  • 2 — Logging and notification (checks the transaction and logs results, but does not authorize)

Selective authorization applies to transactions that are limited to specific merchants. Matching requirements for authorization are set by the dmd_location_sensitivity field.

Allowable Values:

0, 1, 2

Default value:
0

config.special

object
Optional

Contains information about merchant onboarding.

Allowable Values:

A valid special object

config.special.merchant_on_boarding

boolean
Optional

A value of true indicates cards of this card product type can be used for merchant onboarding.

Allowable Values:

true,