Create Card Product

Action: POST
Endpoint: /cardproducts

To create a card product, send a POST request to the /cardproducts endpoint and include the card product details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

The cardproduct request comprises a set of fields that provide basic information about the cardproduct, 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 cardproduct. The elements are referred to as the cardproduct "configuration," and as such are contained in a "config" object.

Body Field Details (basic information)

Name Type Required? Description Allowable Values
token string No 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.
36 char max
name string Yes The name of the card product. We recommend using a unique string. 40 char max
active boolean No 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.
true | false

Default: true
start_date string Yes 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. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z
end_date string No The end date of the range over which the card product can be active. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z
config object No Defines the characteristics of the card product. Configurations are conditionally required based on program setup.

config

Name Type Required? Description
poi object No Governs the point of interaction.
transaction_controls object No Controls transactional characteristics of card usage.
fulfillment object No Determines physical characteristics of a card and bulk shipment information.
special object No Contains information about merchant on-boarding.
selective_auth object No Contains information about authorization decisions.
card_life_cycle object No Defines characteristics of the lifecycle of cards of this cardproduct type.
clearing_and_settlement object No Determines whether a card of this cardproduct type can participate in MFD transaction processing.
jit_funding object No Governs the behavior of just-in-time funding.
digital_wallet_tokenization object No Controls characteristics related to digital wallets.

config.poi

Name Type Required? Description Allowable Values
other object No Allows for configuration of points of interaction other than ecommerce or ATMs. This group includes point-of-sale (POS).
ecommerce boolean No True enables cards to be used for online purchases. true | false

Default: false
atm boolean No True enables cards to be used at ATMs. true | false

Default: false

config.poi.other

Name Type Required? Description Allowable Values
allow boolean No True indicates that card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes point-of-sale (POS). true | false

Default: true
card_presence_required boolean No True indicates that cards of this card product type are required to be present during the transaction, such as in IVR scenarios. true | false

Default: false
cardholder_presence_required boolean No 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. true | false

Default: false

config.transaction_controls

Name Type Required? Description Allowable Values
pre_auth_decline_invalid_zip boolean No Performs AVS at the point of pre-authorization and declines if the ZIP provided is invalid. true | false

Default: false
accepted_countries_token string No 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.
"accept_us_only" | "decline_ofac_countries";

Default: "accept_us_only"
always_require_pin boolean No True indicates that the cards of this cardproduct type require a PIN. true | false

Default: false
always_require_icc boolean No True indicates that the cards of this cardproduct type require an Integrated Circuit Card. true | false

Default: false
allow_gpa_auth boolean No 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.
true | false

Default: true
disable_avs boolean No True indicates that AVS address verification is not active. AVS is active by default. true | false

Default: false
require_card_not_present_card_security_code boolean No True indicates that if allow_card_not_present=true, the card's security code is required. true | false

Default: false
allow_mcc_group_authorization_controls boolean No MCC Group Authorization Controls allow partners to increase authorization holds (percentage or amount) based on merchant type.

For example, a partner can configure an automatic 15% hold on restaurant purchases. This guarantees that the purchase amount plus 15% is available at the time of swipe, or else the transaction will be declined.

Note: Partial authorizations are disallowed if this field is set to true.
true | false

Default: false
allow_first_pin_set_via_financial_transaction boolean No Allows cardholders to define a PIN as they complete their first PIN-debit transaction. true | false

Default: false
ignore_card_suspended_state boolean No Allows transactions to be approved even if the card state=SUSPENDED. When this field is set to true, the card behaves as if its state=ACTIVE. true | false

Default: false
allow_network_load boolean No Indicates whether network loads are allowed. The associated card's state must be ACTIVE or the load will be rejected. true | false

Default: false
allow_network_load_card_activation boolean No Indicates whether network loads are allowed. Sets the associated card's state to ACTIVE if its current state is INACTIVE. true | false

