DOCS

New!

/

10 minute read

January 1, 2020

Managing Physical Cards

The Marqeta platform enables you to issue physical cards individually or in bulk. This guide provides an overview of the available card fulfillment options, including best practices for each card fulfillment type.

At the end of this guide, you should understand:

  • How to issue physical cards, individually or in bulk.

  • Best practices for issuing physical cards.

  • How the card ordering process works for each fulfillment provider.

  • How to track and understand the status of your physical card orders.

For an overview of payment cards on the Marqeta platform, see About Cards.

For information about the /cards resource in the Marqeta Core API, see Cards.

About card fulfillment types

There are four types of physical card fulfillment: full-service mail, full-service bulk, dynamic bulk, and generic bulk. The following sections describe each fulfillment type.

Full-service mail

Full-service mail card fulfillment is appropriate for individual cardholders. Cardholders receive their own personalized cards in the mail at the addresses associated with their user accounts. Full-service mail is the default card fulfillment type for most card programs.

Full-service bulk

Full-service bulk card fulfillment is appropriate when your business is the cardholder, and cards are distributed to your authorized users. Cards are shipped in individually identified envelopes to a single address, such as your business address, and you distribute them to your authorized users. Cards and envelopes are identified with the authorized user’s name.

Bulk

Bulk card fulfillment supports two variants: generic bulk card fulfillment and dynamic bulk card fulfillment. The following sections describe each type.

Generic

Generic bulk card fulfillment is appropriate when you want to have cards in stock to distribute to your authorized users. Cards are shipped in bulk boxes without individual envelopes. Rather than an individual’s name, cards are printed or embossed with a static prefix followed by a serial enumeration, such as “Driver 01,” “Driver 02,” and so on.

See Configuring generic bulk card fulfillment for more information.

Dynamic

Dynamic bulk card fulfillment enables you to create a standing bulk card order to which you can add individual cards on an ongoing basis. Dynamic bulk card fulfillment is appropriate when you want to have more control over individual card details, such as assigning specific user tokens.

See Configuring dynamic bulk card fulfillment for more information.

Configuring full-service mail card fulfillment

To configure an individual card for full-service mail card fulfillment, follow these steps:

Step one — Create your card product

Create your card product as documented on the Card Products page, ensuring that you specify the following items:

  1. Specify your fulfillment provider in the fulfillment_provider field of the config.fulfillment object.

  2. Specify one of the physical card types in the payment_instrument field of the config.fulfillment object:

    • PHYSICAL_MSR: A physical card with a magnetic stripe. This is the default physical card type.

    • PHYSICAL_ICC: A physical card with an integrated circuit, or “chip.”

    • PHYSICAL_CONTACTLESS: A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.

    • PHYSICAL_COMBO: A physical card with a chip that also supports contactless payments.

  3. Specify the fulfillment package ID in the package_id field of the config.fulfillment object. The package ID identifies the design and artwork that you have on file with your fulfillment provider.

  4. Set the bulk_ship field of the config.fulfillment object to false.

  5. Enter your company’s return address in the return_address field of the config.fulfillment.shipping object.

Step two — Create your users

Create your users as documented on the Users page, ensuring that you specify each user’s shipping address. The following body fields are required:

  • first_name

  • last_name

  • address1

  • city

  • state (USA only)

  • postal_code

  • country

Step three — Create your cards

Create your cards as documented on the Cards page, ensuring that you specify the required user_token and fulfillment.card_personalization.text objects.

Optionally, you can also specify the card carrier design in the fulfillment.card_personalization.carrier object. The card carrier is the trifold paper to which the card is affixed for shipment.

Configuring full-service bulk card fulfillment

To configure cards for full-service bulk card fulfillment, follow these steps:

Step one — Create your card product

