DOCS

New!

/

55 minute read

November 2, 2019

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 necessary for use 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, optional

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

Allowable Values:

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 cardproduct 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

True enables cards to be used for online purchases.

Allowable Values:

true, false

Default value: false

atm

boolean, optional

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

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

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

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.

Allowable Values:

"accept_us_only", "decline_ofac_countries";

Default value: "accept_us_only"

always_require_pin

boolean, optional

True indicates that the cards of this cardproduct type require a PIN.

Allowable Values:

true, false

Default value: false

always_require_icc

boolean, optional

True indicates that the cards of this cardproduct type require an Integrated Circuit Card.

Allowable Values:

true, false

Default value: false

allow_gpa_auth

boolean, optional

True allows transactions to be authorized using GPA funds. If transactions will be funded by way of MSA Orders or Offer Orders, you can set this field to false and disallow funding by way of the GPA.

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 cardproduct type.

Allowable Values:

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

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

The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

name_line_2.value

string, optional

Second line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 21 characters. 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

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

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 cardproduct 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 cardproduct 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 2015 and value=1, the card expires on the last day of Jan 2016.

  • 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 2015 and value=1, the card expires on the last day of Feb 2015.

  • 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 cardproduct 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 2015 and value=1, the card expires on the last day of Jan 2016.

  • 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 2015 and value=1, the card expires on the last day of Feb 2015.

  • 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, MSA, MERCHANT_CAMPAIGN_ACCOUNT, GLOBAL_OVERDRAFT_ACCOUNT

Default value: GPA

The config.jit_funding object

Name Type Required? Description

programgateway_funding_source

object

No

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

program_funding_source

object

No

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. 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. 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": "831-555-5555",
          "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": "345-123-9876",
          "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": "831-555-5555"
        },
        "recipient_address": {
          "first_name": "Big",
          "last_name": "Bird",
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "345-123-9876"
        }
      },
      "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": "831-555-5555"
        },
        "recipient_address": {
          "first_name": "Big",
          "last_name": "Bird",
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "345-123-9876"
        }
      },
      "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, optional

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

Allowable Values:

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 cardproduct 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

True enables cards to be used for online purchases.

Allowable Values:

true, false

Default value: false

atm

boolean, optional

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

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

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

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.

Allowable Values:

"accept_us_only", "decline_ofac_countries";

Default value: "accept_us_only"

always_require_pin

boolean, optional

True indicates that the cards of this cardproduct type require a PIN.

Allowable Values:

true, false

Default value: false

always_require_icc

boolean, optional

True indicates that the cards of this cardproduct type require an Integrated Circuit Card.

Allowable Values:

true, false

Default value: false

allow_gpa_auth

boolean, optional

True allows transactions to be authorized using GPA funds. If transactions will be funded by way of MSA Orders or Offer Orders, you can set this field to false and disallow funding by way of the GPA.

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 cardproduct type.

Allowable Values:

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

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

The card can accommodate only 21 characters. Strings longer than 21 characters are truncated.

name_line_2.value

string, optional

Second line of personalized text printed on the card.

Allowable Values:

The card can accommodate only 21 characters. 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

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

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 cardproduct 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 cardproduct 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 2015 and value=1, the card expires on the last day of Jan 2016.

  • 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 2015 and value=1, the card expires on the last day of Feb 2015.

  • 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 cardproduct 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 2015 and value=1, the card expires on the last day of Jan 2016.

  • 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 2015 and value=1, the card expires on the last day of Feb 2015.

  • 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, MSA, 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. 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. 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": "831-555-5555"
        },
        "recipient_address": {
          "first_name": "Big",
          "last_name": "Bird",
          "address1": "1000 Pacific Ave",
          "city": "Santa Lucia",
          "state": "WA",
          "postal_code": "00112",
          "country": "USA",
          "phone": "345-123-9876"
        }
      },
      "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": "831-555-5555"
            },
            "recipient_address": {
              "first_name": "Big",
              "last_name": "Bird",
              "address1": "1000 Pacific Ave",
              "city": "Santa Lucia",
              "state": "WA",
              "postal_code": "00112",
              "country": "USA",
              "phone": "345-123-9876"
            }
          },
          "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.