Default: false
allow_quasi_cash boolean No Indicates whether transactions involving quasi cash are allowed. true | false

Default: false
enable_partial_auth_approval boolean No 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.
true | false

Default: false

config.fulfillment

Name Type Required? Description Allowable Values
fulfillment_provider string No Specifies the fulfillment provider. PERFECTPLASTIC | ARROWEYE

Default: PERFECTPLASTIC
shipping object No Specifies the shipping details for cards of this cardproduct type. shipping object
bin_prefix string No The prefix of the bank identification number. Default: 111111

Note: In a sandbox environment, this field must be set to 111111.
payment_instrument string No Specifies the physical form cards of this cardproduct type will take. PHYSICAL_MSR | PHYSICAL_ICC | PHYSICAL_CONTACTLESS | PHYSICAL_COMBO | VIRTUAL_PAN

Default: PHYSICAL_MSR
package_id string No Card fulfillment provider's package ID. 50 char max
pan_length string No Specifies the length of the PAN. Default: 16
bulk_ship boolean No Enables bulk ordering of cards of this card product type using the /bulkissuances endpoint. true | false

Default: false
all_zero_card_security_code boolean No If true, an all zero code (000) is allowed as a valid value in an authorization request. true | false

Default: false
allow_card_creation boolean No 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.
true | false

Default: true

config.fulfillment.shipping

Name Type Required? Description Allowable Values
return_address object No Address to which cards will be returned if shipping fails.
recipient_address object No Address to which cards will be shipped.
method string No Specifies the shipping company and method. FEDEX_EXPEDITED | FEDEX_REGULAR | UPS_EXPEDITED | UPS_REGULAR | USPS_EXPEDITED | USPS_REGULAR
care_of_line string No 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.
255 char max

config.fulfillment.shipping.return_address & recipient_address

Name Type Required? Description Allowable Values
address1 string No Number and street. 50 char max
address2 string No Additional address information. 50 char max
city string No City. 50 char max
state string No State. 50 char max
zip string No ZIP code. 50 char max
country string No Country. 50 char max
phone string No Telephone number. 50 char max
first_name string No First Name. 50 char max
middle_name string No Middle Name. 50 char max
last_name string No Last Name. 50 char max

config.selective_auth

Name Type Required? Description Allowable Values
sa_mode integer No 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.
0 | 1 | 2

Default: 1
enable_regex_search_chain boolean No Use true to perform regular expression checking on the description received in the authorization. true | false

Default: false
dmd_location_sensitivity integer No 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 zip 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 zip.

4 - Partial match on CA name; exact match on street address 1 and zip.
0 | 1 | 2 | 3 | 4

Default: 0

config.special

Name Type Required? Description Allowable Values
merchant_on_boarding boolean No True indicates cards of this card product type can be used for merchant onboarding. true | false

Default: false

config.card_life_cycle

Name Type Required? Description Allowable Values
activate_upon_issue boolean No True indicates that cards of the card product type are active once they are issued. true | false

Default: false
expiration_offset object No Specifies the length of time for which cards of this cardproduct type are valid. In other words, the card expires this length of time after the date of issue.
card_service_code integer No 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
100 - 999

Default: 101
update_expiration_upon_activation boolean No 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. true | false

Default: false

config.card_life_cycle.expiration_offset

Name Type Required? Description Allowable Values
unit string No Specifies the units for the value field. YEARS | MONTHS | DAYS | HOURS | MINUTES | SECONDS

Default: YEARS
value integer No Specifies the number of time units (as defined by the unit field) for which cards of this cardproduct type are valid. In other words, the card expires this length of time 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 Feb 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.
Any positive integer

Default: 4

config.clearing_and_settlement

Name Type Required? Description Allowable Values
mfd_capable boolean No True indicates that cards of this cardproduct configuration can be used with MFD processing of transactions. true | false

Default: true
overdraft_destination string No Specifies the destination for overdraft funds.

