/

55 minute read

July 1, 2020

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.

In most cases, 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:

  1. card

  2. bulkissuance

  3. 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.

Note
For more information on cards, see About Cards.

Create card product

Action: POST
Endpoint: /cardproducts

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to create a card product.

The card product request comprises a set of fields that provide basic information about the card product, such as name, active/inactive status, and start and end dates (see Body Field Details — Basic Information). Configuration information is contained in the config object, which contains sub-elements whose fields control the features/behavior of the card product. The elements are referred to as the card product "configuration," and as such are contained in a config object.

Body field details (basic information)

Fields Description

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:

36 char max

name

string
Required

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

Allowable Values:

40 char max

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

start_date

string
Required

The date 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:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

end_date

string
Optional

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

Allowable Values:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

config

object
Conditionally required

Defines the characteristics of the card product. Configurations are conditionally required based on program setup. For more information, contact your Marqeta representative.

Allowable Values:

Existing config object.

The config object

Fields Description

poi

object
Optional

Governs the point of interaction.

transaction_controls

object
Optional

Controls transactional characteristics of card usage.

fulfillment

object
Optional

Determines physical characteristics of a card and bulk shipment information.

special

object
Optional

Contains information about merchant on-boarding.

selective_auth

object
Optional

Contains information about authorization decisions.

card_life_cycle

object
Optional

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

clearing_and_settlement

object
Optional

Specifies the destination for overdraft funds.

jit_funding

object
Optional

Governs the behavior of JIT Funding.

digital_wallet_tokenization

object
Optional

Controls characteristics related to digital wallets.

The config.poi object

Fields Description

other

object
Optional

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

Allowable Values:

ecommerce

boolean
Optional

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

Allowable Values:

true, false

Default value: false

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

The config.poi.other object

Fields Description

allow

boolean
Optional

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

Allowable Values:

true, false

Default value: true

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

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

The config.transaction_controls object

Fields Description

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

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

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

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

address_verification

object
Optional

Contains configuration options for AVS.

Allowable Values:

require_card_not_present_card_security_code

boolean
Optional

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

Allowable Values:

true, false

Default value: false

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

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

allow_first_pin_set_via_financial_transaction

boolean
Optional

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

Allowable Values:

true, false

Default value: false

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

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

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

allow_quasi_cash

boolean
Optional

Indicates whether transactions involving quasi cash are allowed.

Allowable Values:

true, false

Default value: false

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

The config.transaction_controls.address_verification object

Fields Description

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:

auth_messages

object
Optional

Contains verification options for authorization messages.

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

Allowable Values:

The config.transaction_controls.address_verification.av_messages object

Fields Description

validate

boolean
Optional

Set to true to require validation of account verification messages.

Set to false to forgo validation and approve all account verification messages.

Allowable Values:

true, false

Default value: true

decline_on_address_number_mismatch

boolean
Optional

Set to true to decline account verification messages whose address number does not match the address number on file.

Set to false to not decline account verification messages whose address number does not match the address number on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: false

decline_on_postal_code_mismatch

boolean
Optional

Set to true to decline account verification messages whose postal code does not match the postal code on file.

Set to false to not decline account verification messages whose postal code does not match the postal code on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: true

The config.transaction_controls.address_verification.auth_messages object

Fields Description

validate

boolean
Optional

Set to true to require validation of authorization messages.

Set to false to forgo validation and approve all authorization messages.

Allowable Values:

true, false

Default value: true

decline_on_address_number_mismatch

boolean
Optional

Set to true to decline authorization messages whose address number does not match the address number on file.

Set to false to not decline authorization messages whose address number does not match the address number on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: false

decline_on_postal_code_mismatch

boolean
Optional

Set to true to decline authorization messages whose postal code does not match the postal code on file.

Set to false to not decline authorization messages whose postal code does not match the postal code on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: false

The config.fulfillment object

Fields Description

fulfillment_provider

string
Optional

Specifies the fulfillment provider.

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

No expedited processing is available for card orders fulfilled by Arroweye Solutions. To expedite shipping cards by Arroweye Solutions, use the method field of the config.fulfillment.shipping object instead.

Allowable Values:

PERFECTPLASTIC, ARROWEYE, IDEMIA

Default value: PERFECTPLASTIC

shipping

object
Optional

Specifies the shipping details for cards of this card product type.

Allowable Values:

Existing shipping object

bin_prefix

string
Optional

The prefix of the bank identification number.

Allowable Values:

Default value: 111111

Note
In the sandbox environment, this field must be set to 111111.

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

package_id

string
Optional

Card fulfillment provider’s package ID.

Allowable Values:

50 char max

pan_length

string
Optional

Specifies the length of the PAN.

Allowable Values:

Default value: 16

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

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

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

card_personalization

object
Optional

Allows personalized attributes to be added to the card product.