Create your card product as documented on the Card Products page, ensuring that you specify the following items:

  1. Specify your fulfillment provider in the fulfillment_provider field of the config.fulfillment object.

  2. Specify one of the physical card types in the payment_instrument field of the config.fulfillment object:

    • PHYSICAL_MSR: A physical card with a magnetic stripe. This is the default physical card type.

    • PHYSICAL_ICC: A physical card with an integrated circuit, or “chip.”

    • PHYSICAL_CONTACTLESS: A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.

    • PHYSICAL_COMBO: A physical card with a chip that also supports contactless payments.

  3. Specify the fulfillment package ID in the package_id field of the config.fulfillment object. The package ID identifies the design and artwork that you have on file with your fulfillment provider.

  4. Set the bulk_ship field of the config.fulfillment object to false.

  5. Enter your company’s return address in the return_address field of the config.fulfillment.shipping object.

Step two — Create your users

Create your users as documented on the Users page. Entering the user’s address is optional, unless your users require Know Your Customer (KYC) validation. Your fulfillment providers ships the cards to the bulk recipient address you specify in your bulk card order.

Step three — Create your bulk card order

Create your bulk card order as specified on the Bulk Card Orders page, ensuring that you specify your bulk shipping address in the fulfillment.shipping.recipient_address object. The following body fields are required:

  • first_name

  • last_name

  • address1

  • city

  • state (USA only)

  • postal_code

  • country

Optionally, you can also specify the card carrier design in the fulfillment.card_personalization.carrier object. The card carrier is the trifold paper to which the card is affixed for shipment.

Configuring generic bulk card fulfillment

For generic bulk card fulfillment, you configure a bulk order that creates generic users and cards. You can update the generic users with user-specific information, such as their name and address, after the bulk card order has been created.

To configure cards for generic bulk card fulfillment, follow these steps:

Step one — Create your card product

Create your card product as documented on the Card Products page, ensuring that you specify the following items:

  1. Specify your fulfillment provider in the fulfillment_provider field of the config.fulfillment object.

  2. Specify one of the physical card types in the payment_instrument field of the config.fulfillment object:

    • PHYSICAL_MSR: A physical card with a magnetic stripe. This is the default physical card type.

    • PHYSICAL_ICC: A physical card with an integrated circuit, or “chip.”

    • PHYSICAL_CONTACTLESS: A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.

    • PHYSICAL_COMBO: A physical card with a chip that also supports contactless payments.

  3. Specify the fulfillment package ID in the package_id field of the config.fulfillment object. The package ID identifies the design and artwork that you have on file with your fulfillment provider.

  4. Set the bulk_ship field of the config.fulfillment object to false.

  5. Enter your company’s return address in the return_address field of the config.fulfillment.shipping object.

Step two — Create your bulk card order

Create your bulk card order as specified on the Bulk Card Orders page, ensuring that you specify the following items:

  1. Specify your bulk shipping address in the fulfillment.shipping.recipient_address object. The following body fields are required:

    • first_name

    • last_name

    • address1

    • city

    • state (USA only)

    • postal_code

    • country

  2. Specify the number of cards allocated in the bulk card order in the card_allocation field. For example, to create 10 generic users and cards, enter 10 in the card_allocation field. The users are assigned user tokens serially: user-01, user-02, and so on.

  3. Include the user_association object with the single_inventory_user field set to false.

  4. Set the name_line_1_numeric_postfix field to true. This will append the serial numeric postfix to the fulfillment.card_personalization.text object’s name_line_1 field.

  5. In the fulfillment.card_personalization.text object, enter a generic name in the name_line_1 field. For example, enter Driver. This name will be printed on cards, followed by the serial numeric postfix: Driver 01, Driver 02, and so on.

Step three — Update your generic users

After you have created your bulk card order, you can enter individual user information for your generic cards by updating the relevant user as documented on the Users page. Use the PUT method to update a generic user, such as /users/{user-01}, with the relevant information, such as the user’s name and address.

Configuring dynamic bulk card fulfillment

For dynamic bulk card fulfillment, you create a bulk card order with an allocation of 0 as a placeholder, then create users and cards that you add to your bulk order dynamically.