This field does not apply if JIT funding is enabled.
GPA | MSA | MERCHANT_CAMPAIGN_ACCOUNT | GLOBAL_OVERDRAFT_ACCOUNT

Default: GPA

config.jit_funding

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.

config.jit_funding.programgateway_funding_source

Name Type Required? Description Allowable Values
enabled boolean No Specifies whether just-in-time 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. true | false

Default: false
funding_source_token string No The unique identifier of the already existing funding source. Required if just-in-time funding is enabled. Existing funding source token
refunds_destination string No 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. GATEWAY | GPA

config.jit_funding.program_funding_source

Name Type Required? Description Allowable Values
enabled boolean No Specifies whether just-in-time 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. true | false

Default: false
funding_source_token string No The unique identifier of the already existing funding source. Required if just-in-time funding is enabled. Existing funding source token
refunds_destination string No 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. PROGRAM_FUNDING_SOURCE | GPA

config.digital_wallet_tokenization

Name Type Required? Description Allowable Values
provisioning_controls object No Controls the provisioning of digital wallets.

config.digital_wallet_tokenization.provisioning_controls

Name Type Required? Description Allowable Values
manual_entry boolean No Controls the provisioning of digital wallets by manual entry, in which the card holder manually enters the card's PAN, CVV, and expiration date.
wallet_provider_card_on_file boolean No Controls the provisioning of digital wallets where the digital wallet provider already has the card on file.
in_app_provisioning boolean No Controls the provisioning of digital wallets by a Marqeta customer's mobile application.

config.digital_wallet_tokenization.provisioning_controls.manual_entry, wallet_provider_card_on_file, & in_app_provisioning

Name Type Required? Description Allowable Values
enabled boolean No A value of "true" enables the type of provisioning controlled by the setting. true | false

Default: false
disable_avs boolean No A value of "true" disables the address verification system (AVS) for provisioning. true | false

Default: false

Sample Request Body

{
"name": "Purple Card",
"token": "purple_cardproduct",
"start_date": "2016-04-19",
"config": {
"poi" : {
"ecommerce" : false,
"atm" : false,
"other": {
"allow": true,
"card_presence_required": false,
"cardholder_presence_required": false
}
},
"transaction_controls" : {
"pre_auth_decline_invalid_zip": false,
"accepted_countries_token": "accept_us_only",
"always_require_pin": false,
"always_require_icc": false,
"allow_gpa_auth": false,
"disable_avs": false,
"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",
"zip": "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",
"zip": "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" : false,
"expiration_offset": {
"unit": "YEARS",
"value": 10
},
"card_service_code" : 101,
"update_expiration_upon_activation": false
},
"clearing_and_settlement": {
"mfd_capable": true
},
"jit_funding": {
"paymentcard_funding_source": {
"enabled": true
}
}
}
}

Sample Response Body

{
"token": "purple_cardproduct",
"name": "Purple Card",
"active": true,
"config": {
"poi": {
"other": {
"allow": true,
"card_presence_required": false,
"cardholder_presence_required": false
},
"ecommerce": false,
"atm": false
},
"special": {
"merchant_on_boarding": false
},
"transaction_controls": {
"pre_auth_decline_invalid_zip": false,
"accepted_countries_token": "accept_us_only",
"always_require_pin": false,
"always_require_icc": false,
"allow_gpa_auth": false,
"disable_avs": false,
"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": {
"method": "FEDEX_EXPEDITED",
"return_address": {
"address1": "123 Henry St",
"address2": "Suite 101",
"city": "Porterville",
"state": "CA",
"zip": "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",
"zip": "00112",
"country": "USA",
"phone": "345-123-9876",
"first_name": "Big",
"last_name": "Bird"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": ""
}
}
},
"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": false,
"expiration_offset": {
"unit": "YEARS",
"value": 10
},
"card_service_code": 101,
"update_expiration_upon_activation": false
},
"clearing_and_settlement": {
"mfd_capable": true,
"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": ""
}
}
},
"start_date": "2016-04-19",
"created_time": "2016-08-01T17:37:20Z",
"last_modified_time": "2016-08-01T17:37:20Z"
}