Allowable Values:

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-capital letters. A setting of false leaves the text in its original state.

Allowable Values:

true, false

Default value: true

The config.fulfillment.shipping object

Fields Description

return_address

object
Optional

Address to which cards will be returned if shipping fails.

Allowable Values:

recipient_address

object
Optional

Address to which cards will be shipped.

Allowable Values:

method

string
Optional

Specifies the shipping company and shipping service level.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to true, this field is ignored and the shipping method is implicitly FEDEX_EXPEDITED.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to false, you must specify the shipping company and service level using the method field.

  • If your fulfillment provider is Arroweye Solutions, you must specify the shipping company and service level using the method field.

Allowable Values:

Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and IDEMIA: USPS_REGULAR, FEDEX_EXPEDITED

Arroweye Solutions: UPS_REGULAR, UPS_EXPEDITED, USPS_REGULAR, USPS_EXPEDITED

care_of_line

string
Optional

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

Note
This field can also be specified on cards and bulk card orders. If specified at both levels, the field on cards and bulk card orders takes precedence over the card product.

Allowable Values:

255 char max

The config.fulfillment.shipping.return_address & recipient_address objects

Fields Description

address1

string
Optional

Number and street.

Allowable Values:

255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

address2

string
Optional

Additional address information.

Allowable Values:

255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

city

string
Optional

City.

Allowable Values:

40 char max

state

string
Optional

State.

Allowable Values:

50 char max

postal_code

string
Optional

Postal code.

Allowable Values:

50 char max

country

string
Optional

Country.

Allowable Values:

40 char max

phone

string
Optional

Telephone number.

Allowable Values:

50 char max

first_name

string
Optional

First Name.

Allowable Values:

50 char max

middle_name

string
Optional

Middle Name.

Allowable Values:

50 char max

last_name

string
Optional

Last Name.

Allowable Values:

50 char max

The config.fulfillment.card_personalization object

Note
Card personalization attributes defined at the card or bulk card order level override matching attributes of the associated card product at fulfillment time. Contact your Marqeta representative to make use of card personalization.
Fields Description

text

object
Optional

Specifies personalized text that appears on the card.

carrier

object
Optional

Specifies attributes of the card carrier.

images

object
Optional

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

The config.fulfillment.card_personalization.text object

Fields Description

name_line_1.value

string
Optional

First line of personalized text printed on the card.

Allowable Values:

21 char max. Strings longer than 21 characters are truncated.

name_line_2.value

string
Optional

Second line of personalized text printed on the card.

Allowable Values:

21 char max. Strings longer than 21 characters are truncated.

The fulfillment.card_personalization.carrier object

Fields Description

template_id

string
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID.

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.

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.

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.

message_line

string
Optional

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

The config.fulfillment.card_personalization.images object

Fields Description

card

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

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.

Must end in .png.

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.

Must end in .png.

The config.fulfillment.card_personalization.images.card object

Fields Description

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.

Must end in .png.

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.

The config.selective_auth object

Fields Description

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: 1

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

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 CA name; exact match on street address 1 and postal_code.

Allowable Values:

0, 1, 2, 3, 4

Default value: 0

The config.special object

Fields Description

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

The config.card_life_cycle object

Fields Description

activate_upon_issue

boolean
Optional

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

Allowable Values:

true, false

Default value: false

expiration_offset

object
Optional

Specifies the length of time for which cards of this card product type are valid. In other words, cards expire this length of time after the date of issue.

Allowable Values:

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

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

The config.card_life_cycle.expiration_offset object

Fields Description

unit

string
Optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value: YEARS

value

integer
Optional

Specifies the number of time units (as defined by the unit field) 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 2018 and value = 1, the card expires on the last day of Jan 2019.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2018 and value = 1, the card expires on the last day of Feb 2018.

  • 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

min_offset

object
Optional

Specifies the minimum expiration offset allowed by this card product. If not specified, the min_offset equals the expiration_offset.

Allowable Values:

The config.card_life_cycle.expiration_offset.min_offset object

Fields Description

unit

string
Optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value: YEARS

value

integer
Optional

Specifies the number of time units (as defined by the unit field) 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 2018 and value = 1, the card expires on the last day of Jan 2019.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2018 and value = 1, the card expires on the last day of Feb 2018.

  • 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

The config.clearing_and_settlement object

Fields Description

overdraft_destination

string
Optional

Specifies the destination for overdraft funds.

This field does not apply if JIT Funding is enabled.

Allowable Values:

GPA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value: GPA

The config.jit_funding object

Name Type Required? Description

programgateway_funding_source

object

Optional

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

program_funding_source

object

Optional

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

The config.jit_funding.programgateway_funding_source object

Fields Description

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

funding_source_token

string
Optional

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

Allowable Values:

Existing funding source token

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