To configure cards for dynamic bulk card fulfillment, follow these steps:

Step one — Create your card product

Create your card product as documented on the Card Products page, ensuring that you specify the following items:

  1. Specify your fulfillment provider in the fulfillment_provider field of the config.fulfillment object.

  2. Specify one of the physical card types in the payment_instrument field of the config.fulfillment object:

    • PHYSICAL_MSR: A physical card with a magnetic stripe. This is the default physical card type.

    • PHYSICAL_ICC: A physical card with an integrated circuit, or “chip.”

    • PHYSICAL_CONTACTLESS: A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.

    • PHYSICAL_COMBO: A physical card with a chip that also supports contactless payments.

  3. Specify the fulfillment package ID in the package_id field of the config.fulfillment object. The package ID identifies the design and artwork that you have on file with your fulfillment provider.

  4. Set the bulk_ship field of the config.fulfillment object to false.

  5. Enter your company’s return address in the return_address field of the config.fulfillment.shipping object.

Step two — Create your bulk card order

Create your bulk card order as specified on the Bulk Card Orders page, ensuring that you specify the following items:

  1. Specify your bulk shipping address in the fulfillment.shipping.recipient_address object. The following body fields are required:

    • first_name

    • last_name

    • address1

    • city

    • state (USA only)

    • postal_code

    • country

  2. Enter 0 in the card_allocation field.

  3. Include the user_association object with the single_inventory_user field set to false.

  4. Set the name_line_1_numeric_postfix field to false.

Step three — Create your authorized users

Create your users as documented on the Users page.

Step four — Create your cards

Create your cards as documented on the Cards page, ensuring that you enter the required user_token and fulfillment.card_personalization.text objects.

Ordering cards

Physical cards are automatically ordered upon card issuance if the following conditions are met:

  • The card product has a defined physical type in the payment_instrument field in the config.fulfillment object

  • The config.fulfillment object has both a valid fulfillment provider and a valid fulfillment package ID

  • The card is in the ISSUED or REISSUED state

  • The card has not yet been manufactured

If these conditions have been met, then the card is added to the fulfillment queue. Fulfillment cutoff times vary according to your fulfillment provider:

  • For Arroweye Solutions and Perfect Plastic Printing, the cutoff time is 09:00 UTC.

  • For IDEMIA, the cutoff time is 23:00 UTC.

Cancelling card orders

If your card order has not entered the fulfillment queue yet, you can transition the card to the TERMINATED state to cancel the order. For information about transitioning cards to different states, see Create card transition.

If your card order is in the fulfillment queue, you must contact Marqeta Support to determine whether your order can be cancelled.

Reordering cards

If your card order fails and is in the REJECTED state, you must create a new card for that user. If you want to use the same primary account number (PAN) for the new card, you can reissue the PAN from the existing card token. For more details about reissuing a PAN, see the reissue_pan_from_card_token field documentation on the Cards page.

Fulfillment status

When a card is fulfilled, the fulfillment_status and state_reason fields of the card object are updated. You can send a GET request to /cards/{token} to see these fields. Marqeta sends a webhook request for each transition that occurs for a given card.

Each fulfillment provider offers different shipping options for physical cards. If you choose a shipping option that offers a tracking number, such as UPS or FedEx, the tracking number will appear in the state_reason field of your card order. Be aware that most US Postal Service shipping options do not offer a tracking number.

Card fulfillment usually follows this timeline:

  1. Day 0: You place your card order prior to the cutoff time. The card is placed in the ISSUED state.

  2. Day 1: The card goes to ORDERED state by approximately 09:00 Pacific Time (UTC-08:00). The card is now being processed.

  3. Day 3: The card is shipped. If your fulfillment provider is IDEMIA, allow one additional day. The status of the card order is sent to Marqeta the following morning.

  4. Day 4: The card goes to SHIPPED state. The card shipping status and tracking information is sent to Marqeta this morning by approximately 03:00 Pacific Time (UTC-08:00).

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.