Retrieve Card Product

Action: GET
Endpoint: /cardproducts/{token}

To retrieve a specific card product, issue a GET request to the /cardproducts/{token} endpoint and include the token path parameter to specify the card product to return.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the card product to retrieve. Existing card product token.

Issue a GET to /cardproducts to retrieve existing card product tokens.

Sample Response Body

{
"token": "purple_cardproduct",
"name": "Purple Card",
"active": true,
"config": {
"poi": {
"other": {
"allow": true,
"card_presence_required": false,
"cardholder_presence_required": false
},
"ecommerce": false,
"atm": false
},
"special": {
"merchant_on_boarding": false
},
"transaction_controls": {
"pre_auth_decline_invalid_zip": false,
"accepted_countries_token": "accept_us_only",
"always_require_pin": false,
"always_require_icc": false,
"allow_gpa_auth": false,
"disable_avs": false,
"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": {
"method": "FEDEX_EXPEDITED",
"return_address": {
"address1": "123 Henry St",
"address2": "Suite 101",
"city": "Porterville",
"state": "CA",
"zip": "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",
"zip": "00112",
"country": "USA",
"phone": "345-123-9876",
"first_name": "Big",
"last_name": "Bird"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": ""
}
}
},
"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": false,
"expiration_offset": {
"unit": "YEARS",
"value": 10
},
"card_service_code": 101,
"update_expiration_upon_activation": false
},
"clearing_and_settlement": {
"mfd_capable": true,
"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": ""
}
}
},
"start_date": "2016-04-19",
"created_time": "2016-08-01T17:37:20Z",
"last_modified_time": "2016-08-01T17:37:20Z"
}


Update Card Product

Action: PUT
Endpoint: /cardproducts/{token}

To update a card product, issue a PUT request to the /cardproducts/{token} endpoint. Include the card product token as a path parameter to indicate the card product to update. Include the modified or additional card product details in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes The token identifying the card product to update. Existing card product token.

Issue a GET to /cardproducts to retrieve existing card product tokens.

Body Field Details (basic information)

Name Type Required? Description Allowable Values
name string Yes The name of the card product. We recommend using a unique string. 40 char max
active boolean No 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.
true | false

Default: true
start_date string Yes 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. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z
end_date string No The end date of the range over which the card product can be active. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z
config object No Defines the characteristics of the card product. Configurations are conditionally required based on program setup. Config object

config

Name Type Required? Description
poi object No Governs the point of interaction.
transaction_controls object No Controls transactional characteristics of card usage.
fulfillment object No Determines physical characteristics of a card and bulk shipment information.
special object No Contains information about merchant on-boarding.
selective_auth object No Contains information about authorization decisions.
card_life_cycle object No Defines characteristics of the lifecycle of cards of this cardproduct type.
clearing_and_settlement object No Determines whether a card of this cardproduct type can participate in MFD transaction processing.
jit_funding object No Governs the behavior of just-in-time funding.
digital_wallet_tokenization object No Controls characteristics related to digital wallets.

config.poi

Name Type Required? Description Allowable Values
other object No Allows for configuration of points of interaction other than ecommerce or ATMs. This group includes point-of-sale (POS).
ecommerce boolean No True enables cards to be used for online purchases. true | false

Default: false
atm boolean No True enables cards to be used at ATMs. true | false

Default: false

config.poi.other

Name Type Required? Description Allowable Values
allow boolean No True indicates that card transactions at points of interaction other than ecommerce or ATMs are allowed. This group includes point-of-sale (POS). true | false

Default: true
card_presence_required boolean No True indicates that cards of this card product type are required to be present during the transaction, such as in IVR scenarios. true | false