The config.jit_funding.program_funding_source object

Fields Description

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

funding_source_token

string
Optional

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

Allowable Values:

Existing funding source token

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

The config.digital_wallet_tokenization object

Fields Description

provisioning_controls

object
Optional

Controls the provisioning of digital wallets.

Allowable Values:

The config.digital_wallet_tokenization.provisioning_controls object

Fields Description

manual_entry

boolean
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:

wallet_provider_card_on_file

boolean
Optional

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

Allowable Values:

in_app_provisioning

boolean
Optional

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

Allowable Values:

The config.digital_wallet_tokenization.provisioning_controls.manual_entry, wallet_provider_card_on_file and in_app_provisioning objects

Fields Description

enabled

boolean
Optional

A value of true enables the type of provisioning controlled by the setting.

Allowable Values:

true, false

Default value: false

address_verification.validate

boolean
Optional

Set to true to enable the address verification system (AVS) for provisioning.

Allowable Values:

true, false

Default value: true

Sample request body

{
  "name": "My Card Product 01",
  "token": "my_cardproduct_01",
  "start_date": "2017-04-27",
  "config": {
    "poi" : {
      "ecommerce" : false,
      "atm" : false,
      "other": {
        "allow": true,
        "card_presence_required": false,
        "cardholder_presence_required": false
      }
    },
    "transaction_controls" : {
      "accepted_countries_token": "accept_us_only",
      "always_require_pin": false,
      "always_require_icc": false,
      "allow_gpa_auth": true,
      "require_card_not_present_card_security_code": false,
      "allow_mcc_group_authorization_controls": true,
      "allow_first_pin_set_via_financial_transaction": true,
      "ignore_card_suspended_state": false,
      "allow_network_load": false,
      "allow_network_load_card_activation": false,
      "allow_quasi_cash": false,
      "enable_partial_auth_approval": true
    },
    "fulfillment": {
      "shipping": {
        "return_address": {
          "address1": "123 Henry St",
          "address2": "Suite 101",
          "city": "Porterville",
          "state": "CA",
          "postal_code": "93257",
          "country": "USA",
          "phone": "8315555555",
          "first_name": "Saki",
          "middle_name": "R",
          "last_name": "Dogger"
        },
        "recipient_address": {
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "3451239876",
          "first_name": "Big",
          "last_name": "Bird"
        },
        "method": "FEDEX_EXPEDITED"
      },
      "payment_instrument": "PHYSICAL_MSR",
      "package_id": "0",
      "all_zero_card_security_code": false,
      "bin_prefix": "111111",
      "bulk_ship": false,
      "pan_length": "16",
      "fulfillment_provider": "PERFECTPLASTIC"
    },
    "selective_auth" : {
      "sa_mode" : 1,
      "enable_regex_search_chain" : false,
      "dmd_location_sensitivity" : 0
    },
    "card_life_cycle" : {
      "activate_upon_issue" : true,
      "expiration_offset": {
        "unit": "YEARS",
        "value": 10
      },
      "card_service_code" : 101,
      "update_expiration_upon_activation": false
    },
    "jit_funding": {
      "paymentcard_funding_source": {
        "enabled": true
      }
    }
  }
}

Is this helpful?

Sample response body

{
  "token": "my_cardproduct_01",
  "name": "My Card Product 01",
  "active": true,
  "config": {
    "poi": {
      "other": {
        "allow": true,
        "card_presence_required": false,
        "cardholder_presence_required": false
      },
      "ecommerce": false,
      "atm": false
    },
    "transaction_controls": {
      "accepted_countries_token": "accept_us_only",
      "always_require_pin": false,
      "always_require_icc": false,
      "allow_gpa_auth": true,
      "require_card_not_present_card_security_code": false,
      "allow_mcc_group_authorization_controls": true,
      "allow_first_pin_set_via_financial_transaction": true,
      "ignore_card_suspended_state": false,
      "allow_network_load": false,
      "allow_network_load_card_activation": false,
      "allow_quasi_cash": false,
      "enable_partial_auth_approval": true,
      "address_verification": {
        "av_messages": {
          "validate": true,
          "decline_on_address_number_mismatch": false,
          "decline_on_postal_code_mismatch": true
        },
        "auth_messages": {
          "validate": true,
          "decline_on_address_number_mismatch": false,
          "decline_on_postal_code_mismatch": false
        }
      }
    },
    "fulfillment": {
      "shipping": {
        "method": "FEDEX_EXPEDITED",
        "return_address": {
          "first_name": "Saki",
          "middle_name": "R",
          "last_name": "Dogger",
          "address1": "123 Henry St",
          "address2": "Suite 101",
          "city": "Porterville",
          "state": "CA",
          "postal_code": "93257",
          "country": "USA",
          "phone": "8315555555"
        },
        "recipient_address": {
          "first_name": "Big",
          "last_name": "Bird",
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "3451239876"
        }
      },
      "payment_instrument": "PHYSICAL_MSR",
      "package_id": "0",
      "all_zero_card_security_code": false,
      "bin_prefix": "111111",
      "bulk_ship": false,
      "pan_length": "16",
      "fulfillment_provider": "PERFECTPLASTIC",
      "allow_card_creation": true,
      "uppercase_name_lines": true
    },
    "selective_auth": {
      "sa_mode": 1,
      "enable_regex_search_chain": false,
      "dmd_location_sensitivity": 0
    },
    "special": {
      "merchant_on_boarding": false
    },
    "card_life_cycle": {
      "activate_upon_issue": true,
      "expiration_offset": {
        "unit": "YEARS",
        "value": 10,
        "min_offset": {
          "unit": "YEARS",
          "value": 4
        }
      },
      "card_service_code": 101,
      "update_expiration_upon_activation": false
    },
    "clearing_and_settlement": {
      "overdraft_destination": "GPA"
    },
    "jit_funding": {
      "paymentcard_funding_source": {
        "enabled": true,
        "refunds_destination": ""
      },
      "programgateway_funding_source": {
        "enabled": false,
        "funding_source_token": "",
        "refunds_destination": ""
      },
      "program_funding_source": {
        "enabled": false,
        "funding_source_token": "",
        "refunds_destination": ""
      }
    },
    "digital_wallet_tokenization": {
      "provisioning_controls": {
        "manual_entry": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        },
        "wallet_provider_card_on_file": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        },
        "in_app_provisioning": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        }
      }
    }
  },
  "start_date": "2017-04-27",
  "created_time": "2017-04-27T19:25:55Z",
  "last_modified_time": "2017-04-27T19:25:55Z"
}
{
    "api": "cardproducts",
    "endpoint": "/cardproducts",
    "method": "post",
    "cp_id": 1,
    "bc_id": 1
}

Is this helpful?

Retrieve card product

Action: GET
Endpoint: /cardproducts/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a specific card product.

URL path parameters

Fields Description

token

string
Required

Identifies the card product to retrieve.

Allowable Values:

Existing card product token.

Send a GET request to /cardproducts to retrieve existing card product tokens.

Sample response body

{
  "token": "my_cardproduct_01",
  "name": "My Card Product 01",
  "active": true,
  "config": {
    "poi": {
      "other": {
        "allow": true,
        "card_presence_required": false,
        "cardholder_presence_required": false
      },
      "ecommerce": false,
      "atm": false
    },
    "transaction_controls": {
      "accepted_countries_token": "accept_us_only",
      "always_require_pin": false,
      "always_require_icc": false,
      "allow_gpa_auth": true,
      "require_card_not_present_card_security_code": false,
      "allow_mcc_group_authorization_controls": true,
      "allow_first_pin_set_via_financial_transaction": true,
      "ignore_card_suspended_state": false,
      "allow_network_load": false,
      "allow_network_load_card_activation": false,
      "allow_quasi_cash": false,
      "enable_partial_auth_approval": true,
      "address_verification": {
        "av_messages": {
          "validate": true,
          "decline_on_address_number_mismatch": false,
          "decline_on_postal_code_mismatch": true
        },
        "auth_messages": {
          "validate": true,
          "decline_on_address_number_mismatch": false,
          "decline_on_postal_code_mismatch": false
        }
      }
    },
    "fulfillment": {
      "shipping": {
        "method": "FEDEX_EXPEDITED",
        "return_address": {
          "first_name": "Saki",
          "middle_name": "R",
          "last_name": "Dogger",
          "address1": "123 Henry St",
          "address2": "Suite 101",
          "city": "Porterville",
          "state": "CA",
          "postal_code": "93257",
          "country": "USA",
          "phone": "8315555555"
        },
        "recipient_address": {
          "first_name": "Big",
          "last_name": "Bird",
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "3451239876"
        }
      },
      "payment_instrument": "PHYSICAL_MSR",
      "package_id": "0",
      "all_zero_card_security_code": false,
      "bin_prefix": "111111",
      "bulk_ship": false,
      "pan_length": "16",
      "fulfillment_provider": "PERFECTPLASTIC",
      "allow_card_creation": true,
      "uppercase_name_lines": true
    },
    "selective_auth": {
      "sa_mode": 1,
      "enable_regex_search_chain": false,
      "dmd_location_sensitivity": 0
    },
    "special": {
      "merchant_on_boarding": false
    },
    "card_life_cycle": {
      "activate_upon_issue": true,
      "expiration_offset": {
        "unit": "YEARS",
        "value": 10,
        "min_offset": {
          "unit": "YEARS",
          "value": 4
        }
      },
      "card_service_code": 101,
      "update_expiration_upon_activation": false
    },
    "clearing_and_settlement": {
      "overdraft_destination": "GPA"
    },
    "jit_funding": {
      "paymentcard_funding_source": {
        "enabled": true,
        "refunds_destination": ""
      },
      "programgateway_funding_source": {
        "enabled": false,
        "funding_source_token": "",
        "refunds_destination": ""
      },
      "program_funding_source": {
        "enabled": false,
        "funding_source_token": "",
        "refunds_destination": ""
      }
    },
    "digital_wallet_tokenization": {
      "provisioning_controls": {
        "manual_entry": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        },
        "wallet_provider_card_on_file": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        },
        "in_app_provisioning": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        }
      }
    }
  },
  "start_date": "2017-04-27",
  "created_time": "2017-04-27T19:25:55Z",
  "last_modified_time": "2017-04-27T19:25:55Z"
}
{
    "api": "cardproducts",
    "endpoint": "/cardproducts/{token}",
    "method": "get",
    "cp_id": 1,
    "bc_id": 1
}