Default: false
cardholder_presence_required boolean No 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. true | false

Default: false

config.transaction_controls

Name Type Required? Description Allowable Values
pre_auth_decline_invalid_zip boolean No Performs AVS at the point of pre-authorization and declines if the ZIP provided is invalid. true | false

Default: false
accepted_countries_token string No 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.
"accept_us_only" | "decline_ofac_countries";

Default: "accept_us_only"
always_require_pin boolean No True indicates that the cards of this cardproduct type require a PIN. true | false

Default: false
always_require_icc boolean No True indicates that the cards of this cardproduct type require an Integrated Circuit Card. true | false

Default: false
allow_gpa_auth boolean No 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.
true | false

Default: true
disable_avs boolean No True indicates that AVS address verification is not active. AVS is active by default. true | false

Default: false
require_card_not_present_card_security_code boolean No True indicates that if allow_card_not_present=true, the card's security code is required. true | false

Default: false
allow_mcc_group_authorization_controls boolean No MCC Group Authorization Controls allow partners to increase authorization holds (percentage or amount) based on merchant type. For example, a partner can configure an automatic 15% hold on restaurant purchases. This guarantees that the purchase amount plus 15% is available at the time of swipe, or else the transaction will be declined. Note: Partial authorizations are disallowed if this field is set to true. true | false

Default: false
allow_first_pin_set_via_financial_transaction boolean No Allows cardholders to define a PIN as they complete their first PIN-debit transaction. true | false

Default: false
ignore_card_suspended_state boolean No Allows transactions to be approved even if the card state=SUSPENDED. When this field is set to true, the card behaves as if its state=ACTIVE. true | false

Default: false
allow_network_load boolean No Indicates whether network loads are allowed. The associated card's state must be ACTIVE or the load will be rejected. true | false

Default: false
allow_network_load_card_activation boolean No Indicates whether network loads are allowed. Sets the associated card's state to ACTIVE if its current state is INACTIVE. true | false

Default: false
allow_quasi_cash boolean No Indicates whether transactions involving quasi cash are allowed. true | false

Default: false
enable_partial_auth_approval boolean No 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.
true | false

Default: false

config.fulfillment

Name Type Required? Description Allowable Values
fulfillment_provider string No Specifies the fulfillment provider. PERFECTPLASTIC | ARROWEYE

Default: PERFECTPLASTIC
shipping object No Specifies the shipping details for cards of this cardproduct type. shipping object
bin_prefix string No The prefix of the bank identification number. Default: 1111111

Note: In a sandbox environment or when testing against Swagger, this field must be set to 111111.
payment_instrument string No Specifies the physical form cards of this cardproduct type will take. PHYSICAL_MSR | PHYSICAL_ICC | PHYSICAL_CONTACTLESS | PHYSICAL_COMBO | VIRTUAL_PAN

Default: PHYSICAL_MSR
package_id string No Card fulfillment provider's package ID. 50 char max
pan_length string No Specifies the length of the PAN. Default: 16
bulk_ship boolean No Enables bulk ordering of cards of this card product type using the /bulkissuances endpoint. true | false

Default: false
all_zero_card_security_code boolean No If true, an all zero code (000) is allowed as a valid value in an authorization request. true | false

Default: false
allow_card_creation boolean No 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.
true | false

Default: true

config.fulfillment.shipping

Name Type Required? Description Allowable Values
return_address object No Address to which cards will be returned if shipping fails.
recipient_address object No Address to which cards will be shipped.
method string No Specifies the shipping company and method FEDEX_EXPEDITED | FEDEX_REGULAR | UPS_EXPEDITED | UPS_REGULAR | USPS_EXPEDITED | USPS_REGULAR
care_of_line string No 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.
255 char max

config.fulfillment.shipping.return_address & recipient_address