Is this helpful?

Update card product

Action: PUT
Endpoint: /cardproducts/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

The token identifying the card product to update.

Allowable Values:

Existing card product token.

Send a GET request to /cardproducts to retrieve existing card product tokens.

Body field details

Fields Description

name

string
Required

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

Allowable Values:

40 char max

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

start_date

string
Required

The date 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:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

end_date

string
Optional

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

Allowable Values:

yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

config

object
Conditionally required

Defines the characteristics of the card product. Configurations are conditionally required based on program setup. For more information, contact your Marqeta representative.

Allowable Values:

Existing config object.

The config object

Fields Description

poi

object
Optional

Governs the point of interaction.

transaction_controls

object
Optional

Controls transactional characteristics of card usage.

fulfillment

object
Optional

Determines physical characteristics of a card and bulk shipment information.

special

object
Optional

Contains information about merchant on-boarding.

selective_auth

object
Optional

Contains information about authorization decisions.

card_life_cycle

object
Optional

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

clearing_and_settlement

object
Optional

Specifies the destination for overdraft funds.

jit_funding

object
Optional

Governs the behavior of JIT Funding.

digital_wallet_tokenization

object
Optional

Controls characteristics related to digital wallets.

The config.poi object

Fields Description

other

object
Optional

Allows for configuration of points of interaction other than ecommerce or ATMs. This group includes point of sale (POS).

Allowable Values:

ecommerce

boolean
Optional

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

Allowable Values:

true, false

Default value: false

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

The config.poi.other object

Fields Description

allow

boolean
Optional

A value of true indicates that card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes point of sale (POS).

Allowable Values:

true, false

Default value: true

card_presence_required

boolean
Optional

A value of true indicates that 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

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

The config.transaction_controls object

Fields Description

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

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

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

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

address_verification

object
Optional

Contains configuration options for AVS.

Allowable Values:

require_card_not_present_card_security_code

boolean
Optional

True indicates that if allow_card_not_present is true, the card’s security code is required.

Allowable Values:

true, false

Default value: false

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

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

allow_first_pin_set_via_financial_transaction

boolean
Optional

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

Allowable Values:

true, false

Default value: false

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

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

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

allow_quasi_cash

boolean
Optional

Indicates whether transactions involving quasi cash are allowed.

Allowable Values:

true, false

Default value: false

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

The config.transaction_controls.address_verification object

Fields Description

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:

auth_messages

object
Optional

Contains verification options for authorization messages.

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

Allowable Values:

The config.transaction_controls.address_verification.av_messages object

Fields Description

validate

boolean
Optional

Set to true to require validation of account verification messages.

Set to false to forgo validation and approve all account verification messages.

Allowable Values:

true, false

Default value: true

decline_on_address_number_mismatch

boolean
Optional

Set to true to decline account verification messages whose address number does not match the address number on file.

Set to false to not decline account verification messages whose address number does not match the address number on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: false

decline_on_postal_code_mismatch

boolean
Optional

Set to true to decline account verification messages whose postal code does not match the postal code on file.

Set to false to not decline account verification messages whose postal code does not match the postal code on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: true

The config.transaction_controls.address_verification.auth_messages object

Fields Description

validate

boolean
Optional

Set to true to require validation of authorization messages.

Set to false to forgo validation and approve all authorization messages.

Allowable Values:

true, false

Default value: true

decline_on_address_number_mismatch

boolean
Optional

Set to true to decline authorization messages whose address number does not match the address number on file.

Set to false to not decline authorization messages whose address number does not match the address number on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: false

decline_on_postal_code_mismatch

boolean
Optional

Set to true to decline authorization messages whose postal code does not match the postal code on file.

Set to false to not decline authorization messages whose postal code does not match the postal code on file.

This field is functional only if validate = true.

Allowable Values:

true, false

Default value: false

The config.fulfillment object

Fields Description

fulfillment_provider

string
Optional

Specifies the fulfillment provider.

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

No expedited processing is available for card orders fulfilled by Arroweye Solutions. To expedite shipping cards by Arroweye Solutions, use the method field of the config.fulfillment.shipping object instead.

Allowable Values:

PERFECTPLASTIC, ARROWEYE, IDEMIA

Default value: PERFECTPLASTIC

shipping

object
Optional

Specifies the shipping details for cards of this card product type.

Allowable Values:

Existing shipping object

bin_prefix

string
Optional

The prefix of the bank identification number.

Allowable Values:

Default value: 1111111

Note
In the sandbox environment or when testing against Swagger, this field must be set to 111111.

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

package_id

string
Optional

Card fulfillment provider’s package ID.

Allowable Values:

50 char max

pan_length

string
Optional

Specifies the length of the PAN.

Allowable Values:

Default value: 16

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

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

allow_card_creation

boolean
Optional

Controls 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

uppercase_name_lines

boolean
Optional

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

Allowable Values:

true, false

Default value: true

The config.fulfillment.shipping object

Fields Description

return_address

object
Optional

Address to which cards will be returned if shipping fails.

Allowable Values:

recipient_address

object
Optional

Address to which cards will be shipped.

Allowable Values:

method

string
Optional

Specifies the shipping company and shipping service level.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to true, this field is ignored and the shipping method is implicitly FEDEX_EXPEDITED.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to false, you must specify the shipping company and service level using the method field.

  • If your fulfillment provider is Arroweye Solutions, you must specify the shipping company and service level using the method field.

Allowable Values:

Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and IDEMIA: USPS_REGULAR, FEDEX_EXPEDITED

Arroweye Solutions: UPS_REGULAR, UPS_EXPEDITED, USPS_REGULAR, USPS_EXPEDITED

care_of_line

string
Optional

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

Note
This field can also be specified on cards and bulk card orders. If specified at both levels, the field on cards and bulk card orders takes precedence over the card product.

Allowable Values:

255 char max

The config.fulfillment.shipping.return_address & recipient_address objects

Fields Description

address1

string
Optional

Number and street.

Allowable Values:

255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

address2

string
Optional

Additional address information.

Allowable Values:

255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

city

string
Optional

City.

Allowable Values:

40 char max

state

string
Optional

State.

Allowable Values:

50 char max

postal_code

string
Optional

Postal code.

Allowable Values:

50 char max

country

string
Optional

Country.

Allowable Values:

40 char max

phone

string
Optional

Telephone number.

Allowable Values:

50 char max

first_name

string
Optional

First Name.

Allowable Values:

50 char max

middle_name

string
Optional

Middle Name.

Allowable Values:

50 char max

last_name

string
Optional

Last Name.

Allowable Values:

50 char max

The config.fulfillment.card_personalization object

Note
Card personalization attributes defined at the card or bulk card order level override matching attributes of the associated card product at fulfillment time. Contact your Marqeta representative to make use of card personalization.
Fields Description

text

object
Optional

Specifies personalized text that appears on the card.

carrier

object
Optional

Specifies attributes of the card carrier.

images

object
Optional

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

The config.fulfillment.card_personalization.text object

Fields Description

name_line_1.value

string
Optional

First line of personalized text printed on the card.

Allowable Values:

21 char max. Strings longer than 21 characters are truncated.

name_line_2.value

string
Optional

Second line of personalized text printed on the card.

Allowable Values:

21 char max. Strings longer than 21 characters are truncated.

The fulfillment.card_personalization.carrier object

Fields Description

template_id

string
Optional

Specifies the card carrier template to use.

Allowable Values:

A card carrier template ID.

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.

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.

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.

The config.fulfillment.card_personalization.images object

Fields Description

card

object
Optional

Specifies personalized images that appear on the card.

Allowable Values:

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.

Must end in .png.

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.

Must end in .png.

The config.fulfillment.card_personalization.images.card object

Fields Description

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.

Must end in .png.

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.

The config.selective_auth object

Fields Description

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: 1

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

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 CA name, exact match on street address 1 and postal_code.

Allowable Values:

0, 1, 2, 3, 4

Default value: 0

The config.special object

Fields Description

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

The config.card_life_cycle object

Fields Description

activate_upon_issue

boolean
Optional

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

Allowable Values:

true, false

Default value: false

expiration_offset

object
Optional

Specifies the length of time for which cards of this card product type are valid. In other words, cards expire this length of time after the date of issue.

Allowable Values:

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:

  • 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

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

The config.card_life_cycle.expiration_offset object

Fields Description

unit

string
Optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value: YEARS

value

integer
Optional

Specifies the number of time units (as defined by the unit field) 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 2018 and value = 1, the card expires on the last day of Jan 2019.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2018 and value = 1, the card expires on the last day of Feb 2018.

  • 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