Name Type Required? Description Allowable Values
address1 string No Number and street. 50 char max
address2 string No Additional address information. 50 char max
city string No City. 50 char max
state string No State. 50 char max
zip string No ZIP code. 50 char max
country string No Country. 50 char max
phone string No Telephone number. 50 char max
first_name string No First Name. 50 char max
middle_name string No Middle Name. 50 char max
last_name string No Last Name. 50 char max

config.selective_auth

Name Type Required? Description Allowable Values
sa_mode integer No 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.
0 | 1 | 2

Default: 1
enable_regex_search_chain boolean No Use true to perform regular expression checking on the description received in the authorization. true | false

Default: false
dmd_location_sensitivity integer No 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 zip 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 zip.

4 - Partial match on CA name, exact match on street address 1 and zip.
0 | 1 | 2 | 3 | 4

Default: 0

config.special

Name Type Required? Description Allowable Values
merchant_on_boarding boolean No True indicates cards of this card product type can be used for merchant onboarding. true | false

Default: false

config.card_life_cycle

Name Type Required? Description Allowable Values
activate_upon_issue boolean No True indicates that cards of the card product type are active once they are issued. true | false

Default: false
expiration_offset object No Specifies the length of time for which cards of this cardproduct type are valid. In other words, the card expires this length of time after the date of issue.
card_service_code integer No 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
100 - 999

Default: 101
update_expiration_upon_activation boolean No 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. true | false

Default: false

config.card_life_cycle.expiration_offset

Name Type Required? Description Allowable Values
unit string No Specifies the units for the value field. YEARS | MONTHS | DAYS | HOURS | MINUTES | SECONDS

Default: YEARS
value integer No Specifies the number of time units (as defined by the unit field) for which cards of this cardproduct type are valid. In other words, the card expires this length of time 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 Feb 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.
Any positive integer

Default: 4

config.clearing_and_settlement

Name Type Required? Description Allowable Values
mfd_capable boolean No True indicates that cards of this cardproduct configuration can be used with MFD processing of transactions. true | false

Default: true
overdraft_destination string No Specifies the destination for overdraft funds.

This field does not apply if JIT funding is enabled.
GPA | MSA | MERCHANT_CAMPAIGN_ACCOUNT | GLOBAL_OVERDRAFT_ACCOUNT

Default: GPA

config.jit_funding

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.

config.jit_funding.programgateway_funding_source

Name Type Required? Description Allowable Values
enabled boolean No Specifies whether just-in-time 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. true | false

Default: false
funding_source_token string No The unique identifier of the already existing funding source. Required if just-in-time funding is enabled. Existing funding source token
refunds_destination string No 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. GATEWAY | GPA

config.jit_funding.program_funding_source

Name Type Required? Description Allowable Values
enabled boolean No Specifies whether just-in-time 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. true | false

Default: false
funding_source_token string No The unique identifier of the already existing funding source. Required if just-in-time funding is enabled. Existing funding source token
refunds_destination string No 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. PROGRAM_FUNDING_SOURCE | GPA

config.digital_wallet_tokenization

Name Type Required? Description Allowable Values
provisioning_controls object No Controls the provisioning of digital wallets.

config.digital_wallet_tokenization.provisioning_controls

Name Type Required? Description Allowable Values
manual_entry boolean No Controls the provisioning of digital wallets by manual entry, in which the card holder manually enters the card's PAN, CVV, and expiration date.
wallet_provider_card_on_file boolean No Controls the provisioning of digital wallets where the digital wallet provider already has the card on file.
in_app_provisioning boolean No Controls the provisioning of digital wallets by a Marqeta customer's mobile application.

config.digital_wallet_tokenization.provisioning_controls.manual_entry, wallet_provider_card_on_file, & in_app_provisioning

Name Type Required? Description Allowable Values
enabled boolean No A value of "true" enables the type of provisioning controlled by the setting. true | false