min_offset

object
Optional

Specifies the minimum expiration offset allowed by this card product. If not specified, the min_offset equals the expiration_offset.

Allowable Values:

The config.card_life_cycle.expiration_offset.min_offset object

Fields Description

unit

string
Optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value: YEARS

value

integer
Optional

Specifies the number of time units (as defined by the unit field) 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 2018 and value = 1, the card expires on the last day of Jan 2019.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2018 and value = 1, the card expires on the last day of Feb 2018.

  • 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

The config.clearing_and_settlement object

Fields Description

overdraft_destination

string
Optional

Specifies the destination for overdraft funds.

This field does not apply if JIT Funding is enabled.

Allowable Values:

GPA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value: GPA

The config.jit_funding object

Fields Description

programgateway_funding_source

object
Optional

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

program_funding_source

object
Optional

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

The config.jit_funding.programgateway_funding_source object

Fields Description

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

funding_source_token

string
Optional

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

Allowable Values:

Existing funding source token

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

The config.jit_funding.program_funding_source object

Fields Description

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

funding_source_token

string
Optional

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

Allowable Values:

Existing funding source token

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

The config.digital_wallet_tokenization object

Fields Description

provisioning_controls

object
Optional

Controls the provisioning of digital wallets.

Allowable Values:

The config.digital_wallet_tokenization.provisioning_controls object

Fields Description

manual_entry

boolean
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:

wallet_provider_card_on_file

boolean
Optional

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

Allowable Values:

in_app_provisioning

boolean
Optional

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

Allowable Values:

The config.digital_wallet_tokenization.provisioning_controls.manual_entry, wallet_provider_card_on_file and in_app_provisioning objects

Fields Description

enabled

boolean
Optional

A value of true enables the type of provisioning controlled by the setting.

Allowable Values:

true, false

Default value: false

address_verification.validate

boolean
Optional

Set to true to enable the address verification system (AVS) for provisioning.

Allowable Values:

true, false

Default value: true

Sample request body

{
    "active": false
}

Is this helpful?

Sample response body

{
  "token": "my_cardproduct_01",
  "name": "My Card Product 01",
  "active": false,
  "config": {
    "poi": {
      "other": {
        "allow": true,
        "card_presence_required": false,
        "cardholder_presence_required": false
      },
      "ecommerce": false,
      "atm": false
    },
    "transaction_controls": {
      "accepted_countries_token": "accept_us_only",
      "always_require_pin": false,
      "always_require_icc": false,
      "allow_gpa_auth": true,
      "require_card_not_present_card_security_code": false,
      "allow_mcc_group_authorization_controls": true,
      "allow_first_pin_set_via_financial_transaction": true,
      "ignore_card_suspended_state": false,
      "allow_network_load": false,
      "allow_network_load_card_activation": false,
      "allow_quasi_cash": false,
      "enable_partial_auth_approval": true,
      "address_verification": {
        "av_messages": {
          "validate": true,
          "decline_on_address_number_mismatch": false,
          "decline_on_postal_code_mismatch": true
        },
        "auth_messages": {
          "validate": true,
          "decline_on_address_number_mismatch": false,
          "decline_on_postal_code_mismatch": false
        }
      }
    },
    "fulfillment": {
      "shipping": {
        "method": "FEDEX_EXPEDITED",
        "return_address": {
          "first_name": "Saki",
          "middle_name": "R",
          "last_name": "Dogger",
          "address1": "123 Henry St",
          "address2": "Suite 101",
          "city": "Porterville",
          "state": "CA",
          "postal_code": "93257",
          "country": "USA",
          "phone": "8315555555"
        },
        "recipient_address": {
          "first_name": "Big",
          "last_name": "Bird",
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "3451239876"
        }
      },
      "payment_instrument": "PHYSICAL_MSR",
      "package_id": "0",
      "all_zero_card_security_code": false,
      "bin_prefix": "111111",
      "bulk_ship": false,
      "pan_length": "16",
      "fulfillment_provider": "PERFECTPLASTIC",
      "allow_card_creation": true,
      "uppercase_name_lines": true
    },
    "selective_auth": {
      "sa_mode": 1,
      "enable_regex_search_chain": false,
      "dmd_location_sensitivity": 0
    },
    "special": {
      "merchant_on_boarding": false
    },
    "card_life_cycle": {
      "activate_upon_issue": true,
      "expiration_offset": {
        "unit": "YEARS",
        "value": 10,
        "min_offset": {
          "unit": "YEARS",
          "value": 4
        }
      },
      "card_service_code": 101,
      "update_expiration_upon_activation": false
    },
    "clearing_and_settlement": {
      "overdraft_destination": "GPA"
    },
    "jit_funding": {
      "paymentcard_funding_source": {
        "enabled": true,
        "refunds_destination": ""
      },
      "programgateway_funding_source": {
        "enabled": false,
        "funding_source_token": "",
        "refunds_destination": ""
      },
      "program_funding_source": {
        "enabled": false,
        "funding_source_token": "",
        "refunds_destination": ""
      }
    },
    "digital_wallet_tokenization": {
      "provisioning_controls": {
        "manual_entry": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        },
        "wallet_provider_card_on_file": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        },
        "in_app_provisioning": {
          "enabled": false,
          "address_verification": {
            "validate": true
          }
        }
      }
    }
  },
  "start_date": "2017-04-27",
  "created_time": "2017-04-27T19:25:55Z",
  "last_modified_time": "2017-04-27T21:28:37Z"
}
{
    "api": "cardproducts",
    "endpoint": "/cardproducts/{token}",
    "method": "put",
    "cp_id": 1,
    "bc_id": 1
}

Is this helpful?

List card products

Action: GET
Endpoint: /cardproducts

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list existing card products.

This endpoint supports pagination.

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "token": "my_cardproduct_01",
      "name": "My Card Product 01",
      "active": true,
      "config": {
        "poi": {
          "other": {
            "allow": true,
            "card_presence_required": false,
            "cardholder_presence_required": false
          },
          "ecommerce": false,
          "atm": false
        },
        "transaction_controls": {
          "accepted_countries_token": "accept_us_only",
          "always_require_pin": false,
          "always_require_icc": false,
          "allow_gpa_auth": true,
          "require_card_not_present_card_security_code": false,
          "allow_mcc_group_authorization_controls": true,
          "allow_first_pin_set_via_financial_transaction": true,
          "ignore_card_suspended_state": false,
          "allow_network_load": false,
          "allow_network_load_card_activation": false,
          "allow_quasi_cash": false,
          "enable_partial_auth_approval": true,
          "address_verification": {
            "av_messages": {
              "validate": true,
              "decline_on_address_number_mismatch": false,
              "decline_on_postal_code_mismatch": true
            },
            "auth_messages": {
              "validate": true,
              "decline_on_address_number_mismatch": false,
              "decline_on_postal_code_mismatch": false
            }
          }
        },
        "fulfillment": {
          "shipping": {
            "method": "FEDEX_EXPEDITED",
            "return_address": {
              "first_name": "Saki",
              "middle_name": "R",
              "last_name": "Dogger",
              "address1": "123 Henry St",
              "address2": "Suite 101",
              "city": "Porterville",
              "state": "CA",
              "postal_code": "93257",
              "country": "USA",
              "phone": "8315555555"
            },
            "recipient_address": {
              "first_name": "Big",
              "last_name": "Bird",
              "address1": "1000 Pacific Ave",
              "city": "Santa Lucia",
              "state": "WA",
              "postal_code": "00112",
              "country": "USA",
              "phone": "3451239876"
            }
          },
          "payment_instrument": "PHYSICAL_MSR",
          "package_id": "0",
          "all_zero_card_security_code": false,
          "bin_prefix": "111111",
          "bulk_ship": false,
          "pan_length": "16",
          "fulfillment_provider": "PERFECTPLASTIC",
          "allow_card_creation": true,
          "uppercase_name_lines": true
        },
        "selective_auth": {
          "sa_mode": 1,
          "enable_regex_search_chain": false,
          "dmd_location_sensitivity": 0
        },
        "special": {
          "merchant_on_boarding": false
        },
        "card_life_cycle": {
          "activate_upon_issue": true,
          "expiration_offset": {
            "unit": "YEARS",
            "value": 10,
            "min_offset": {
              "unit": "YEARS",
              "value": 4
            }
          },
          "card_service_code": 101,
          "update_expiration_upon_activation": false
        },
        "clearing_and_settlement": {
          "overdraft_destination": "GPA"
        },
        "jit_funding": {
          "paymentcard_funding_source": {
            "enabled": true,
            "refunds_destination": ""
          },
          "programgateway_funding_source": {
            "enabled": false,
            "funding_source_token": "",
            "refunds_destination": ""
          },
          "program_funding_source": {
            "enabled": false,
            "funding_source_token": "",
            "refunds_destination": ""
          }
        },
        "digital_wallet_tokenization": {
          "provisioning_controls": {
            "manual_entry": {
              "enabled": false,
              "address_verification": {
                "validate": true
              }
            },
            "wallet_provider_card_on_file": {
              "enabled": false,
              "address_verification": {
                "validate": true
              }
            },
            "in_app_provisioning": {
              "enabled": false,
              "address_verification": {
                "validate": true
              }
            }
          }
        }
      },
      "start_date": "2017-04-27",
      "created_time": "2017-04-27T19:25:55Z",
      "last_modified_time": "2017-04-27T21:29:12Z"
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.