Default: false
disable_avs boolean No A value of "true" disables the address verification system (AVS) for provisioning. true | false

Default: false

Sample Request Body

{
"config":{
"fulfillment":{
"pan_length": "10"
}
}
}

Sample Response Body

{
"token": "purple_cardproduct",
"name": "Purple Card",
"active": true,
"config": {
"poi": {
"other": {
"allow": true,
"card_presence_required": false,
"cardholder_presence_required": false
},
"ecommerce": false,
"atm": false
},
"special": {
"merchant_on_boarding": false
},
"transaction_controls": {
"pre_auth_decline_invalid_zip": false,
"accepted_countries_token": "accept_us_only",
"always_require_pin": false,
"always_require_icc": false,
"allow_gpa_auth": false,
"disable_avs": false,
"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": {
"method": "FEDEX_EXPEDITED",
"return_address": {
"address1": "123 Henry St",
"address2": "Suite 101",
"city": "Porterville",
"state": "CA",
"zip": "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",
"zip": "00112",
"country": "USA",
"phone": "345-123-9876",
"first_name": "Big",
"last_name": "Bird"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": ""
}
}
},
"payment_instrument": "PHYSICAL_MSR",
"package_id": "0",
"all_zero_card_security_code": false,
"bin_prefix": "111111",
"bulk_ship": false,
"pan_length": "10",
"fulfillment_provider": "PERFECTPLASTIC"
},
"selective_auth": {
"sa_mode": 1,
"enable_regex_search_chain": false,
"dmd_location_sensitivity": 0
},
"card_life_cycle": {
"activate_upon_issue": false,
"expiration_offset": {
"unit": "YEARS",
"value": 10
},
"card_service_code": 101,
"update_expiration_upon_activation": false
},
"clearing_and_settlement": {
"mfd_capable": true,
"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": ""
}
}
},
"start_date": "2016-04-19",
"created_time": "2016-04-19T22:48:06Z",
"last_modified_time": "2016-04-19T23:25:01Z"
}


List Card Products

Action: GET
Endpoint: /cardproducts

To list existing card products, issue a GET request to the /cardproducts endpoint.

This endpoint supports pagination.

Sample Response Body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "purple_cardproduct",
"name": "Purple Card",
"active": true,
"config": {
"poi": {
"other": {
"allow": true,
"card_presence_required": false,
"cardholder_presence_required": false
},
"ecommerce": false,
"atm": false
},
"special": {
"merchant_on_boarding": false
},
"transaction_controls": {
"pre_auth_decline_invalid_zip": false,
"accepted_countries_token": "accept_us_only",
"always_require_pin": false,
"always_require_icc": false,
"allow_gpa_auth": false,
"disable_avs": false,
"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": {
"method": "FEDEX_EXPEDITED",
"return_address": {
"address1": "123 Henry St",
"address2": "Suite 101",
"city": "Porterville",
"state": "CA",
"zip": "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",
"zip": "00112",
"country": "USA",
"phone": "345-123-9876",
"first_name": "Big",
"last_name": "Bird"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": ""
}
}
},
"payment_instrument": "PHYSICAL_MSR",
"package_id": "0",
"all_zero_card_security_code": false,
"bin_prefix": "111111",
"bulk_ship": false,
"pan_length": "10",
"fulfillment_provider": "PERFECTPLASTIC"
},
"selective_auth": {
"sa_mode": 1,
"enable_regex_search_chain": false,
"dmd_location_sensitivity": 0
},
"card_life_cycle": {
"activate_upon_issue": false,
"expiration_offset": {
"unit": "YEARS",
"value": 10
},
"card_service_code": 101,
"update_expiration_upon_activation": false
},
"clearing_and_settlement": {
"mfd_capable": true,
"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": ""
}
}
},
"start_date": "2016-04-19",
"created_time": "2016-04-19T22:48:06Z",
"last_modified_time": "2016-04-19T23:25:01Z"
}
]
}